Authentication using the Token Exchange Flow

About Token Exchange

The OAuth2 Token Exchange flow is, as the name implies, used to exchange one token for another.
In our case we allow exchanging a token created by an external party, for example you own authorization platform or a service such as Auth0, with a token usable with the Unloc API.

This allows for accessing our API without a dedicated backend, or using an existing permission system.

User management with an external authentication/authorization provider

This guide is based on using Auth0, but you can use any other external authentication/authorization provider as long as they satisfy these requirements:

• Must provide RS256-signed JWT (known as the subject token), signed with a private key.
• Public key must be available via a URL, either as a JWKS or as plain text
• Can add custom URLs to aud-field of subject token
• Can add custom permissions to subject token

Click here for a guide on how to setup Auth0 with user management, fully compatible with Unloc.

Oauth2 tokens with Permissions

The user tokens generated by the external authentication/authorization provider must contain a permissions field, in the form of an array of strings. Each string (entry in the array) represents a Lock Holder that the holder of the token can administrate. These Lock Holders are identified with their countryIso, organizationId and organizationIdSuffix in the following format: lockHolder.identifier:[countryIso].[orgId].[orgIdSuffix]. E.g: lockHolder.identifier:NO.919424508.east.

Example of an Oauh2 token fully compatible with Unloc:

{
  "iss": "https://[integrator].eu.auth0.com/",
  "sub": "auth0|5934aafe4e52d93452b1c90",
  "aud": [
    "api.unloc.app",
    "https://[integrator].eu.auth0.com/userinfo"
  ],
  "scope": "openid email name",
  "permissions": [ 
    "lockHolder.identifier:NO.919424508.east",
    "lockHolder.identifier:NO.425234653.north"
  ]
}

Adding a public key URL

For us to authenticate a subject token, the public key used to sign the token with must be available for us to fetch. This URL must be added to the Integrator through this endpoint.

Performing the Token Exchange

The token exchange endpoint is our token endpoint, with grant set to token_exchange and the aforementioned subject token in the subjectToken field.
If the subject token was validated in our system you will receive a token in return, scoped for the Lock Holders the user has permissions for.