Set up SCIM provisioning · BreezeAuth Docs

This page walks you through connecting a provisioning system, such as an HR platform or an identity directory, to BreezeAuth. You do the first steps in the BreezeAuth admin console, and the last ones in the provisioning system.

Before you start

Permissions. Creating service users and credentials requires the Owner or Administrator role. See Administrative roles.
Verify your domains first. People whose e-mail is on a verified domain are created as managed users. Everyone else is invited as a guest and receives an invitation e-mail. If you connect the provisioning system before verifying your domain, your colleagues will all be invited as guests.
Check what the provisioning system supports. It must speak SCIM 2.0 and be able to obtain OAuth 2.0 access tokens with the client credentials flow. See Authentication below.

1. Create a service user for the provisioning system

In the sidebar, select Users, then New user.
In User type, choose Service user.
Enter a Name that identifies the provisioning system, for example “HR provisioning”.
In Administrative role, choose SCIM Provisioner.
Select Create service user.

The SCIM Provisioner role includes exactly what SCIM needs, and nothing else: reading, creating, updating and deleting users and groups, and managing group members. Don’t use the Administrator role for provisioning: if the credential leaked, it would give access to much more than your users and groups.

See Create and manage service users for more about service users.

2. Create a credential

Open the service user and select the Credentials tab, then New credential.
Enter a Name, for example “Production”, and optionally an Expires at date.
Select Create.
Copy the Client ID and the Client secret, and store them safely. The secret is shown only once.

See Service user credentials for how to store, rotate and deactivate credentials.

3. Find your SCIM base URL

Every organization has its own SCIM base URL:

https://api.breezeauth.com/organizations/<organization ID>/scim/v2

To find your organization ID, select Organization in the sidebar of the admin console. The ID appears under your organization’s name, at the top of the Manage Organization page. Select the copy icon next to it (Copy UUID) to copy it.

For example, if your organization ID is 0d5a7e3c-8b1f-4c2e-a6d9-5f4e3b2a1c0d, your SCIM base URL is:

https://api.breezeauth.com/organizations/0d5a7e3c-8b1f-4c2e-a6d9-5f4e3b2a1c0d/scim/v2

4. Configure the provisioning system

In the provisioning system, create a SCIM connection, sometimes called a “SCIM app” or a “provisioning connector”, with these settings:

Setting	Value
SCIM version	2.0
Base URL (tenant URL)	Your SCIM base URL, from the previous step.
Authentication method	OAuth 2.0, client credentials grant
Token URL (token endpoint)	`https://api.breezeauth.com/oauth/token`
Client ID and client secret	The credential you created.
Unique identifier for users	`userName`, which must hold the person’s e-mail address.
Unique identifier for groups	`displayName`

Important: BreezeAuth doesn’t issue long-lived API tokens. Access tokens expire after a few minutes, so the provisioning system must request them itself from the token URL, with the client ID and secret, whenever it needs a new one. A system that only lets you paste a fixed “bearer token” or “API key” once will stop working when that token expires. In that case, your developers can run a small connector that obtains tokens and forwards the SCIM requests. See Obtain access tokens.

Map the attributes

Most provisioning systems let you choose which of their attributes fill each SCIM attribute. Map at least:

SCIM attribute	Map it to
`userName`	The person’s work e-mail address. Required.
`name.givenName`, `name.familyName`	First and last name.
`active`	Whether the person should have access.
`externalId`	The person’s identifier in the provisioning system.

The other supported attributes, such as job title, phones, department or manager, are listed in Provision users.

5. Test the connection

Most provisioning systems have a Test connection button. If you want to test by hand, your developers can request a token and read the configuration of your SCIM endpoint:

curl https://api.breezeauth.com/organizations/<organization ID>/scim/v2/ServiceProviderConfig \
  -H 'Authorization: Bearer <access token>'

A 200 OK response with a ServiceProviderConfig document means the URL and the credential are correct.

6. Start provisioning

Start with a few test people, for example by limiting the provisioning system to a small test group.
In the admin console, check under Users and Groups that they appear as expected, with the right Account type.
In the Audit Logs, filter by the service user to see every change it made.
Give the provisioned groups access to their applications.
Extend provisioning to everyone.

Keep the connection secure

Restrict where it connects from. If the provisioning system calls from known IP addresses, limit service users to those networks. See Restrict the networks service users connect from.
Rotate the credential regularly, without downtime. See Rotate a credential.
Stop provisioning instantly by deactivating the service user or its credential. Provisioning stops at the next request; nothing already provisioned is undone.