# Provision users with SCIM

Let your identity provider create, update and deactivate people and groups in your organization ahead of sign-in, over SCIM 2.0.

A SCIM token belongs to one single sign-on connection. Replace _okta_ with a name for the token,
after the identity provider app that uses it.

## Prerequisites

- Permission for `iam:CreateScimToken`. In the console also `iam:ListSsoConnections` to open the
  **Single sign-on** page and `iam:ListScimTokens`: without it the card has no
  **SCIM provisioning** section at all.
- A single sign-on connection with at least one verified domain (see
  [Verify a domain](verify-a-domain.md)). Only addresses on its verified domains can be provisioned.

## Create a token

**Console**
1. Open **IAM**, then choose **Single sign-on**.
2. On the connection's card, under **SCIM provisioning**, copy the **SCIM base URL**.
3. Enter okta as the token name and choose **Create token**.
4. Copy the **SCIM token**. It is shown once.

**CLI**
```sh
dcloud iam sso-connections create-scim-token connection-id --name okta
```

**API**
```http
POST /iam/api/sso-connections/connection-id/scim-tokens
{ "name": "okta" }
```

The response carries `token` (shown once) and `baseUrl`.

**Terraform:** not available. A SCIM token is a secret shown once; it is not a Terraform resource.

## Configure the identity provider

In the identity provider's SCIM app, set the base URL `https://<console host>/api/scim/v2` and the
token as a bearer token (`Authorization: Bearer ews_scim_…`). Turn on creating, updating and
deactivating users, and pushing groups.

## Result

| What the identity provider does | What happens in your organization                                                                                                                                     |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Create a user                   | A membership with the role on first sign-in, for the account at the address; when there is none, a new account with no password (they sign in through single sign-on) |
| Update the name                 | The account's name                                                                                                                                                    |
| Deactivate (`active: false`)    | Membership suspended, every console session ended, connected apps disconnected, the person mailed. Reactivating restores it                                           |
| Delete a user                   | Membership suspended, sessions ended, connected apps disconnected. The account and its audit trail stay                                                               |
| Push a group                    | An IAM group managed by the identity provider: its name and members come from SCIM; attach policies to it in the console                                              |
| Change group members            | IAM group membership; a person who is not in the organization is ignored                                                                                              |
| Delete a group                  | The IAM group                                                                                                                                                         |

The organization owner is never deactivated or removed through SCIM. Every change is in the audit
log as a `scim:` event (such as `scim:CreateUser` or `scim:DeactivateUser`), with the token's name
as the principal. Each token may make 600 requests a minute.

Supported: `/Users` and `/Groups` with `GET`, `POST`, `PUT`, `PATCH` and `DELETE`, including the
`members[value eq "…"]` removal form; `/ServiceProviderConfig` and `/ResourceTypes`. Filters:
`userName eq "…"` for users, `displayName eq "…"` or `externalId eq "…"` for groups. Not
supported: bulk operations, sorting, ETags and password changes.

To revoke a token, choose **Revoke** beside it (`iam:DeleteScimToken`).

## If it is refused

The SCIM endpoint answers SCIM errors, among them:

- 400 `example.org is not a verified domain of this connection`
- 409 `A member with that userName exists`
- 409 `A group with that name exists in the organization`
- 403 `The organization owner cannot be deactivated through SCIM`
- 401 `Invalid token`, and 429 `Too many requests`

Creating a token is refused when the SCIM tokens quota is reached (see [Quotas](quotas.md)).

## Related

- [Single sign-on](single-sign-on.md) · [Map identity provider groups to IAM groups](map-idp-groups-to-iam-groups.md)
- `iam.sso-connections.create-scim-token` · `dcloud iam sso-connections create-scim-token`
