Single sign-on

Adding a provider#

Each entry in auth.oidcProviders needs an id, a display name, the issuer URL, and a client ID. It also needs a client secret, injected as an environment variable rather than set as a plain value:

global:
  dalpApp:
    config:
      auth:
        oidcProviders:
          - id: "fusionauth"
            displayName: "FusionAuth"
            issuer: "https://auth.example.com"
            clientId: "dalp"
            clientSecret: "${OIDC_PROVIDER_CLIENT_SECRET:-}"
            adminClaim: "dalp-admin"

Everything except clientSecret is plain configuration that you set directly in your values file. issuer must be an https:// URL, except for a loopback host reserved for local testing. Any other http:// issuer fails config decode when the pod boots, not when the chart installs. A render can succeed while the pod later fails config validation. An upgrade that waits for readiness can then time out. clientSecret is the one field you inject from a secret rather than set directly, through the OIDC_PROVIDER_CLIENT_SECRET environment variable or your configured secret-manager equivalent. Values and secrets shows how that injection reaches the running pod. Set it from a Kubernetes Secret, never as a literal in your values file or in a plain ConfigMap. An unencrypted values file lands the secret in Helm release history and in etcd, readable by anything with read access to Secrets or ConfigMaps in the namespace. Add more entries to the list to offer more than one provider at sign-in.

An entry only counts as a configured provider once id, issuer, clientId, and clientSecret all have real values. A partially filled entry parses without an error and changes nothing: local sign-in stays active, and no external sign-in option appears. This is deliberate. It stops a values file mid-edit, or a Secret that has not synced yet, from silently taking down local login.

Set two more fields on purpose rather than leaving their defaults:

• scopes requests the token claims the provider returns. When you omit it, the Console requests openid, email, and profile. Setting scopes replaces that default list and does not add to it. If you need a role or group claim for adminClaim, list openid, email, and profile alongside it, or sign-in fails on the missing email claim the platform relies on as the identity anchor.
• adminClaim names the claim, or the array a claim value must appear in, that grants the platform administrator role on sign-in. Leave it unset and no OIDC user ever becomes a platform administrator through this provider, which is the deny-by-default posture you want until you have scoped who at your identity provider can assign it. Anyone who can set that claim's value for a user at the identity-provider side can make that user a platform administrator the next time they sign in, because the role is recomputed on every login. Scope who can assign the claim before you set it, the same way you would scope a platform administrator grant inside DALP itself.

A complete entry disables local Console sign-in for the whole deployment#

One complete OIDC entry replaces local Console sign-in for every Console user on the deployment, from the moment the release that carries it rolls out. No per-user or per-organisation exception exists, and no in-band fallback exists: an operator who is locked out cannot sign in locally to fix the configuration.

The API enforces these restrictions as well as the Console. Calling a blocked credential flow directly does not bypass the restriction.

A first sign-in through OIDC does not adopt a pre-existing local account that shares the same email address. The platform refuses that sign-in, and the browser returns to the Console sign-in page. Returning users resolve by provider and subject, so only an account whose first sign-in came through the provider can sign in through it. Plan for this before rollout: a Console user who already holds a local account with the same email cannot sign in to the Console at all, because local sign-in is off and the provider sign-in is refused.

A platform administrator can delete that local account under “Platform admin”, “Platform users” only when nothing refuses the deletion: the account must not be an organisation's only owner or a wallet checker, must hold no tokens and must have no on-chain identity bound to it. After the deletion, the next provider sign-in creates a new account without the old account's memberships.

SSO centralises authentication at your identity provider, which gives you one place to enforce password policy and MFA and to stop new sign-ins. A Console session already open stays valid until it expires. The identity provider also becomes a single point of failure for reaching the Console.

Recovering from a lockout#

If a bad OIDC configuration locks every user out, redeploy with oidcProviders set to an empty list. Local email and password sign-in returns when the redeploy completes. Accounts first created through the provider have no local password, and because the instance already has accounts, a new local sign-up does not become a platform administrator. When no account with a password holds that role, Restore the platform administrator role gives it to one. To restore external sign-in instead, fix the provider configuration in a non-production environment, verify a full sign-in round trip there, then redeploy it to production.

What stays independent#

Three things do not follow the all-or-nothing rule:

