SCIM Access

How to use LeanIX SCIM (System for Cross-Domain Identity Management).

Overview

The basic idea of SCIM is to synchronize user states between systems. SCIM synchronizes user information from the source system (AD/LDAP/directly maintained in the IDP) to the target system (LeanIX). SCIM works in conjunction with Single Sign-on (SSO), hence SSO is also required. In a nutshell, the purpose of SSO is to verify during login time whether a user is allowed to access the system (authentication) and, optionally, what the user is allowed to do in the system (authorization).

The three main use cases of SCIM are:

  • User provisioning: If a user exists in the source system (AD/LDAP/directly maintained in the IDP) but not in the target system(LeanIX), then a corresponding user object is created in the target system.
  • User deprovisioning: If a user exists in the target system but not in the source system, then the user object in the target system gets de-provisioned.
  • User updating: If the user information in the source system differs from the target system, then that information gets pushed to the target system.

📘

Note

SCIM is not supported in LeanIX SaaS Management Platform (SMP).

Initial Configuration

SCIM Endpoint

Use the following SCIM Endpoint to manage automated user provisioning:

https://{SUBDOMAIN}.leanix.net/services/mtm/v1/scim/v2

Replace {SUBDOMAIN} with your LeanIX subdomain. You can copy the subdomain value from the workspace URL.

IDMType MTM_BASED_ROLES

When InviteOnly is enabled for the default workspace, no permissions will be created.

Steps to setup SCIM

  1. In your LeanIX workspace, create a new technical user (Admin > Technical User) with an ADMIN permission role
  2. Notify LeanIX Support and share the name of the Technical User, so we can grant it the necessary rights (accountuser to accountadmin)
  3. Using your technical user token, create a short-lived bearer token.
  4. Transform the short-lived bearer token into a long-lived bearer token. Keep in mind that you are synchronizing only the workspace you are creating the token in.
  5. Configure provisioning in your IDP (URL: https://{SUBDOMAIN}.leanix.net/services/mtm/v1/scim/v2) and the long-lived bearer token that you created.
  6. Configure attribute mappings.

Authorization

Short-Lived Bearer Token

The user has to be an ACCOUNTADMIN when the short-lived bearer token is created. The long-lived bearer token inherits the user role from the short-lived token.

MTM allows users with at least ACCOUNTADMIN authority to provision long-lived bearer tokens. This kind of access token is required for the SCIM integration. Long-lived bearer tokens do not include an expiry and are, therefore valid until they are deleted or invalidated actively.

curl --request POST \
  --url https://{SUBDOMAIN}.leanix.net/services/mtm/v1/oauth2/token \
  -u apitoken:68Euc[...]EKRcS \
  --data grant_type=client_credentials

Long-Lived Bearer Token

First of all, retrieve a valid short-lived access token for your user that has the ACCOUNTADMIN or SUPERADMIN role. See Technical User on how you can use an API token to do so.

You can then create a long-lived bearer token by calling the respective REST endpoint with that short-lived access token. Make sure to include a description and a scope. Workspace ID can be found in the API Tokens tab of the Administration section of your workspace.

curl --request POST \
  --url https://{SUBDOMAIN}.leanix.net/services/mtm/v1/longlivedBearerTokens \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJz [...] ssqaPSA' \
  --header 'Content-Type: application/json' \
  --data '{"description":"My first long-lived bearer token","scope":"","scimConfiguration":{"workspaceId":"default workspace id","permissionRole":"default ROLE"}}'

You should then see an HTTP 201 response containing the long-lived bearer token in the accessToken attribute:

{
  "id": "47394a58-4165-45e4-afc3-f9a706dad4fb",
  "accountId": "fb526496-751b-44cd-a678-369f233fa543",
  "accessTokenId": "4dd966bf-06f1-43bf-9dc2-eec7134d555f",
  "valid": true,
  "accessToken": "eyJraWQiOiI2MzM2NTMxOMiIsImFsZyI6IlJTMjU2In0.eyJq [...] U_Xeg",
  "creatorId": "8c263138-afab-4823-b509-0b99c2c36569",
  "description": "My first long-lived bearer token",
  "createdAt": "2020-05-19T06:43:11.667Z"
}

❗️

Important - access token availability

The access token will only be visible once in this very response. Please make sure to copy it to a secure location.

List Existing Long-Lived Bearer Tokens

To get a list of all already existing Long-Lived Bearer Tokens, simply call the following REST endpoint with any valid access token that has the role ACCOUNTADMIN or SUPERADMIN:

curl --request GET \
  --url https://{SUBDOMAIN}.leanix.net/services/mtm/v1/longlivedBearerTokens \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJz [...] ssqaPSA'

You should get a HTTP 200 response containing a list of existing tokens:

[
  {
    "id": "47394a58-4165-45e4-afc3-f9a706dad4fb",
    "accountId": "fb526496-751b-44cd-a678-369f233fa543",
    "accessTokenId": "4dd966bf-06f1-43bf-9dc2-eec7134d555f",
    "valid": true,
    "creatorId": "8c263138-afab-4823-b509-0b99c2c36569",
    "description": "My first long-lived bearer token",
    "createdAt": "2020-05-19T06:43:11.667Z"
  },
  ...
]

Invalidate Existing Long-Lived Bearer Tokens

If you need to invalidate one of your Long-Lived Bearer Tokens, simply post to the following REST endpoint with any valid access token that has the role ACCOUNTADMIN or SUPERADMIN:

curl --request POST \
  --url https://{SUBDOMAIN}.leanix.net/services/mtm/v1/longlivedBearerTokens/47394a58-4165-45e4-afc3-f9a706dad4fb/invalidate \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJz [...] ssqaPSA'

You should get an HTTP 200 response showing that the token is now invalid:

{
  "id":"47394a58-4165-45e4-afc3-f9a706dad4fb",
  "accountId":"fb526496-751b-44cd-a678-369f233fa543",
  "accessTokenId":"4dd966bf-06f1-43bf-9dc2-eec7134d555f",
  "valid": false,
  "creatorId":"8c263138-afab-4823-b509-0b99c2c36569",
  "description":"My first long-lived bearer token",
  "createdAt":"2020-05-19T06:43:11.667Z"
}

After this, nobody is able to perform any authenticated operation with the invalidated Long-Lived Bearer Token.

SCIM Attribute Mapping

The following attributes are allowed:

  • userName
  • active
  • name
  • emails
  • roles
  • entitlements
  • enterpriseUserExtension::department

Currently, we support three Attributes in the Entitlement Object:

  • role (required): A subset of standard roles as defined by leanix ("VIEWER", "MEMBER", "ADMIN").
  • workspaceId (required): The uuid of the workspace the user has permission for.
  • customRole (optional): A list of customer roles as defined in the workspace.