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 configurationAs supplied by your token provider:
An
issuer
URLAn
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 valueA 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 IDsThe
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 thelogin
unless you’re configuring a service user account)The
firstName
of the userThe
lastName
of the userThe
userType
(personal or service)Optionally,
groups
for mapping to LUSID roles
Note
You can set a
claimMappings
field name, excludinggroups
, to an explicit value by wrapping the value in““
characters, for exampleuserType = "Personal"
.
For example, if you have the following external token fields and mappings…
LUSID field | External token issuer field example |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
…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
Issuer is invalid
errorIf 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
value should beAudience is supplied by your external token issuer. Please contact your external token provider for help obtaining the required value.