Dex SSO Setup and Verification

Overview

This is an end-to-end procedure for setting up and verifying Dex-based SSO for StarlingX OpenStack Horizon and Keystone. It gives you a complete flow, together with a way to verify each component after applying StarlingX OpenStack.

The procedure applies to StarlingX OpenStack (a generic application-name placeholder such as stx-openstack is used in the commands), and covers all deployment types: standalone (AIO-SX, AIO-DX, and Standard) and Distributed Cloud subclouds, in one flow. Steps common to all deployments are shared; the Distributed Cloud RedirectURI registration (Ansible playbook) is the deployment-specific addition.

Prerequisites

All deployments:

  • oidc-auth-apps is applied and healthy (Dex pods running):

    ~(keystone_admin)$ system application-show oidc-auth-apps
~(keystone_admin)$ kubectl get pods -n kube-system | grep oidc-dex

  • endpoint_domain is configured on the node running StarlingX OpenStack:

    ~(keystone_admin)$ system service-parameter-list | grep endpoint_domain

  • HTTPS/TLS certificates are configured:

    ~(keystone_admin)$ system certificate-list

  • At least one identity provider connector is configured in Dex (LDAP, Active Directory, OIDC, SAML, or another supported connector):

    ~(keystone_admin)$ system helm-override-show oidc-auth-apps dex kube-system

Note

In a Distributed Cloud, StarlingX OpenStack runs on the subcloud, so endpoint_domain must be set on the subcloud. The System Controller does not run StarlingX OpenStack and does not require it; an empty value there is expected and harmless.

Distributed Cloud subclouds only:

  • oidc-auth-apps is applied on the System Controller (subclouds use the Central Cloud Dex).

  • oidc-auth-apps is uploaded (not applied) on the subcloud, so the StarlingX OpenStack Dex integration can enable federation.

Procedure

  1. Apply StarlingX OpenStack.

    ~(keystone_admin)$ system application-apply [openstack-app-name]

    Dex federation is enabled automatically when all prerequisites are met (no user overrides required). The apply configures:

    • Keystone federation identity provider (dex) and mapping

    • openid federation protocol

    • Keystone auth methods (mapped, openid)

    • trusted_dashboard entries

    • Horizon SSO settings

  2. Verify Dex SSO auto-configuration.

    Run these commands on the node running StarlingX OpenStack (the standalone system, or the subcloud in a Distributed Cloud). Source admin credentials first.

    • Identity provider (expect dex present, Enabled = True):

      ~(keystone_admin)$ openstack identity provider list

    • Mapping (expect dex_mapping present):

      ~(keystone_admin)$ openstack mapping list

    • Protocol (expect openid mapped to dex_mapping; if missing, SSO login will fail, see Troubleshooting):

      ~(keystone_admin)$ openstack federation protocol list --identity-provider dex

    • Auth methods (expect mapped and openid):

      ~(keystone_admin)$ kubectl exec -n openstack [keystone-api-pod] -c keystone-api -- \
 grep '^methods' /etc/keystone/keystone.conf

    • Trusted dashboard (expect the Horizon FQDN):

      ~(keystone_admin)$ kubectl exec -n openstack [keystone-api-pod] -c keystone-api -- \
 grep trusted_dashboard /etc/keystone/keystone.conf

    • Horizon SSO settings (expect WEBSSO_ENABLED = True and SECURE_PROXY_SSL_HEADER set for HTTPS):

      ~(keystone_admin)$ kubectl exec -n openstack [horizon-pod] -- \
 grep -E 'WEBSSO_ENABLED|SECURE_PROXY_SSL_HEADER' /etc/openstack-dashboard/local_settings

  3. Configure federated user access.

    Dex-authenticated users are mapped into the federated_users group (per dex_mapping). By default this group has the member role on the federation project only. Assign roles and projects appropriate to your security requirements:

    ~(keystone_admin)$ openstack group show federated_users -f value -c id
