Generate a Delegated Access Token
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.
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.
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 |
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 |
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.
