# SSO sign-in (OIDC)

Source: https://docs.settlemint.com/docs/developers/sso-oidc
Configure an external OpenID Connect identity provider as the sign-in method for a DALP deployment, with FusionAuth as the worked example.



DALP can delegate account sign-in to an external OpenID Connect (OIDC) identity provider. Configuration is provider-neutral: the same `auth.oidcProviders` block works against FusionAuth, Okta, Auth0, or any standards-compliant OIDC issuer. No provider is special-cased in code. This section uses FusionAuth as the worked example because it surfaces the two integration requirements operators most often miss: the `name` claim source and how provider roles reach the token DALP reads.

This section covers the overview, enablement model, claim requirements, and sign-in flow. Related pages: [Configure an OIDC provider](/docs/developers/sso-oidc/configure-provider), [FusionAuth setup](/docs/developers/sso-oidc/fusionauth-setup), [Deploy OIDC in production](/docs/developers/sso-oidc/deploy-production), [Troubleshooting](/docs/developers/sso-oidc/troubleshooting), and [Authentication](/docs/compliance-security/security/authentication).

## Enablement is all-or-nothing [#enablement-is-all-or-nothing]

DALP treats the configured provider list as a deployment-wide switch for sign-in. A provider counts as configured for sign-in only when its `id`, `issuer`, `clientId`, and `clientSecret` are all set; partially-filled entries are ignored.

When at least one provider is fully configured for sign-in, the external IdP becomes the sole login method. The platform disables local email and password sign-in server-side and rejects passkey sign-in paths. No in-band fallback exists: recovery from a misconfigured provider requires a redeploy with an empty provider list (see [Deploy OIDC in production](/docs/developers/sso-oidc/deploy-production)).

<Mermaid
  chart="`
flowchart TD
Cfg[&#x22;auth.oidcProviders[]&#x22;] --> Filter[&#x22;Configured providers<br/>(id + issuer + clientId + clientSecret all set)&#x22;]
Filter -->|&#x22;none configured&#x22;| Local[&#x22;Local login ON<br/>email/password + passkey&#x22;]
Filter -->|&#x22;one or more configured&#x22;| SSO[&#x22;SSO only<br/>email/password disabled<br/>passkey paths rejected<br/>implicit account-linking off&#x22;]
`"
/>

<Callout type="warning" title="Configuring a provider for sign-in disables local login">
  Configuring a provider for sign-in (a complete `clientId` + `clientSecret`
  entry) removes email/password and passkey sign-in for the whole deployment.
  Verify the provider end-to-end in a non-production environment before enabling
  it where operators depend on access. OIDC wallet verification configuration
  (see below) does not have this effect.
</Callout>

## Beyond sign-in: OIDC wallet verification [#beyond-sign-in-oidc-wallet-verification]

Sign-in is not the only place DALP uses an OIDC provider. The same provider can back OIDC wallet verification: when a signing request declares the `OIDC_MFA` verification method, the platform runs a server-side TOTP check against the provider and treats success as authorization for that one signing operation. OIDC wallet verification sits alongside PIN, OTP, and recovery codes as a way to authorize signing, and does not replace sign-in.

OIDC wallet verification is enabled separately from sign-in, through different fields (`apiKey` and `applicationId`). Configuring it does not disable local login. A deployment can pair it with local password sign-in or with OIDC sign-in. The two capabilities are independent.

In this version, `OIDC_MFA` is available to API and SDK callers that supply it in a request's `walletVerification`. The Console does not offer it as a selectable method. Configure it in the [OIDC MFA enablement predicate](/docs/developers/sso-oidc/configure-provider), set up FusionAuth in [FusionAuth setup](/docs/developers/sso-oidc/fusionauth-setup), and map its failures in [Troubleshooting](/docs/developers/sso-oidc/troubleshooting).

## What the provider must supply [#what-the-provider-must-supply]

DALP reads the user profile from the provider's ID token (falling back to the userinfo endpoint only when the ID token lacks a subject or email). Three claims drive sign-in and authorization.

| DALP need               | Source claim                                                                                               | What happens if it is missing or wrong                                |
| ----------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| Display name (required) | `name`                                                                                                     | Sign-in fails: the platform cannot create the account without a name. |
| Identity anchor         | a verified `email`                                                                                         | An explicit `email_verified: false` is rejected by design.            |
| Platform admin          | the `adminClaim` value inside a `roles` or `groups` array, or a direct boolean claim named by `adminClaim` | The user signs in as a regular member.                                |

Admin assignment is deny-by-default: when `adminClaim` is empty, the platform never promotes a profile to platform admin. The role re-derives on every login, so changing a user's claim at the IdP promotes or demotes them on their next sign-in.

## How sign-in flows [#how-sign-in-flows]

<Mermaid
  chart="`
sequenceDiagram
participant U as Browser
participant D as DALP (better-auth)
participant I as OIDC provider
U->>D: Click &#x22;Sign in with provider&#x22;
D->>I: Redirect to authorization endpoint (PKCE, scopes)
Note over I: invalid_redirect_uri if the callback URL is not registered
I-->>D: Callback with authorization code
Note over D: issuer_missing if RFC 9207 issuer validation is on<br/>and the provider omits the iss parameter
D->>I: Exchange code for ID token (and access token)
D->>D: Map profile claims to the DALP user
Note over D: name_is_missing if no name claim<br/>email_is_missing if email_verified is false<br/>role is member if the admin claim is absent
D-->>U: Session created; role admin or member
`"
/>

Each labelled failure has a cause and fix in [Troubleshooting](/docs/developers/sso-oidc/troubleshooting).

## Next steps [#next-steps]

* Map every configuration field and its environment variable in [Configure an OIDC provider](/docs/developers/sso-oidc/configure-provider).
* Follow the end-to-end [FusionAuth setup](/docs/developers/sso-oidc/fusionauth-setup).
* Plan the rollout with [Deploy OIDC in production](/docs/developers/sso-oidc/deploy-production).