How do I configure LUSID to use a different API access token issuer?

You can use the ExternalTokenIssuer API to configure LUSID to use API access tokens for your own identity provider (IDP) for all requests in your LUSID domain. You can configure up to five different external token issuers.

Prerequisites

Contact us to provision your LUSID domain with access to the ExternalTokenIssuer API endpoints.

To set up an external token issuer, call the CreateExternalTokenIssuer API, passing in the following:

• A code that uniquely identifies the configuration

• As supplied by your token provider:

  • An issuer URL

  • An audience string

  Note the issuer/audience combination must be unique within your LUSID domain.

• A friendly description

• A logoutUrl for LUSID to redirect users to when they log out; this defaults to the LUSID logout screen if you do not provide a value

• A collection of claimMappings to map the token fields required by LUSID to your external token fields, including a field name mapping for:

  • userId for unique LUSID user IDs

  • The login email address for each LUSID account (a LUSID username; it must be unique within your LUSID domain)

  • The email address for each LUSID account (this should be the same as the login unless you’re configuring a service user account)

  • The firstName of the user

  • The lastName of the user

  • The userType (personal or service)

  • Optionally, groups for mapping to LUSID roles

  Note

  You can set a claimMappings field name, excluding groups, to an explicit value by wrapping the value in ““ characters, for example userType = "Personal".

For example, if you have the following external token fields and mappings…

…you might send the following request:

curl -X POST 'https://<your-domain>.lusid.com/identity/api/externaltokenissuers' 
  -H 'Content-Type: application/json-patch+json'
  -H 'Authorization: Bearer <your-API-access-token>'
  -d '{
{
  "code": "Acme-External-Token-Issuer",
  "issuer": "https://auth.acme.com",
  "audience": "api.acme-app.com",
  "description": "External Token Issuer definition to allow matching Acme Co. authentication tokens to LUSID API access tokens",
  "claimMappings": {
    "userId": "uniqueId",
    "login": "username",
    "email": "email",
    "firstName": "givenName",
    "lastName": "surname",
    "userType": "\"Personal"\",
    "groups": "role"
  },
  "logoutUrl": "https://acme.com/signedout"
}'

Once you’ve set up your external token issuer, your users can continue to use LUSID as usual. Behind the scenes, LUSID obtains an access token for each request from your configured identity provider.

Note

If using LUSID’s impersonation feature, you can continue to use the relevant additional headers in requests as usual.