# Provision people with SCIM

Create, suspend and restore people in your project from your identity provider over SCIM 2.0, and keep accounts in your applications current.

SCIM 2.0 (RFC 7644) is a standard that lets one system keep another system's list of people current. Creating and suspending accounts this way is called _provisioning_.

AuthFI provisions in both directions. Inbound, your identity provider or HR system tells your project who exists. Outbound, your project tells the applications downstream.

## Before you begin

You need:

- A plan that includes SCIM. Without it, the endpoints on this page return `403`.
- An AuthFI project and its issuer, the project's URL. This guide uses `https://acme.authfi.io`.
- For inbound provisioning: administrator access to the provisioning settings of your identity provider.
- For outbound provisioning: an application that accepts SCIM, its SCIM base URL, and the bearer token it gave you.

## Provision people from your identity provider

Connect your identity provider or HR system to your project's SCIM endpoint. It then creates, updates and suspends people in your project.

<Steps>

### Create a SCIM token

1. In the console, open **Integrations > Applications** and select the **Provisioning** tab.
2. Choose **Generate token**. The dialog **Inbound SCIM provisioning** opens.
3. Copy the **SCIM 2.0 base URL**.
4. Choose a **Token lifetime**: **1 year (recommended)**, **180 days**, **90 days** or **30 days**.
5. Choose **Generate token**.

The dialog shows the **Bearer token**. It starts with `scim_` and is shown once. Copy it, then tick **I have copied the token**. The dialog stays open until you do.

```bash
export SCIM_TOKEN=<your SCIM token>
```

Every SCIM token expires. The dialog warns you a month before the token lapses.

<Warning title="A new token replaces the old one">
  A project has one SCIM token. **Rotate token** replaces the token your identity provider is using, and the old one
  stops working at once. Enter the new token in your identity provider straight away. **Revoke** removes the token.
</Warning>

### Configure your identity provider

In your identity provider's provisioning settings, enter these values.

| Setting           | Value                                                       |
| ----------------- | ----------------------------------------------------------- |
| Base URL          | The **SCIM 2.0 base URL**, `https://acme.authfi.io/scim/v2` |
| Authentication    | Bearer token                                                |
| Token             | The `scim_…` **Bearer token**                               |
| Unique identifier | `userName`, the person's email                              |

Your identity provider appends `/Users` and `/Groups` to the base URL itself.

</Steps>

## Provision people to an application

When an application accepts SCIM, your project keeps the application's accounts current. The console calls each application you provision to an _outbound connector_.

1. In the console, open **Integrations > Applications** and select the **Provisioning** tab.
2. In the **Outbound connectors** block, choose **Connect an application**.
3. Fill in the fields, and register the connector.

| Field                   | Enter                                          |
| ----------------------- | ---------------------------------------------- |
| **Application name**    | The name shown in the list of connectors       |
| **Their SCIM base URL** | The application's SCIM base URL. `https` only. |
| **Their API token**     | The bearer token the application gave you      |

AuthFI seals the token when it arrives, and never shows it again.

The list of connectors shows, for each application, whether the last sends succeeded. To stop provisioning to an application, choose **Stop provisioning** on its row.

## Check that it works

To check inbound provisioning, call your project's SCIM endpoint with the token.

```bash
curl https://acme.authfi.io/scim/v2/ServiceProviderConfig \
  -H "Authorization: Bearer $SCIM_TOKEN"
```

The request succeeds when the base URL and the token are right. Then start provisioning from your identity provider, and look for the people it sends in your project.

To check outbound provisioning, create or change a person in your project. The **Outbound connectors** block shows whether the send succeeded.

## What your identity provider can send

Your project's SCIM endpoint accepts these requests under `https://acme.authfi.io/scim/v2`.

| Resource                                               | Operations                              |
| ------------------------------------------------------ | --------------------------------------- |
| Users                                                  | `GET`, `POST`, `PUT`, `PATCH`, `DELETE` |
| Groups                                                 | `GET`, `POST`, `PUT`, `PATCH`, `DELETE` |
| `/ServiceProviderConfig`, `/ResourceTypes`, `/Schemas` | `GET`                                   |

| Feature   | Value                                              |
| --------- | -------------------------------------------------- |
| Patch     | Yes                                                |
| Filter    | `userName eq "…"` and `externalId eq "…"` on Users |
| Page size | 20 by default, 100 at most                         |

To find a person, filter on `userName` or `externalId` instead of listing everyone.

## Create or update a person

Your identity provider creates a person with a `POST` to the Users resource.

<Endpoint method="POST" path="/scim/v2/Users" />

```bash
curl https://acme.authfi.io/scim/v2/Users \
  -H "Authorization: Bearer $SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "ada@acme.com",
    "externalId": "00u1abcd"
  }'
```

| Attribute    | Required | Meaning                                    |
| ------------ | -------- | ------------------------------------------ |
| `userName`   | Yes      | The person's email                         |
| `externalId` | Yes      | Your identity provider's ID for the person |
| `active`     | No       | Whether the person may sign in             |

AuthFI keeps these three attributes from a SCIM user.

The response is `201`, and it carries the `id` that AuthFI gives the person. Sending the same person again answers `409` with `scimType` `uniqueness`, as SCIM requires. Identity providers then look the person up and update them.

## Suspend and restore a person

Any of these requests suspends a person:

- `DELETE /scim/v2/Users/{id}`
- `PATCH` with `active` set to `false`
- `PUT` with `active` set to `false`

`{id}` is the `id` AuthFI returned when the person was created.

AuthFI keeps the person's account and marks it suspended. It also revokes their sign-in: open sessions end, and refresh tokens stop working.

To restore a person, set `active` to `true`.

<Note title="Send the whole resource on PUT">
  A `PUT` replaces the resource. Always include `"active": true` for a person who should keep access.
</Note>

## Manage groups

A group has a `displayName` and `members`.

```json
{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "displayName": "engineering",
  "members": [{ "value": "b2f0c6e4-..." }]
}
```

Each member's `value` is the `id` AuthFI returned when that person was created. It is not your identity provider's own ID for them.

## What AuthFI sends to an application

AuthFI sends a change to each outbound connector when the change happens in your project.

| When, in your project          | Sent to the application                                         |
| ------------------------------ | --------------------------------------------------------------- |
| A person is created or changed | The person is created, or updated if they already exist         |
| A person is suspended          | `active: false`                                                 |
| A person is deleted            | Deactivated, or deleted where the application cannot deactivate |

A person is sent with these attributes: `userName` (their email), `externalId`, `active`, a given name and a family name, and a primary email.

## Troubleshooting

| What you see                         | Cause                          | Fix                                                                                                                         |
| ------------------------------------ | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| `403` on every SCIM endpoint         | The plan does not include SCIM | Change the plan                                                                                                             |
| `401` from a token that used to work | The SCIM token has expired     | On the **Provisioning** tab, choose **Manage token**, then **Rotate token**. Enter the new token in your identity provider. |

## Next steps

<Cards>
  <Card href="/connections/sign-in-with" title="Add sign-in with another identity provider">
    Let the people you provision sign in with the same identity provider.
  </Card>
  <Card href="/concepts/access" title="Roles, groups and grants">
    How a group passes access on to its members.
  </Card>
  <Card href="/extend/webhooks" title="Webhooks">
    Have your project call your server when a person is created or suspended.
  </Card>
  <Card href="/security/keys" title="Keys and secrets">
    How AuthFI stores the API token of an outbound connector.
  </Card>
</Cards>