SCIM Access

How to use leanix SCIM

Overview

As an application developer, you can use the System for Cross-Domain Identity Management (SCIM) user management API to enable automatic provisioning of users and groups between LeanIX and your Active Directory.

SCIM Endpoint

http://your-url/services/mtm/v1/scim/v2

IDMType MTM_BASED_ROLES

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

Authorization

Short-Lived bearer token

The user has to be an ACCOUNTADMIN when the shortlived bearer token is created. The longlived 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 therefor 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 https://dev.leanix.net/docs/authentication 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 a 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"
}

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
customRoles(optional): a list of customerRoles 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.

All required mapping values between Azure AD and LeanIXAll required mapping values between Azure AD and LeanIX

All required mapping values between Azure AD and LeanIX

Email mapping as secondary matching attributeEmail mapping as secondary matching attribute

Email mapping as secondary matching attribute

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