Manage clients

You can manage clients using Application APIs (with an access token of the relevant app or with an admin access token) or Client APIs (with an access token of the relevant app), or from the Admin Portal (as described below).

Depending on your business needs, Mosaic allows creating OIDC and SAML clients.

• OIDC clients are designed for apps relying on the OIDC protocol for authentication and authorization.
• SAML clients are designed to support identity federation with external IDPs using the SAML protocol.

OIDC clients are versatile and are considered to be default for Mosaic integrations—you can build any identity experience (authentication, fraud prevention, identity verification, etc.) with an OIDC client. SAML clients can only be used with SSO Service and Hosted login.

You can manage clients from the Application page:

• Create a client by clicking + Add client and configuring its settings.
• Edit a client by clicking and then Edit.
• Delete a client by clicking and then Delete.

Complete the wizard by configuring client settings. Some of these settings are common for all client types and configurations, while others are specific to the protocol (OIDC in this case) and derive from other settings.

• Protocol: Setting to OIDC defines that this client is OIDC-based.
• Third-party client: Enabling the toggle marks the client as third-party. With the right consent, third-party clients that represent external services can request access to your protected resources on behalf of the user.
• Client name: Client name to display when needed.
• Client description: Short description of your client.

• 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 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]).

• 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. See Rotate client secrets.
  • 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.

• Enforce 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.

• SameSite: 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.

• 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.

  See the available claims list

  Claim	Description
  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 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 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

• 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.

  See the available claims list

  Claim	Description
  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 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 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

• 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.

• 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.

• Token timeout configuration: Allows modifying default token expiration times:

  • 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, 2 weeks, and can be configured up to 1 year.

• Third-party client settings: Defines configuration settings for external services (if third-party client is toggled):

  • Consent redirect URL: List of URIs for obtaining user consent (e.g., URI to redirect to when a third-party client requests access to user data). These pages should be managed by the first-party client.
  • Access validity period: Currently, set to 30 days.
  • Scopes / permissions: List of resources the third-party client is allowed to access on behalf of the user in the app. Third-party clients typically have limited control over user data.

Grant granular access to Mosaic by assigning roles to a client. Pick one or more roles from the list or create a new role. If you don't specify a role, the client will be assigned an implicit role that grants global access to Mosaic APIs. For details, see Manage client roles.

Complete the wizard by configuring client settings. Some of these settings are common for all client types and configurations, while others are specific to the protocol (SAML in this case).

• Protocol: Setting to SAML defines that this client is SAML-based.
• Client name: Client name to display when needed.
• Client description: Short description of your client.

• Service provider (SP) ACR URL: The endpoint where SAML responses containing authentication assertions are sent after the user successfully logs in. This URL must be configured accurately to ensure that the authentication data is received and processed by the intended application.
• Service Provider (SP) Entity ID: ID that uniquely identifies the service provider within the SAML framework. This is crucial for ensuring that the SAML responses are directed to the correct client application, maintaining the integrity and security of the authentication process.

• NameID: The type of primary identifier to be used. Can be one of the following: email, phone number, username, or external user ID.
• Sign SAML assertion: Enable signing the SAML assertions in addition to signing the SAML response.
• Allow the ACS URL to be optional in SAML requests: Make ACS URL not mandatory.