Dex as IdP for OpenStack Keystone

Overview

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.

  • 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 StarlingX OpenStack 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: StarlingX OpenStack in a Subcloud and Dex in the Central Cloud

In this scenario, StarlingX OpenStack is deployed on the subcloud while Dex runs in the Central Cloud. The subcloud Horizon and Keystone RedirectURIs must be registered with the central Dex client.

Recommended: register RedirectURIs automatically.

Run the automation playbook on the System Controller active controller. The playbook discovers qualifying subclouds (online, managed, Dex-enabled, and StarlingX OpenStack-applied), registers the corresponding RedirectURIs in the central Dex client, and removes URIs for subclouds deleted from the Distributed Cloud. The playbook is idempotent; run it after adding a subcloud or after applying StarlingX OpenStack on a subcloud.

~(keystone_admin)$ ansible-playbook \
 /usr/share/ansible/stx-ansible/playbooks/configure_dex_dc_federation.yml \
 -e "openstack_app_name=[openstack-app-name]"

For the complete setup and verification flow, see Dex SSO Setup and Verification.

Alternative: register RedirectURIs manually.

If you need to register a RedirectURI, add it to the client used in config.staticClients of the Dex Helm overrides in the Central Cloud:

<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