Dex as IdP for OpenStack Keystone

About this task

This documentation describes the support for using ‘platform’ oidc-auth-apps (Dex OIDC Proxy IdP) for authentication of ‘openstack’ Horizon and ‘openstack’ APIs/CLIs. In this integration, StarlingX OpenStack Keystone delegates user authentication to Dex, while authorization, project scoping, and access control remain managed inside StarlingX OpenStack.

Keystone Federation using StarlingX oidc-auth-apps (Dex) is enabled by default. For more details, see Introduction to Keystone Federation.

When enabled:

• StarlingX oidc-auth-apps (Dex) is automatically registered as the federated IDP for openstack keystone.

  • and StarlingX oidc-auth-apps (Dex) is automatically configured with StarlingX Local LDAP as its backend IdP; although additional backend IDPs can be configured.

• Default federation mapping is applied

• Required resources are created automatically:

  • Group

  • Project

  • Role and role assignment

  • Federation protocol

Note

No manual StarlingX OpenStack CLI steps are required for most deployments. However, certain deployment types may require additional Helm user overrides for SSO to function correctly. For details on when these overrides apply, see User Overrides for DC Subclouds and HTTPS Deployments.

• Horizon shows “Login with oidc-auth-apps (Dex) SSO”

• Users authenticated via Dex:

  • Are identified by email

  • Are added to a default group

  • Receive access to a default project

  Note

  See RBAC for Dex Users for more details on keystone group and keystone project/tenant.

To verify if Dex was successfully enabled:

1. Open Horizon

2. Click “Login with oidc-auth-apps (Dex) SSO”

3. Successful login confirms configuration

Dex Identity Provider Configuration - federation.dex_idp

The Dex Identity Provider overrides defines how Dex is registered and consumed by Keystone federation.

These overrides control:

• Whether Dex federation is enabled

• Identity Provider registration

• Federation protocol and mappings

• Horizon WebSSO exposure

Except where explicitly stated, the values below are defaults and should only be changed when customization is required.

The values below are the Helm overrides for the openstack keystone Helm chart:

conf:
    federation:
        wsgi:
            ...
        dex_idp:
            enabled: false
            provider_name: "dex"
            provider_remote_id: "https://<oam-floating-ip>:30556/dex" # This IP is the one used in the DEX configuration
            protocol_name: "openid"
            group_name: "federated_users"
            project_name: "federation"
            mapping_name: "dex_mapping"
            websso_label: "Login with DEX SSO"
            websso_initial_choice: "credentials"
            claim_groups: false
            groups: []
            groups_mapping: |
            ...
            default_mapping: |
                [{
                "local": [{
                    "user": {"name": "{0}"},
                    "group": {"name": "{{ .Values.conf.federation.dex_idp.group_name }}", "domain": {"name": "Default"}}
                }],
                "remote": [{"type": "OIDC-email"}]
                }]

In the default configuration with the claim_groups: false all users are set as federated_users in project_name: "federation" with the role: "member". However, if you want to set claim_groups: true you need to define the groups mapping, projects and roles in the overrides, for more details see RBAC for Dex Users.

To update the Helm overrides values above you can create a keystone-overrides.yaml to add your configurations:

~(keystone_admin)$ system helm-override-update wr-openstack keystone openstack --reuse-values --values keystone-overrides.yaml
~(keystone_admin)$ system application-apply wr-openstack

Advanced Usage (optional)

By default bootstrap is set to “true”. When enabled: true the mappings are configured by default for both claim_groups: true and claim_groups: false.

The bootstrap should only be disabled if you want to manually create the mappings, groups, and projects for OIDC users and groups.

To manage federation manually go to the Helm overrides, create a keystone-overrides.yaml as described above and set:

conf:
  federation:
    bootstrap:
      enabled: false

Dex Scenarios

Scenario 1: Dex and |prod-os| in the Same Subcloud

This scenario works automatically with the configurations applied during the StarlingX OpenStack deployment.

Enabling of StarlingX oidc-auth-apps (Dex) as the federated IdP for openstack keystone is automatically applied if following conditions are met:

• It is not set manually to false.

• The OIDC parameters set by default:

  • on standalone and systemController, to point to local Dex

  • on subcloud, to point to SystemController’s Dex

  For this scenario, you have to reset the OIDC parameters to point to local Dex.

• Dex status is healthy.

• The endpoint domain is configured. To check if the endpoint_domain exists run:

  ~(keystone_admin)$ system service-parameter-list
  

RedirectURI configurations are automatically added to Dex.

Scenario 2: |prod-os| in a Subcloud and Dex in the Central Cloud

This scenario works, but requires manual configuration.

After StarlingX OpenStack is deployed on the subcloud, the required RedirectURI overrides are not automatically applied to Dex in the Central Cloud.

You must manually configure the Dex Helm overrides in the Central Cloud to add the StarlingX OpenStack Horizon RedirectURI for each subcloud where StarlingX OpenStack is installed.

Manually add a new RedirectURI:

<WRO-KEYSTONE-EXTERNAL-URL>/v3/auth/OS-FEDERATION/identity_providers/dex/protocols/openid/websso/redirect
This RedirectURI must be added to the client used in config.staticClients.
Example:

config:
  staticClients:
  - id: stx-oidc-client-app
    name: STX OIDC Client app
    redirectURIs:
    - http://keystone.openstack.svc.cluster.local/v3/auth/OS-FEDERATION/identity_providers/dex/protocols/openid/websso/redirect
    - https://10.20.9.3:30555/callback
    secret: St8rlingX

To update the overrides values above create an oidc-overrides.yaml file to add your configurations.

~(keystone_admin)$ system helm-override-update oidc-auth-apps dex kube-system --reuse-values --values oidc-overrides.yaml
~(keystone_admin)$ system application-apply oidc-auth-apps

User Overrides for DC Subclouds and HTTPS Deployments

On StarlingX OpenStack deployments, additional Helm user overrides may be required for DEX SSO to function correctly, depending on your deployment type.

Keystone override (DC subclouds only)

Apply the following Keystone user override on Distributed Cloud subclouds:

conf:
  federation:
    dex_idp:
      enabled: true
  keystone:
    auth:
      methods: external,password,token,mapped,application_credential,openid

On DC subclouds, DEX auto-enablement updates the Keystone chart’s system_overrides, but the is_dex_enabled() check evaluates only user_overrides. As a result, the required auth.methods entries (mapped, openid) are not generated unless this override is explicitly provided. The explicit auth.methods list also ensures that the application_credential authentication method remains enabled.

Horizon override (any HTTPS deployment)

Apply the following Horizon user override on any StarlingX OpenStack deployment where HTTPS is enabled:

conf:
  horizon:
    local_settings:
      config:
        raw:
          SECURE_PROXY_SSL_HEADER: '["HTTP_X_FORWARDED_PROTO","https"]'

This override is required for standalone systems, system controllers, and subclouds when TLS is terminated at the ingress. The 26.03 Horizon plugin does not automatically configure SECURE_PROXY_SSL_HEADER when HTTPS is enabled. Without this setting, Horizon detects the request scheme as http, causing the DEX SSO token POST request to be redirected from HTTP to HTTPS and lost during the 301 redirect.