Institutional Vault authenticates users through your organization's OIDC-compatible identity provider (IdP). Configure the IdP before installing the wallet so callback URLs and client identifiers match the hostnames you deploy.

Vendor-specific steps:

• Auth0 IdP Configuration
• Okta IdP Configuration
• Entra IdP Configuration

What you must create

Create two OIDC application (client) registrations in your IdP, plus an API / resource that defines the audience for Vault API access tokens.

Also record the IdP issuer URL (no trailing slash). The wallet discovers OIDC metadata from \{issuer\}/.well-known/openid-configuration.

📘

Note:

Some deployments also use machine-to-machine (client-credentials) clients for Canton Participant, Validator, or Gateway APIs. Those audiences are separate from the Vault SPA and Native clients described here.

SPA client (Vault UI)

Create a Single Page Application (or equivalent public web client) for the Vault frontend.

• Grant types: Authorization Code with PKCE (and refresh tokens if your IdP requires them for the SPA session model).
• Redirect / callback URI: your Vault UI origin plus the login callback path, for example https://wallet.yourcompany.com/login/callback (exact path can vary by IdP guide).
• Logout / post-logout redirect: Vault UI origin (for example https://wallet.yourcompany.com).
• Web origins / CORS: Vault UI origin when the IdP requires it.
• Client authentication: public client (no client secret).

Supply the SPA Client ID to the wallet OIDC SPA client setting at install time.

Native client (ApproverApp)

Create a Native (public) application for ApproverApp on mobile and desktop.

• Grant types: Authorization Code with PKCE; refresh token as required by your IdP.
• Redirect / callback URIs (register both form factors):
  • Mobile ApproverApp: com.blockdaemon.reactnativeapproverapp://callback
  • Desktop ApproverApp: app://./callback
• Logout URIs: the same deep links when the IdP requires logout redirects.
• Client authentication: public client (no client secret).

Supply the Native Client ID to:

1. The wallet OIDC native client setting (client_id_native).
2. Each Policy Node [[OIDCConfig]].ClientID entry used for ApproverApp onboarding.

Approver onboarding validates the ID token. Policy Node ClientID must match the ID token aud (or one element when aud is an array). For many IdPs that is the Native application Client ID.

🚧

Caution:

Some IdP tenants reject empty-host schemes such as app://./callback. Validate Desktop ApproverApp redirect URIs in your tenant before go-live. Auth0-style tenants may use a different deep-link format for mobile; follow the vendor guide for that IdP.

API audience and issuer

Create an API or authorization-server resource that defines the audience claimed on access tokens for the Vault API. SPA and Native clients must be allowed to request tokens for that audience (and scopes such as openid, email, and profile as required).

Collect before install:

Map these into your deployment secrets (for example the Auth0-shaped AUDIENCE, ISSUER, CLIENT_ID_SPA, CLIENT_ID_NATIVE block, or the equivalent keys your installer expects). See Cloud-agnostic Install Guide for wallet.yaml oidc_static_config and Policy Node [[OIDCConfig]] examples.

Identity claim

Vault uses the JWT email claim as the user identifier for onboarding and operations. Prefer a stable email claim on tokens issued for Vault.

When an access token used against the Vault API has no email claim, the wallet resolves email from the IdP UserInfo endpoint discovered at \{issuer\}/.well-known/openid-configuration (same Bearer token; result cached by sub).

ApproverApp onboarding still requires email on the ID token presented to Policy Nodes. That path does not call UserInfo. If ID tokens omit email_verified, Policy Nodes may need AllowUnverifiedEmail enabled for your IdP.