Configure OIDC clients

Use this guide to create an OIDC user authentication client for a web or native app. For backend-based authentication through Mosaic APIs or SDKs without an OIDC/SAML login flow, see Backend-based authentication.

Before you start

Create a Mosaic application for the client.
For OIDC login, prepare the redirect URIs that receive the authorization response.
Choose your login experience. For journey-orchestrated login, prepare an SSO journey and an SSO client group, or create the group inline.

In Applications > your app > Clients, click + Add client and select User authentication client. Follow the steps below for protocol-based OIDC authentication.

Step 1 - General

Field	Description
Client name	Client name to display when needed.
Client description	Short description of your client.

Step 2 - Authentication flow

Field	Description
Does your login use OIDC or SAML authentication?	Enabled by default. Leave it enabled for protocol-based authentication, then select OIDC or SAML. Disable it for backend-based authentication through Mosaic APIs or SDKs.
Protocol	Setting to OIDC defines that this client is OIDC-based.
Client type	Whether the client is a web app (default) or a native app (e.g., mobile). This is used to adapt validations and configuration according to client type when relevant (such as validations for redirect URIs).
Redirect URIs	List of URIs approved for redirects for your customer-facing application (e.g., URI to redirect to when an authentication is completed). The required format of the redirect URI depends upon client type: web clients must use HTTPS unless using a local environment, while native apps must use HTTPS unless using a local environment or custom scheme. Custom schemes are only allowed in the format of reverse domain schemes (`[domain]://[scheme]`).

Choose Journey-orchestrated or Application-controlled. For the journey-orchestrated path, select the required SSO client group and Journey. When the group uses Mosaic-hosted screens, select a Style or use the default Mosaic style. The journey and style are configured per client. See Choose your login experience.

For the path that skips this step, see Backend-based authentication.

Step 4 - Advanced settings

Field	Description
Enforce FAPI 2.0 compliance	For highly-regulated industries, consider enabling "Enforce FAPI 2.0 compliance". This will automatically disable client settings that aren't FAPI 2.0-compliant and prompt you to configure your client in accordance with FAPI principles, for example by enforcing mTLS, PKCE, and PAR. See FAPI 2.0.
Authentication method	Enforces client authentication using a specific method: Client Secret: (default) Allows authenticating using Client ID and Client Secret. For security purposes, the secret can be rotated later without changing the client ID. Private key JWT: Allows authenticating using client JWT assertion signed by your private key. If selected, provide JWKS. mTLS (self-signed): Allows leveraging an mTLS handshake for authentication. If selected, provide the self-signed certificate in the JWKS format. mTLS (CA-signed): Allows leveraging an mTLS handshake for authentication. If selected, provide the certificate chain in the PEM format. For requirements, see Authenticate using mutual TLS. Optionally, define Subject DN attributes (Common name (`CN`), Organization (`O`), and others) to enforce certificate validation against these values.
Enable token binding	Enabling this ensures that tokens are cryptographically bound to client certificate in the mTLS and private key JWT flows.
Enforce PAR	Enforces the usage of the PAR endpoint for auth requests. For implementation details, see Integrate login using PAR.
PKCE support	Whether the client requires the proof key of code exchange (PKCE) for authentication. For implementation details, see Secure login with PKCE. Allow PKCE alongside client credentials: (default) Allows auth requests with and without PKCE, provided that they use client credentials. Enforce PKCE alongside client credentials: Requires all authentication requests to include PKCE in addition to client credentials. Enforce PKCE instead of client credentials: Retrieves user access tokens only. For security reasons, Mosaic doesn't recommend using PKCE as a standalone method for authenticating users without the Client Secret.
Access token expiration	The access token time-to-live. By default, 60 minutes.
Refresh token expiration	The refresh token time-to-live. By default, 2 weeks.
Max refresh time	The maximum period of time when the refresh token can be rotated. By default, 2 weeks.
Session expiration	The validity period during which you can silently authenticate the session. By default, 8760 hours (1 year). This session is tied to the tokens issued to this client: it limits how long the client can renew tokens without a new login. It's separate from the session timeout of an SSO client group, which controls when users must sign in again across the group's clients.
Same Site	Defines the client cookie policy for requests made from a different site (cross-site). LAX: Allows Mosaic session cookies to be sent during standard navigation flows while blocking most cross-site requests (iframes and POSTs). This provides strong CSRF protection with minimal impact on typical sign-in experiences. None: Allows sharing Mosaic session cookies. This option can only be used for HTTPS redirect URIs.
Supported prompt values	List of OIDC prompt values to be enforced by the OIDC authorization server. Note that only selected prompt values can be included in the authorization requests, requests containing unselected prompt values will be rejected. Login: Forces the user to authenticate. Consent: Obtains user's consent. Required to obtain a refresh token. None: Checks for an existing session.
Resources	List of URIs the client can explicitly request access to. This allows the client to manage dedicated access for a resource, including the token expiration. For example, a website can have a shorter lifetime for the page used to manage the user's payment methods. Before a resource can be added to a client, it must first be created from the Resources tab of the Applications page (see Resources).
ID token — Pre-defined custom claims	Dropdown for selecting the claim values that Mosaic should return by default in the user's ID token. These claims do not need to be explicitly requested in the OIDC authorization request. Pre-defined ID token custom claim list is available below this table.
Return ID token claims on UserInfo as well	Checkbox that makes the UserInfo endpoint return the same default claims selected in ID Token - Pre-defined Custom Claims. When selected, User info - Pre-defined Custom Claims is disabled because UserInfo uses the ID token claim selection.
User info — Pre-defined custom claims	Dropdown for selecting the claim values that Mosaic should return by default from the UserInfo endpoint. These claims do not need to be explicitly requested during the OIDC flow. Pre-defined UserInfo custom claim list is available below this table.
ID token encryption	Allows encrypting ID tokens using the customer-provided key. Upload a JWKS containing an RSA public key (RSA-OAEP) and rotate it as necessary. Encrypted tokens will be returned in a JWE form.
Token exchange	Lets clients exchange user access tokens using OAuth 2.0 Token Exchange (RFC 8693). Both options are disabled by default. Initiate token exchange: Allows this client to call `/oidc/token` with the token exchange grant, as the exchanging client. Delegate tokens issued by this client: Controls which clients may exchange user access tokens issued to this client, as the source client. When enabled, choose All clients within the Application (every client in the same Mosaic application, including dynamically registered clients) or Specific clients / DCR Authorities (manually registered clients you select, and optionally Client authorities, so that clients registered through them can exchange tokens).