~(keystone_admin)$ openstack role assignment list --group [group-id] --names
~(keystone_admin)$ openstack role add --group federated_users --project [project] [role]

    Note

    Customizing how federated users map to groups, projects, or roles is standard OpenStack Keystone federation configuration. For advanced mapping scenarios, refer to the upstream OpenStack Keystone federation documentation. See also RBAC for Dex Users.

  4. Register RedirectURIs with Dex.

    Standalone systems (Dex runs locally): RedirectURIs are registered automatically when StarlingX OpenStack is applied. No manual step is required.

    Distributed Cloud subclouds (Dex on the System Controller): Run the automation playbook on the System Controller active controller:

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

    The playbook discovers qualifying subclouds (online, managed, Dex-enabled, StarlingX OpenStack-applied), reads each subcloud’s external Horizon and Keystone endpoints, 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.

  5. Verify end-to-end SSO login.

    1. Open Horizon at the Horizon URL for the system (the subcloud URL for a Distributed Cloud).

    2. Select the Dex SSO option and sign in.

    3. Authenticate with your identity provider credentials on the Dex page.

    4. Confirm the federated user lands in the assigned projects.

    Where the login fails indicates which piece to check: a failure before the`` Dex page points to Horizon SSO; a redirect URI error points to Register RedirectURIs with Dex Step; a rejection at Dex points to the connector or credentials; an authorization error after return points to Configure federated user access Step.

Troubleshooting Dex SSO Login Issues

Use the verification commands above to isolate which component is misconfigured, then match the symptom below.

The Dex SSO option does not appear on the Horizon login page

  • Cause: WEBSSO_ENABLED is not set, or the StarlingX OpenStack apply did not enable federation.

  • Resolution: Verify the Horizon SSO settings; confirm StarlingX OpenStack applied successfully with all prerequisites met.

Redirected to Dex, but Dex shows an unregistered or invalid redirect URI error

  • Cause: The Horizon or Keystone callback URI is not registered in the Dex client.

  • Resolution: On standalone, confirm StarlingX OpenStack applied. On Distributed Cloud, run the playbook on the System Controller (Step 4).

The Dex login page does not load or cannot reach Dex

  • Cause: Keystone ingress or Dex connectivity issue, or DNS resolution of the endpoint domain.

  • Resolution: Verify the Dex pods are running; confirm the endpoint domain resolves and TLS certificates are valid.

Authentication is rejected at the Dex login page

  • Cause: The identity provider connector is misconfigured, or the credentials are wrong.

  • Resolution: Verify the connector configuration in Dex; confirm credentials with your identity provider.

Login returns “not a trusted dashboard host” (HTTP 401)

  • Cause: trusted_dashboard does not include the Horizon URL.

  • Resolution: Verify trusted_dashboard; confirm endpoint_domain is set correctly and StarlingX OpenStack was re-applied.

Login succeeds at Dex but Horizon shows an authorization or permission error

  • Cause: The federated user has no role on any usable project.

  • Resolution: Assign the group appropriate roles and projects (Step 3).

The openid federation protocol is missing from the protocol list

  • Cause: The StarlingX OpenStack apply did not complete the federation setup.

  • Resolution: Confirm the StarlingX OpenStack apply reached applied status; re-apply if the configuration is incomplete.

The SSO click returns HTTP 500

  • Cause: Keystone OIDC session or cache error.

  • Resolution: Check the keystone-api pod logs for cache or session errors.

General diagnostic steps:

  • Re-run the verification checks and confirm each item matches the expected output.

  • Check the Keystone API pod logs for federation errors and grep for federation, oidc, or websso:

    ~(keystone_admin)$ kubectl logs -n openstack [keystone-api-pod] -c keystone-api

  • Check the Dex pod logs on the Dex host (the standalone system or the System Controller):

    ~(keystone_admin)$ kubectl logs -n kube-system [oidc-dex-pod]

  • Confirm the browser is not caching a previous failed session; retry in a private or incognito window.

Results

Federated users can log in to StarlingX OpenStack Horizon through Dex SSO, authenticate with their identity provider credentials, and access the projects and roles assigned to their federated group without requiring a separate local Keystone account.