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

Prev Next

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…

LUSID field

External token issuer field example

userId

uniqueId

login

username

email

email

firstName

givenName

LastName

surname

userType

"Personal"

groups

role

…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.


Troubleshooting

Issuer is invalid error

If your request fails with the error message The field Issuer is invalid., ensure you have contacted us to express your intent to use an external token issuer. For your security, we only allow approved issuer URLs as inputs for the Issuer field.  

I’m not sure what my audience value should be

Audience is supplied by your external token issuer. Please contact your external token provider for help obtaining the required value.