Generate an Access Token using Delegated Authentication

Introduction

Delegated Authentication is a feature the Mosaic User Service provides, where end-user application developers can generate a Mosaic End-User Access Token without using the Mosaic User Service for authentication and primary token generation. This feature is useful when end-user applications already have a user management and authentication service in place, but wants to use other Mosaic end-user facing services.

What is Delegated Authentication?

Take a scenario where there is already an end-user application developed with authentication and authorization capabilities, and its own user store. The primary backend for this application has its own means of handling users, profiles and authentication. But now, the application developers wants to use Mosaic end-user facing services such as the Billing service so that they can easily implement subscription capabilities in their application.

The GraphQL APIs exposed by the Mosaic end-user facing services can only be accessed using a Mosaic end-user Access Token, which is generated by the User Service upon authentication. Given that the primary authentication and user management is handled by a non-Mosaic third party service, when the end-user application calls a Mosaic end-user facing service, that application can use Delegated Authentication. This allows generating a JWT that represents an end-user that is authenticated and managed through a third-party, but is used in the context of the Mosaic platform.

When using the Delegated Authentication API, the Mosaic User Service creates a user record for the corresponding end-user along with a profile, connected to the email address used to generate the token.

The token contains information such as the Tenant ID, Environment ID, Application ID, User ID and Profile ID.

This token can be attached to the Authentication header as a Bearer token and be used to call any secured API exposed by Mosaic end-user facing services such as Personalization, Billing, Monetization or Entitlement.

Using Delegated Authentication

Setting up the IDP Connection

Before calling the generateDelegatedAccessToken GraphQL operation to generate an Access Token, a new IDP Connection must be configured of type Delegated Authentication. Token generation will fail if a Delegated Authentication IDP Connection is not configured.

Navigate to the New IDP Connection station through Environment-> Services Configuration -> IDP Connections. Select Delegated Authentication (Managed) as the Provider. The title will be filled in automatically, and you can change if required. Click on Proceed.

**New Delegated Authentication IDP Connection **

You will be navigated to the IDP Connection Details station for the newly created Delegated Authentication IDP Connection. Set the status as Enabled and save.

Delegated Authentication IDP Connection Details

generateDelegatedAccessToken GraphQL Operation

An Access Token can be generated for Delegated Authentication purposes by calling the GraphQL mutation generateDelegatedAccessToken exposed through the management API of the Mosaic User Service.

This operation is a secured operation, meaning that a valid service account token must be provided with the permission GENERATE_DELEGATED_ACCESS_TOKEN. The Tenant and the Environment IDs the Access Token should be generated for will be derived from this.

Inputs

Property	Type	Description
applicationId	UUID!	Application ID that will be specified in the Access Token.
subjectId	String!	Subject ID of the end-user given by the Authentication Provider. This could be a UUID, a text value or a number as decided by the 3rd party Authentication Provider. The Mosaic User Service will recognize this value as the unique identifier for an end-user.
uniqueProfileIdentifier	String	A unique identifier which represents the user’s profile. This could be a UUID, a text value or a number. This identifier is used to determine if the user the access token is generated for should have a new User Profile or associated with an already existing one. If no uniqueProfileIdentifier is given, a default user profile is created and will be assigned to the token’s payload.
email	String	Optional email address of the end-user the access token is generated for.
name	String	Optional Name of the end-user.

Response

Property	Type	Description
accessToken	String!	The Access Token generated with Delegated Authentication.
tokenType	String!	The token type. This value will be Bearer.
expiresIn	Int!	Expiry period in seconds.
Payload	EndUserAccessTokenPayload	Contains the payload that is returned in the JWT.

Using the Access Tokens generated with Delegated Authentication

The Access Token is a JWT that is signed by the Mosaic User Service, issued for a specific user and a profile ID. This is a Bearer Token that can be used for http authorization.

All end-user facing services in Mosaic requires a Mosaic end-user Access Token to call the GraphQL operations. The Access Token generated with Delegated Authentication will also be identified as a valid Mosaic end-user Access Token. It can be passed in the Authorization header in the http request, when making calls to these GraphQL operations. The @axinom/mosaic-id-guard library will then verify this token and allow the token bearer to execute the required operations. (i.e. creating a new billing subscription, storing watch history in personalization-service, etc.)

Embedding the Access Token in a 3rd Party JWT

This is only applicable when the existing end-user application already utilizes a JWT format for the existing integrations.

With the introduction of the Delegated Authentication, end-user applications must now maintain two access tokens. One for the existing 3rd party integrations and the Access Token generated with Delegated Authentication to access Mosaic end-user facing services. It may be desirable to streamline this and only maintain a single JWT.

To support this, the @axinom/mosaic-id-guard library allows the Access Token to be embedded inside any other JWT issued by a 3rd party and to use that combined JWT when making requests to the Mosaic end-user facing services.

The full Access Token content must be embedded within a property named mosaic.end-user.accessToken of the 3rd party JWT. Below is a sample payload of an embedded token.

{
  "sub": "1234567890",
  "name": "John Doe",
  "admin": true,
  "iat": 1646726761,
  "exp": 1646730361,
  "mosaic.end-user.accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTY0NjcyNjc2MSwiZXhwIjoxNjQ2NzMwMzYxfQ.jUSuFusrcXKswIgRXsZis7cVSpbM6b26k2IYa5kk4Aw"
}

Extending the Access Token

The Access Token generated with Delegated Authentication also allows its payload to be extended by adding other developer defined properties (similar to regular Mosaic end-user tokens). If an Access Token Enrichment Webhook is defined in the Application configuration in User Service, during the generation of the access tokens, the User Service will make a call to this webhook and embed its response in a property called extensions.

Access Token Enrichment Webhook in Application Details