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.

export SCIM_TOKEN=<your SCIM token>

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.

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.

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.

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.

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": "[email protected]",
    "externalId": "00u1abcd"
  }'

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.

Manage groups

A group has a displayName and members.

{
  "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.

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

Troubleshooting

Next steps