One Time Login Tokens – Unidy Documentation

This document outlines the use of the feature: One-Time Login Tokens.

This feature enables a seamless session-bridging experience, allowing a user who is already authenticated in one application (e.g., a native mobile app) to be automatically logged into a separate third-party service without re-entering their credentials.

The process leverages a user's existing session, established through e.g. the OIDC Authorization Flow requesting an Authorization Code with PKCE, to generate a single-use token. This token is then used to initiate a new OIDC flow with a third-party service, effectively bridging the user's session between the two environments.

The Flow: A Step-by-Step Guide

The session bridging process with a One-Time Login Token follows a specific sequence of events, as detailed below.

Step 1: Initial Authentication

The user must first be signed into your application. This is done via the standard OIDC Authorization Flow requesting an Authorization Code with PKCE , which is a secure and recommended method for public clients like native apps. The successful completion of this flow provides your application with an access_token for the authenticated user.

☝️ That access_token needs to have the scope one_time_login_tokens:write.

Step 2: Generating the One-Time Login Token

Once your application has a valid access token for the user, it can make a call to our SSO API to generate a One-Time Login Token. This API call must be authenticated with the user's access token.

The API endpoint for generating the token can be found in the API documentation of you own Unidy instance (or here). The call looks like

curl -XPOST 'https://xxx.unidy.de/api/v1/one_time_login_tokens' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: bearer <access_token>' \
  --data '{
  "client_id": "<client_id>",
  "redirect_uri": "https://target.example.com",
  "scopes": ["openid"]
}'

Upon a successful request, our API will return a JSON response containing the login token:

{
  "token": "4673acb8-9c8a-48af-abe2-9166ca568ab2"
}

‼️ The lifetime of that token is 10 seconds.

Step 3: Redirecting the User

Your application must now redirect the user to your Unidy instance. This redirect is done by constructing a URL that includes the login token as a query parameter.

The redirect URL has the following format:

https://xxx.unidy.de/one_time_login?token=4673acb8-9c8a-48af-abe2-9166ca568ab2

Your application should open this URL in the user's web browser.

You can optionally pass a redirect_url to overwrite the redirect_uri that was specified during the token creation. Note that the user will be logged in at https://xxx.unidy.de after finishing this step.

If you want to generate the redirect_uri at this stage, you can also pass the redirect_uri directly as an additional query parameter.

https://xxx.unidy.de/one_time_login?token=4673acb8-9c8a-48af-abe2-9166ca568ab2&redirect_uri=xxx

Step 4: SSO Instance Authentication and Redirection

When the user's browser is redirected to our SSO instance with the login token, the following actions occur:

Unidy validates the token.

If the token is valid, the user is automatically logged in to the Unidy instance.

The token is immediately invalidated, preventing it from being used again.

Unidy then initiates a new OIDC flow to the third-party service specified during the token creation. Since the user is already authenticated with us, this process is seamless.

Currently, we only support the id_token flow for this session bridging. The SSO instance generates an id_token for the third-party service and redirects the user's browser back to the redirect_uri you provided in Step 2.

The final redirect URL to the third-party service will contain the id_token as a fragment. For example:

https://third-party.com/callback#id_token=your-id-token

The third-party service can then validate the id_token and log the user in.

Optional: Redirect to Partner directly

In some cases, you don’t want to initialize the OAuth handshake directly, as described in Step 4. If the third party has an endpoint that initializes the OAuth handshake, you can redirect the user there directly after he has been logged in. To do so you need to set the additional parameter skip_oauth_authorization, when creating the one time login token. The scopes setting then becomes irrelevant. See example:

 curl -XPOST 'https://xxx.unidy.de/api/v1/one_time_login_tokens' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: bearer <access_token>' \
  --data '{
  "client_id": "<client_id>",
  "redirect_uri": "https://target.example.com/oauth/start_handshake",
  "skip_oauth_authorization": true
}'

The rest of Step 2 and 3 with receiving the token and sending the user to the /one_time_login endpoint remains the same. The user will be logged in and is then redirected to the redirect_uri directly.