How do I impersonate another user or role?

With LUSID’s impersonation feature, you can allow particular privileged accounts to impersonate another user or role when making a request to APIs in the FINBOURNE platform. For example, you could grant a service user account impersonation privileges that your business’s trusted subsystem can use to operate on behalf of a user in LUSID.

To enable impersonation in LUSID, contact us. Once enabled, to use the impersonation feature:

1. Set up a service user account with impersonation privileges.

2. Send an impersonated API request.

Setting up a service user account with impersonation privileges

To use the impersonation feature, you must create a service user account and assign them a role containing the correct policy. To do this:

1. Sign in to the LUSID web app with the credentials of a LUSID administrator.

2. From the top left menu, navigate to Identity and Access > Roles. Create a new role allow-user-impersonation with the assigned system policy lusid-system-allow-user-impersonation.

3. From the top left menu, navigate to Identity and Access > Users. Create a service user account with the following assigned roles:

   • allow-user-impersonation

   • lusid-administrator

   You can also assign the service user additional roles of your choice. See how to assign a role to a user.

   Note

   When creating the service user account, you must specify a Login. We recommend you specify a value that explicitly indicates it is your impersonating user, for example impersonator@acme.com.

4. Create a Personal Access Token (PAT) for the service user. All impersonated requests will require this PAT, so ensure you store the PAT securely.

Sending an impersonated request

A service user with impersonation privileges can send a FINBOURNE platform API request with additional headers to make the request as either:

• A particular user, using a user ID or login

• One or more particular roles

Impersonating a user

To impersonate an existing LUSID user and their assigned roles in a request, you must include one of the following HTTP headers:

• X-LUSID-Run-As-User, specifying the user ID you intend to impersonate. For example, to call the ListPortfolios API as Jane Smith whose user ID is 00um073pwk8WMVC8Z2p7, you might send the following request:

  curl -X GET "https://<your-domain>.lusid.com/api/api/portfolios?limit=3"
    -H "X-LUSID-Run-As-User: 00um073pwk8WMVC8Z2p7"
    -H "Authorization: Bearer <service-user-personal-access-token>"

• X-LUSID-Run-As-Login, specifying the unique login of the user you intend to impersonate. For example, to call the ListPortfolios API as Jane Smith whose login is jane.smith@acme.com, you might send the following request:

  curl -X GET "https://<your-domain>.lusid.com/api/api/portfolios?limit=3"
    -H "X-LUSID-Run-As-Login: jane.smith@acme.com"
    -H "Authorization: Bearer <service-user-personal-access-token>"

Impersonating one or more roles

To impersonate one or more roles as a non-existent user in a request, you must include the following HTTP headers:

• X-LUSID-Run-As-User, specifying the user ID of a user that does not exist in LUSID. LUSID will log activities as this user ID.

  Note

  You can use any user ID value for non-existent impersonated users, however the value should not contain personally identifying information.

• X-LUSID-Run-As-Roles, specifying a comma-separated list of roles that grant access to the requested features and data.

  Note

  You must prefix roles that are not in the default scope with <scope>:. For example, the lusid-administrator role is in the scope LUSID_SYSTEM, therefore you must specify the value LUSID_SYSTEM:lusid-administrator. You can call the ListRoles API to view role scopes.

For example, to call the ListPortfolios API as an impersonating user with the granting roles portfolio-manager-UK and portfolio-manager-US, you might send the following request:

curl -X GET "https://<your-domain>.lusid.com/api/api/portfolios?limit=3"
  -H "X-LUSID-Run-As-User: my-impersonated-user"
  -H "X-LUSID-Run-As-Roles: portfolio-manager-UK, portfolio-manager-US"
  -H "Authorization: Bearer <service-user-personal-access-token>"

Note the following:

• The specified roles must grant access to both the required data and feature policies for the request. Read more.

• You must use the service user’s generated PAT as the bearer token for an impersonating call.

• You cannot create or use an impersonated user’s PAT. You may only use the service user’s PAT.

Viewing impersonated request logs

When you make an impersonated request, the request logs contain the following values:

• The user ID of the impersonated user.

• The impersonatingUser ID.

Note

Currently, you can only retrieve the impersonatingUser ID via the Insights API, for example by calling the GetRequestLog endpoint.

Troubleshooting

403 response when impersonating the lusid-administrator role

When you use the X-LUSID-Run-As-Roles HTTP header, you must prefix roles that are not in the default scope with <scope>:. You can call the ListRoles API to view role scopes.

See Impersonating one or more roles.