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.

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:

Open Horizon
Click “Login with oidc-auth-apps (Dex) SSO”
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