FusionAuth setup

Create the OIDC application

Create a FusionAuth application (or reuse an existing one), enable the Authorization Code grant on its OAuth configuration, and note the client ID and client secret. You will set these in DALP config.

Register the redirect (callback) URL

Add DALP's callback URL to the application's authorized redirect URLs (OAuth configuration). The callback path is:

https://<dapp-host>/api/auth/oauth2/callback/<provider-id>

<provider-id> is the id you will set in DALP config (for example fusionauth). Add the full URL for every host the Console serves. A host that is not registered fails the sign-in with invalid_redirect_uri, and local deployments behind a per-branch host must register each host they answer on.

Confirm the requested scopes

DALP requests openid email profile by default. FusionAuth returns email and name for these scopes once the user's profile is populated (next steps). No extra scope configuration is required for the default setup.

Create the admin role and assign it

Create an application role whose name matches the adminClaim you will configure in DALP (this guide uses dalp-admin).

Assign it by giving the user a registration for the DALP application with the dalp-admin role selected. Only registered users that hold the role carry it in their token.

Set the user's full name (required for the name claim)

FusionAuth derives the OIDC name claim from the full name field on the account record. A user with only first and last name set, but no full name set, produces a token without a name claim. DALP sign-in then fails with name_is_missing. Set the full name on the profile and confirm it is populated for every user who will sign in.

Add a lambda to put roles in the ID token

By default FusionAuth includes application roles in the access token only. DALP reads the ID token, so the admin role never arrives. The user signs in as a member. Create a JWT Populate lambda that copies the registration roles into the token, then assign it to the application's ID token populate slot.

function populate(jwt, user, registration) {
  if (registration && registration.roles) {
    jwt.roles = registration.roles;
  }
}

The lambda writes roles as an array, which is exactly the shape DALP's admin-claim resolver looks for (dalp-admin inside a roles array). Confirm the populate signature against your FusionAuth version, because the lambda contract has varied across releases.

Wire the provider into DALP

Add the provider to auth.oidcProviders, setting requireIssuerValidation: false because FusionAuth lacks RFC 9207 support.

auth:
  oidcProviders:
    - id: fusionauth
      displayName: FusionAuth
      issuer: http://localhost:9011
      clientId: ${OIDC_PROVIDER_CLIENT_ID:-}
      clientSecret: ${OIDC_PROVIDER_CLIENT_SECRET:-}
      adminClaim: dalp-admin
      requireIssuerValidation: false

For production, inject clientId and clientSecret from the environment or a secret store rather than committing them, and use an https:// issuer. See Deploy OIDC in production.

Restart and verify

DALP reads provider configuration at boot, so restart the stack after changing config. Then open the Console sign-in page. Only the Sign in with FusionAuth button should appear, because local login is now disabled. Complete the sign-in: a user holding dalp-admin lands as a platform admin, and everyone else as a regular member. If the round-trip or role is wrong, see Troubleshooting.

Add a server API key

During verification the platform calls FusionAuth server-to-server: it reads the user (/api/user) and runs the two-factor flow (/api/two-factor/start, then /api/two-factor/login). Create an API key and set OIDC_PROVIDER_MFA_API_KEY to its value.

A super-user key (no endpoint restrictions) is the simplest choice. If you restrict the key to specific endpoints, note that /api/two-factor/login is a public authentication endpoint that does not appear in the API-key endpoint list, so a key limited to only the OIDC MFA endpoints rejects the login call. Keep the key in a secret store; never commit it.

Enable the authenticator factor on the tenant

OIDC wallet verification uses a time-based one-time password (TOTP) authenticator. Enable Authenticator as a multi-factor method on the FusionAuth tenant. Without it no user can enroll a factor, and every verification attempt returns USER_MISSING_2FA.

Enroll each user's authenticator

Each user who authorizes signing must hold an enrolled authenticator factor. Enroll it from the user's profile or through your own enrollment flow. The platform looks the user up by the email on their session, so that email must match a FusionAuth user that holds an authenticator factor.

Add the verification fields to DALP config

Add apiKey and applicationId to the provider entry. applicationId is the FusionAuth application id (the same value as clientId).

auth:
  oidcProviders:
    - id: fusionauth
      displayName: FusionAuth
      issuer: http://localhost:9011
      clientId: ${OIDC_PROVIDER_CLIENT_ID:-}
      clientSecret: ${OIDC_PROVIDER_CLIENT_SECRET:-}
      adminClaim: dalp-admin
      requireIssuerValidation: false
      apiKey: ${OIDC_PROVIDER_MFA_API_KEY:-}
      applicationId: ${OIDC_PROVIDER_MFA_APPLICATION_ID:-}

For a verification-only provider with no OIDC sign-in, set issuer, apiKey, and applicationId, and leave clientId and clientSecret empty.

Restart and verify

Restart the stack so the platform re-reads the provider configuration. A signing request that declares OIDC_MFA with a current authenticator code now authorizes through FusionAuth. If it fails, the Troubleshooting page maps each OIDC MFA error to its cause and fix.