ID Token - Pre-defined Custom claims list

Click to open the list

tid: ID of the Mosaic tenant
fname: User's first name
lname: User's last name
mname: User's middle name
email: User's primary email
email_verified: Indicates if the user's primary email is verified
phone_number: User's primary phone number
phone_number_verified: Indicates if the user's primary phone number is verified
groups: Groups to which the user belongs
new_user: Indicates if a new user was created as part of the authentication flow
birthday: User's birthday as YYYY-MM-DD
language: The language of the user
city: User's city of residence
address: User's address
country: User's country of residence
street_address: User's street address
address_type: Type of user's address
webauthn: Returned only if WebAuthn was used
roles: List of role IDs assigned to the user
ts_roles: Transmit Security platform roles assigned to the user through Transmit Security RBAC. These are distinct from the Mosaic application-level roles in the roles claim
role_values: Main and custom roles assigned to the user
ts_permissions: Transmit Security platform permissions assigned to the user through Transmit Security RBAC. These are distinct from the Mosaic application-level permissions in the permissions claim
permissions: List of permissions delegated to the user
approval_data: Returned only in transaction signing flows. Contains approval-related transaction data
custom_group_data: Custom data object for group info
username: Username used to identify the user for password login
secondary_phone_numbers: List of user's secondary phone numbers
secondary_emails: List of user's secondary emails
picture: The picture of user, specified as a URL
created_at: Date user was created in the tenant
last_auth: Date user last authenticated
auth_time: Time the user was authenticated
external_account_id: User identifier in an app, set by the app
external_user_id: A unique identifier in a tenant
app_name: Name of the app the user is associated with
custom_data: Custom data object for tenant user info
custom_app_data: Custom data object for app-related user info

User info - Pre-defined Custom claims list

Click here to open the list

