🚧

Note

SCIM is not supported in LeanIX SMP.

Overview

The basic idea of SCIM is to synchronise user states between systems. SCIM works in conjunction with Single Sign-on (SSO), but 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).

SCIM synchronises user information from the source system (AD/LDAP/directly maintained in the IDP) to the target system (LeanIX).

The 3 main use-cases of SCIM are:

1. 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
2. User De-provisioning: 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
3. User Updating: If the user information in source system differs from the target system, then that information gets pushed to the target system

SCIM Endpoint

https:// customer_domain.leanix.net/services/mtm/v1/scim/v2

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 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. Create a short-lived bearer token (see Authentication)
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! See below:
5. Config provisioning in your IdP (URL: https://<customerdomain>.leanix.net/services/mtm/v1/scim/v2) and the long-lived bearer token created in step 4)
6. Config mappings as per documentation below

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 ACCOUNTADMIN & SUPERADMIN users to provision long-lived bearer tokens. These access tokens can be used for integrations that cannot leverage the API token feature to create access tokens on demand (e.g. SCIM user provisioning). Long-lived bearer tokens do not include an expiry and are therefore valid until they are deleted or invalidated actively.

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.

curl --request POST \
  --url https://app.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://app.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 hat has the role ACCOUNTADMIN or SUPERADMIN:

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

You should get a 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

Allowed attributes

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

currently we support 3 Attributes in the Entitlement Object:

role(required) : 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

Azure AD specific mappings

To make Azure AD completely compatible with the SCIM implementation the predefined email attribute must be configured as a matching attribute with matching precedence 2.

https://docs.microsoft.com/en-us/azure/active-directory/app-provisioning/customize-application-attributes

SCIM Documentation

https://docs.microsoft.com/en-us/azure/active-directory/app-provisioning/use-scim-to-provision-users-and-groups