mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
96 lines
4.7 KiB
Plaintext
96 lines
4.7 KiB
Plaintext
---
|
|
title: "SCIM user provisioning"
|
|
description: "Automatically provision, deprovision, and map users to roles for Mintlify dashboard members from Okta or another SCIM 2.0 identity provider."
|
|
keywords: ["SCIM", "Okta", "identity provider", "user management", "RBAC"]
|
|
---
|
|
|
|
<Info>
|
|
SCIM requires an [Enterprise plan](https://mintlify.com/pricing?ref=scim).
|
|
</Info>
|
|
|
|
SCIM (System for Cross-domain Identity Management) lets admins provision and deprovision Mintlify organization members directly from your identity provider.
|
|
|
|
SCIM manages who has access to your organization. To control how users sign in, set up [SSO](/dashboard/sso).
|
|
|
|
### Supported identity providers
|
|
|
|
Mintlify's SCIM endpoint works with any SCIM 2.0-compliant identity provider that authenticates with a bearer token. Step-by-step instructions below cover Okta. For other providers, [contact us](mailto:support@mintlify.com) for setup guidance.
|
|
|
|
## Enable SCIM
|
|
|
|
<Steps>
|
|
<Step title="Open SCIM settings">
|
|
In your Mintlify dashboard, navigate to the [SCIM](https://app.mintlify.com/settings/organization/scim) tab of the "Identity & access" page.
|
|
</Step>
|
|
<Step title="Turn on SCIM">
|
|
Click **Configure SCIM**. Mintlify generates a **SCIM base URL** and a **bearer token**.
|
|
|
|
<Warning>
|
|
Securely store the bearer token. Mintlify shows it only once and cannot display it again.
|
|
</Warning>
|
|
</Step>
|
|
<Step title="Add the credentials to your identity provider">
|
|
Enter the SCIM base URL and bearer token into your identity provider's SCIM app configuration. See [Configure your identity provider](#configure-your-identity-provider) for provider-specific steps.
|
|
</Step>
|
|
</Steps>
|
|
|
|
## Configure your identity provider
|
|
|
|
### Okta
|
|
|
|
<Steps>
|
|
<Step title="Add a SCIM app in Okta">
|
|
In Okta, under **Applications**, click **Browse App Catalog** and search for **SCIM 2.0 Test App (Header Auth)**. This is Okta's standard integration for any SCIM 2.0 API that authenticates with a bearer token.
|
|
</Step>
|
|
<Step title="Add your Mintlify credentials">
|
|
Under the app's **Provisioning** settings, enter the Mintlify SCIM base URL and bearer token. Format the token as `Bearer <token>`.
|
|
</Step>
|
|
<Step title="Enable provisioning actions">
|
|
Under **Provisioning to app**, enable the create, update, and deactivate options you want Okta to manage. Leave **Sync password** off, since Mintlify doesn't use Okta-managed passwords.
|
|
</Step>
|
|
<Step title="Create and push groups">
|
|
In Okta, use your existing groups or create new ones for each set of users you want to provision, then push those groups to the SCIM app under **Push groups**.
|
|
|
|
<Warning>
|
|
Group names are case-sensitive. The name you map in Mintlify must match the Okta group name exactly.
|
|
</Warning>
|
|
</Step>
|
|
<Step title="Assign users">
|
|
Assign the relevant groups or individual users to the app under **Assignments**.
|
|
</Step>
|
|
<Step title="Map groups to roles">
|
|
In the Mintlify dashboard, map each pushed group name to a dashboard role. See [Map groups to roles](#map-groups-to-roles).
|
|
</Step>
|
|
</Steps>
|
|
|
|
## Map groups to roles
|
|
|
|
Assign [roles](/dashboard/roles) to users based on their identity provider group membership.
|
|
|
|
1. In the Mintlify dashboard, navigate to the [SCIM](https://app.mintlify.com/settings/organization/scim) tab of the "Identity & access" page.
|
|
2. In the "Group-to-role mappings" section, click **Add mapping**.
|
|
3. Enter the identity provider group name and select a role.
|
|
|
|
When a user belongs to multiple mapped groups, Mintlify assigns the highest-privilege role among them.
|
|
|
|
You can edit or remove a mapping at any time. This mapping is one-directional and only controls which Mintlify role a group receives. For example, suppose you map your identity provider's `developers` group to the editor role and later change that mapping to viewer. New members of `developers` become viewers in Mintlify, but the existing `developers` group itself is unchanged in your identity provider.
|
|
|
|
## Rotate the bearer token
|
|
|
|
Rotate the bearer token if it's exposed or as part of routine credential hygiene.
|
|
|
|
1. Navigate to the [SCIM](https://app.mintlify.com/settings/organization/scim) tab of the "Identity & access" page.
|
|
2. Click **Rotate token**.
|
|
3. Copy the new token and update your identity provider's SCIM configuration.
|
|
|
|
<Warning>
|
|
Rotating the token immediately invalidates the previous token. Provisioning stops working until you update your identity provider with the new token.
|
|
</Warning>
|
|
|
|
## Disable SCIM
|
|
|
|
1. Navigate to the [SCIM](https://app.mintlify.com/settings/organization/scim) tab of the "Identity & access" page.
|
|
2. Toggle SCIM off.
|
|
|
|
Disabling SCIM stops new provisioning and deprovisioning events from your identity provider. Existing dashboard members keep their current access until removed manually or through another method.
|