tid: ID of the Mosaic tenant
fname: User's first name
lname: User's last name
mname: User's middle name
email: User's primary email
email_verified: Indicates if the user's primary email is verified
phone_number: User's primary phone number
phone_number_verified: Indicates if the user's primary phone number is verified
groups: Groups to which the user belongs
new_user: Indicates if a new user was created as part of the authentication flow
birthday: User's birthday as YYYY-MM-DD
language: The language of the user
city: User's city of residence
address: User's address
country: User's country of residence
street_address: User's street address
address_type: Type of user's address
webauthn: Returned only if WebAuthn was used
roles: List of role IDs assigned to the user
ts_roles: Transmit Security platform roles assigned to the user through Transmit Security RBAC. These are distinct from the Mosaic application-level roles in the roles claim
role_values: Main and custom roles assigned to the user
ts_permissions: Transmit Security platform permissions assigned to the user through Transmit Security RBAC. These are distinct from the Mosaic application-level permissions in the permissions claim
permissions: List of permissions delegated to the user
approval_data: Returned only in transaction signing flows. Contains approval-related transaction data
custom_group_data: Custom data object for group info
username: Username used to identify the user for password login
secondary_phone_numbers: List of user's secondary phone numbers
secondary_emails: List of user's secondary emails
picture: The picture of user, specified as a URL
created_at: Date user was created in the tenant
last_auth: Date user last authenticated
auth_time: Time the user was authenticated
external_account_id: User identifier in an app, set by the app
external_user_id: A unique identifier in a tenant
app_name: Name of the app the user is associated with
custom_data: Custom data object for tenant user info
custom_app_data: Custom data object for app-related user info

Customizing claims

Claims such as org_id do not appear in these dropdowns. When authentication runs in the context of an organization, Mosaic adds org_id automatically to the ID token and UserInfo response.

To add custom key/value claims in journey flows, configure Enrich Access and ID Token or Enrich SSO Token in your journey.

Step 5 - Client roles

The last step lets you assign one or more client roles to the client.

Field	Description
Client roles	Assign one or more client roles to the client. If you don't select a role, the client implicitly receives the App Admin role. Exception: clients that were configured in the Admin Portal's SSO & Federation section, now deprecated, have no roles when none is assigned and can only perform authentication. To grant more permissions, assign client roles explicitly.
Client roles > + Add role	Opens the Add role flow: Step 1 - Details: enter the required Role name and optional Description. Step 2 - Setup: assign permissions from the permission tree under the Mosaic capability areas Identity management, Authentication, Platform Administration, and Fraud Prevention, each expanding into more granular categories. For more details, see Manage client roles.

Field

Description

Client roles

Assign one or more client roles to the client. If you don't select a role, the client implicitly receives the App Admin role. Exception: clients that were configured in the Admin Portal's SSO & Federation section, now deprecated, have no roles when none is assigned and can only perform authentication. To grant more permissions, assign client roles explicitly.

Client roles > + Add role

Opens the Add role flow:

Step 1 - Details: enter the required Role name and optional Description.
Step 2 - Setup: assign permissions from the permission tree under the Mosaic capability areas Identity management, Authentication, Platform Administration, and Fraud Prevention, each expanding into more granular categories.

For more details, see Manage client roles.

After saving

Complete the wizard and save the client. The client details page contains its credentials and configuration.

Important

Upon OIDC client creation, Mosaic will autogenerate a unique Client ID and Client Secret.

Client ID: Client identifier for API requests, automatically generated when the client is created. It cannot be edited.
Client Secret: Client secret used to authorize API requests on behalf of the client (either directly or by using it to generate client access tokens). It is automatically generated when the client is created, and you can rotate it later without changing the Client ID. During rotation, Mosaic can keep up to two active secrets so you can update your backend before revoking the old one.

Backend-based authentication

For user authentication through Mosaic APIs or SDKs without an OIDC or SAML login flow, select User authentication client, then turn off Does your login use OIDC or SAML authentication? in Authentication flow. The saved client is still an OIDC client.

This path uses General, Authentication flow, Advanced settings (step 3), and Client roles (step 4). It skips Login Experience. Configure the authentication method and token settings shown for this path, then assign the required client roles (see Step 5 - Client roles; on this path it's step 4). Enforce PAR is not available on this path; the protocol-based settings above do not all apply.

Follow the setup requirements in the guide for the authentication method you integrate. See Backend authentication.