• OIDC-based wallet verification is a separate capability from OIDC sign-in. It uses its own fields, apiKey and applicationId, on the same provider entry, and it does not gate whether local sign-in stays active.
  • It works only for an account that has signed in through that provider, because the platform finds the account at the provider by the identity linked at sign-in, never by email.
  • Without issuer, apiKey and applicationId, the provider's authenticator is not offered as a wallet factor.
  • The platform checks the code through the provider's user and two-factor APIs at the issuer URL (/api/user/{id}, /api/two-factor/start and /api/two-factor/login, the FusionAuth API), with apiKey as the credential. A provider that does not serve these routes cannot act as a wallet factor, even when its OIDC sign-in works.
  • The PIN, recovery codes and wallet authenticator keep working under single sign-on. Wallet verification describes the methods.
• A user's existing two-factor can still be turned off on the Console. Only enrolling a new login two-factor method is blocked there, alongside password and email changes. Wallet-signing two-factor is untouched regardless.
• Investor portal sign-in keeps its local methods, as the next section describes.

Investor portal sign-in under single sign-on#

The identity provider replaces sign-in on the Console only. The Investor portal keeps email and password sign-in, passkeys, password reset and two-factor enrolment for investors, including the email and text message sign-in codes their organisations allow. SSO also closes self sign-up on the Investor portal, so nobody can create a new account there. An account that holds the admin or owner role on the platform, or in an organisation that is not archived, cannot start an Investor portal session. The portal refuses it with 403 Forbidden and ADMINISTRATION_NEEDS_CONSOLE_SIGN_IN, and the message This account administers the platform or an organization, so it signs in to the Console through the identity provider.

Role writes that need a Console session#

The Platform API checks the app that issued a session before it accepts these writes, even when the caller's wallet holds the on-chain role:

• system, asset, offering, venue and custody gateway role grants and revokes
• changes to an asset's supply delegate, hold reserver, authorised converter and burner capability
• fixed-yield and offering fund withdrawals
• undeliverable-purchase refunds

These writes require a Console-issued session. A Portal-issued session, an anonymous session or one with no recorded issuing app answers 403 Forbidden with WALLET_ROLE_ADMINISTRATION_NEEDS_CONSOLE_SIGN_IN (DALP-200384), and starts no write. On the v1 API the same refusal answers 403 Forbidden with DALP-9485, whose message and fix also say to sign in to the Console. Sign in to the Console and retry. The check applies without an identity provider too, and sessions issued before the issuing app was recorded are refused until the user signs in to the Console again. This check does not end a Console session when access at the identity provider changes, revoke an on-chain role or disable an existing API key. API keys keep each route's existing access policy, and investors can still buy, claim and transfer their own holdings through the portal.

Production rollout checklist#

Before you roll a complete OIDC entry into a production instance:

• Stage and verify the full sign-in round trip in a non-production environment first. Include a user who should land as a platform administrator and one who should land as an ordinary member.
• Confirm your identity provider enforces multi-factor authentication for Console users. auth.enforce2fa stops applying to an account whose only sign-in is the identity provider.
• Confirm clientSecret, and apiKey if you also configure OIDC wallet verification, come from a Kubernetes Secret, never a values literal.
• Confirm adminClaim is set only if you intend OIDC users to reach the platform administrator role, and confirm who at your identity provider can assign that claim's value.
• Register the Console's callback URL with your identity provider before rollout: /api/auth/callback/<provider-id>, using the provider's id field and matching the exact host the Console serves from. A multi-host deployment needs the callback registered for each host.
• Confirm that whoever holds deploy access understands Recovering from a lockout before you roll the entry out.

Failure modes#

Related authentication settings#

These sit alongside oidcProviders in the same auth block. restrictOrgCreationToAdmin, membershipLimit, and walletTwoFactor apply the same way whether or not you configure OIDC. enforce2fa does not: it stops applying to an account whose only sign-in is the identity provider, because the provider then owns login authentication. An account that holds a password or a passkey, such as an investor on the Investor portal, still needs two-factor.

See also#

• Values and secrets for how a Kubernetes Secret reaches clientSecret and apiKey without touching the values file.
• Security for the sign-in code, transaction PIN and transaction code from a signed-in user's own account settings.
• Install the Helm charts for the redeploy command itself.

Frequently asked questions#