Set up SSO across your apps

Create a seamless single sign-on (SSO) experience across your apps. You can silently authenticate the user (without user interaction) if the user is already logged into any app in your tenant. This removes friction from the login process without compromising on security.

How it works

Your app can manage user sessions based on the local session created by the application, and the IDP session created by Transmit. When possible, users are granted access to the app without re-authentication based on an existing access token (if valid), or by obtaining a new access token using a valid refresh token. If no valid refresh token exists (or access tokens can no longer be refreshed since the IDP session has expired), your app will need to authenticate the user. See Session Management.

By layering session management with silent authentication, your app can re-authenticate the user without any user interaction based on a valid IDP session. Since an IDP session is shared across apps in the tenant, the session may have been created in the context of a different app, which provides the SSO login experience.

Here's an example of login logic that supports this, which begins with checking the local application session:

The diagram below illustrates the integration flow for a silent authentication process. When authentication is required, your app will first try to obtain an authorization code without prompting the user to authenticate, based on an existing IDP session. If there's no valid IDP session (i.e., the user is logged out), the user will need to actively authenticate.

For example:

Before you start

This solution relies upon both session management and silent authentication. Session management is used to login users without authentication based on an existing access token, or by obtaining a new one using a refresh token. Silent authentication should be requested only in case authentication is required, in order to provide a better user experience by performing an SSO login without any user interaction whenever possible.

The steps below describe how to implement silent authentication. Before you start, implement the session management flow described in Manage Sessions.

Note

Excessive silent authentication requests are subject to rate limits. Polling for session status isn't supported, and excessive calls should be avoided.

Step 1: Set session expiration

By default, IDP sessions expire after 1 year. You can set a custom expiration using resources (see Manage resources). You'll need to create a resource, set the session expiration for this resource, and then add it as a resource for each of your applications. This resource will need to be specified in each authentication request.

Step 2: Request silent auth

To support SSO across your apps, you'll need to ensure that the end-user won't be asked to re-authenticate if they're currently logged in (even if that login occurred in the context of another app). You can do this by first trying to perform a silent authentication to get an authorization code without prompting the user to authenticate.

To request silent authentication, send an OIDC authorization call like the one below with prompt set to consent (the consent will be granted automatically without user interaction) and with resource set to the URI of the resource created in Step 1.

Copy
Copied
curl -i -X GET \
  'https://api.userid.security/oidc/auth?client_id=CLIENT_ID&scope=openid&prompt=consent&response_type=code&redirect_uri=REDIRECT_URI&resource=RESOURCE_URI'

The response is one of the following:

  • If there is a valid session, the user is not prompted to authenticate and an authorization code is returned to your redirect URI in the code query parameter. This code should be exchanged for user tokens as part of the authentication flow implemented in step 3.
  • If there isn't a valid session, a login_required error is returned to the redirect URI in the error query parameter. The user will need to be prompted to authenticate as described in Step 3.
Note

To be able to perform a silent authentication, the session must satisfy all the requirements requested via acr_values; otherwise, an error will be returned and the user will need to authenticate. For example:

  • If MFA is requested, the session must satisfy the MFA requirements (see Use multi-factor authentication ).
  • If a specific authentication method is requested, the session must include an authentication with the requested method.

Step 3: Authenticate users

If silent authentication fails, you'll need to authenticate the user to obtain the authorization code, which is required to complete the login flow. You can do this using any of the supported authentication methods.

For a hosted login method like WebAuthn biometrics or social login, you can implement an OIDC-based integration. This involves configuring the relevant authentication method for the application (see OIDC guide), and sending an OIDC authorization request with prompt set to login (see OIDC guide).

Alternatively, you can implement any authentication method of your choice using the authentication guides.

Important

Make sure to request authentication for the resource created in Step 1, using the resource parameter.

Step 4: Logout users

When the user requests to logout from your app, the user should be logged out of the IDP session. This will ensure the session can no longer be used for an SSO login. You can use the logout step described in the OIDC guide, or use the logout API as shown below:

Copy
Copied
curl -i -X POST \
  'https://api.userid.security/v1/auth/logout' \
  -H 'Authorization: Bearer [TOKEN]'

where [TOKEN] is the access token you received upon successful authentication.