Skip to main content

SCIM Provisioning

With SCIM provisioning, your identity provider manages your team's Autoheal accounts for you. It creates people before their first sign-in and updates their name and email. It suspends or removes them when they leave, and keeps the user groups you choose in sync. Autoheal's endpoint follows the SCIM 2.0 standard. This page covers what any identity provider does through it; each provider's guide covers its own setup:

note

SCIM provisioning is available to every organization unless Autoheal support has turned it off for yours; then the User provisioning tab of Authentication says it isn't available. A connection's key can create, change and remove people, so setting one up, issuing, rotating or revoking its keys, stopping or resuming it, and removing it all require someone who can manage access in your organization, such as an Org Admin. See Roles & Permissions.

How it fits with SSO and roles​

AnswersManaged in
Single sign-onWho is signing in?Your identity provider
SCIM provisioningWhich accounts and group memberships exist?Your identity provider
RolesWhat can each person or group do, and where?Autoheal, on IAM

SCIM never grants roles. People it creates join your organization with no role and no project. Someone in no group is a member of the organization with no role until you grant one. Grant roles to people or, better, to their groups, on IAM. A group's name never implies a role.

Invitations and just-in-time sign-up keep working alongside SCIM.

What your identity provider manages​

Your identity providerAutoheal admins
A provisioned person's name and emailChanges themCan't change them
Whether a provisioned person can sign inSuspends, reactivates and removes themCan't suspend or remove them
A synced group's name and membersChanges themCan't rename it, change its members, or delete it
Groups made in AutohealNever sees themManage them, and may add provisioned people to them
Roles held by people and groups—Grant and revoke them on IAM, for either kind of group

Synced people show a Synced badge on Users and IAM. Synced groups show one with their connection's name, such as Synced · Entra Acme, on User groups and IAM, so a synced group is never mistaken for one you made with the same name. On Users, User groups and IAM, filter Managed by → Synced to list only what your identity provider manages, or Not synced for the rest. Locked controls explain why they're locked. Adding a provisioned person to a group you made doesn't change who manages them.

Set up the connection​

Choose your organization in the project switcher, then open Authentication in its sidebar and its User provisioning tab.

  1. Create the connection

    Select Set up SCIM (or Add connection for another identity provider) and name it after your identity provider, for example Entra Acme. Autoheal creates the connection and a service account for it, named SCIM: Entra Acme. That account's keys are the token your identity provider uses, and they work only for provisioning, so the account needs no role.

  2. Create a key

    Select Create a key, name it after your identity provider, and choose an expiry. Copy the key: it is shown once. A connection's keys start with ahscim_ and work only on the SCIM endpoint.

  3. Configure your identity provider

    Give your identity provider the connection's Tenant URL and the key as its bearer token (often called the secret token), following its guide, such as Microsoft Entra ID. The tenant URL ends in /api/v1/scim, with no trailing slash.

  4. Check the connection

    Run your identity provider's connection test. The status on Authentication → User provisioning changes from Waiting for first request to Connected. It shows No requests lately when nothing has got through for two hours, and the last request Autoheal refused or failed after accepting the key, if any: its status, the operation, the error code and an ID for the request. It never shows whom the request was about; your identity provider's provisioning log has the details. A wrong or revoked key is refused before that, so it shows as no requests.

People who are already in Autoheal​

When your identity provider provisions someone who already joined by invitation or single sign-on, Autoheal links the existing account rather than creating another, with no approval step. It does this when exactly one person in your organization has that email, the email is verified, the account is active, and no other connection manages them. The person keeps their roles, groups and history.

Once linked, your identity provider manages the person's name and email, with one exception. A person's email is what they sign in with, so whoever holds a new address would hold their account. Your identity provider can't change the email of someone who can manage access in your organization or one of its projects: an Org Admin or a Project Admin, or anyone holding that right on the organization or a project, directly or through a group. Only the email waits: the rest of the update, such as a new name or a suspension, still applies, and the identity provider gets a conflict for the email. Changes to everyone else's email go through. A different capitalization of the same address isn't a change. Your allowed sign-in domains play no part here: they decide who may join, not who owns an address.

The new email isn't lost: it waits on the person's page under Users, and Authentication → User provisioning lists who has one waiting. Someone else who manages access in the organization checks it is the same person and selects Confirm new email; the person can't confirm their own. From then on they sign in with the new email, and the identity provider's next sync goes through. The confirmation is recorded in the access audit log. If the identity provider sends their current email again first, the waiting one goes.

If those conditions aren't met, the request is refused with a conflict, and the error appears on Authentication → User provisioning. Examples are two accounts with the email, a suspended account, or a person another connection already manages. Resolve the account in Autoheal, then retry from your identity provider.

Groups​

Only the groups your identity provider sends are synced. A synced group can hold up to 10,000 people. Its members must be people the same connection provisions. Nested groups are not supported.

Autoheal never takes over a manual group, one made in Autoheal. If your identity provider pushes a group with the same name, both groups stay: its SCIM-managed group is created beside the manual one with no roles, so nobody's access changes. User groups then shows a banner, which you can dismiss, and a Same name as a SCIM-managed group mark on the manual group's row, which opens the review. The manual group's own page shows the banner too. Nothing is blocked meanwhile. The review shows both groups side by side, their members and roles, and what a merge would change, read fresh. From it, an admin who can edit groups and grant roles can:

  • Keep separate: the warning goes away while the two keep that name, and the manual group's row is marked Kept separate from the SCIM-managed group. You can grant roles to the SCIM-managed group whenever you like.
  • Rename manual group: the pair stops sharing a name.
  • Fix in your identity provider: add the people missing from its group there; its next sync brings them in, and the review updates.
  • Merge groups: every role assigned to the manual group is granted to the SCIM-managed group and the manual group is deleted, in one audited step. From then on, your identity provider decides who is in the group. The review names the manual group's members who aren't in the SCIM-managed group: they won't be members after merging, so they no longer get the manual group's roles through it, though they keep any role they hold directly or through another group. If neither group has roles, no role assignments change. You confirm in a second step of the review. Merging needs the right to grant and remove those roles wherever the manual group holds them. If you are in the SCIM-managed group yourself, the roles you gain are recorded as a self-grant and your organization's other admins are told.

If nobody acts, both groups keep working as they are: the synced group gives its members no access until it is granted roles.

Admin roles on synced groups​

Granting a role to a synced group lets your identity provider decide who holds it: whoever it puts in the group gets the role. For an admin role, that means your identity provider's administrators choose your Autoheal admins. They could also take someone out of the group, change that person's email, and put them back; each step is allowed and appears in the access audit log. To keep choosing admins in Autoheal, give admin roles directly or through a group you made. Either way, the last active person who can manage access can't be removed, an Org Admin can take a role off a synced group on IAM at any time, and Autoheal support can restore an admin to an organization left without one.

Removing someone from a synced group removes only the access they had through that group. Roles granted to them directly, or through other groups, stay.

Offboarding​

Suspending someone (the identity provider marks them inactive, for example when they're disabled or unassigned):

  • Stops their access to your organization. New sign-ins are refused at once. Existing sessions and personal access tokens are refused as soon as the change reaches Autoheal.
  • Keeps their roles, groups and tokens, so reactivating them restores the same account and access.
  • Applies even if they're in a group you made in Autoheal.
  • Moves them off Users, group member lists and IAM to Users → ⋯ → Suspended users, which lists the roles they keep. Their page there lets an admin remove a role given to them directly; a role held through a group stays while they are in it. Reactivate them in your identity provider.

Removing someone (the identity provider deletes the user, usually when it's permanently deleted there):

  • Removes them from your organization: their roles, memberships of every group, and personal access tokens go, and they disappear from your user lists.
  • Keeps their history: investigations and the audit trail still show what they did.
  • Means the connection that removed them decides whether they come back. Invitations, from Users or by granting access on IAM, just-in-time sign-up and your other connections refuse their email. When that connection provisions them again, they come back as a new person with no roles or groups until you grant them. An admin can also allow them back on purpose with Allow a removed person back on Authentication → User provisioning; that is recorded in the access audit log. For this, Autoheal keeps the removed person's ID and a hash of their email, and records the removal by ID and name.
  • Doesn't erase every record of them. Earlier entries in the access audit log, such as when they were provisioned, linked, renamed or added to a group, keep the name and email recorded at the time. The access audit log is kept for as long as your organization exists, and people who hold audit:read can read it.

Either way, their access to any other Autoheal organization is unaffected. The last active person who can manage access in your organization can't be suspended or removed: give someone else that role first. Someone your identity provider suspended still holds their roles but can't use them, so they don't count: once it suspends one admin, another admin can't give up their own admin role if nobody else active could manage access.

More than one identity provider​

An organization can have up to five connections, one per identity provider, each with its own keys. Each provider sees and changes only the people and groups it provisioned.

  • A person belongs to the connection that reached them first. Another connection that sends the same email is refused with a conflict; nobody moves between connections on their own.
  • Two providers may sync groups with the same name. Each shows its own connection's badge.
  • Someone removed by one provider is refused by invitations, sign-up and your other providers. Only the provider that removed them can provision them again, unless an admin allows them back first.

Stop, replace a key, or remove a connection​

  • Stop provisioning on a connection refuses that provider's requests until you resume. Nothing it provisioned changes: suspended people stay suspended, and synced groups stay synced. Your other connections keep working.
  • To replace a key without interruption, rotate it, update your identity provider, then let the old key lapse. See API Credentials.
  • Remove connection hands what it manages back to you, in one audited step. Its people stay, with their roles and groups, active or suspended as they were, and become people you manage. Its groups become groups you made, keeping their members and roles. People it removed can be invited again. Its service account and keys are deleted. While one of its groups has the same name as a group you made, Remove connection stays disabled: rename or merge first. To let someone it had suspended back in, open Users → ⋯ → Suspended users, then their page, and select Reactivate.

Limits​

Connections per organization5
Members per synced group10,000
Results per page100
Requests per key1,500 a minute; above that, requests are refused with 429 for the identity provider to retry
Changes at once per organization4 per Autoheal server; above that, 429 with Retry-After, which the identity provider retries
Not supportedBulk requests, nested groups, managers, sorting

Troubleshooting​

Test Connection fails with 401

The key is wrong, expired or revoked, or provisioning is stopped. Create a key on Authentication → User provisioning, or resume provisioning.

Requests fail with 403

SCIM provisioning isn't turned on for your organization. Contact Autoheal support.

A person isn't created: 409 conflict

Either another provisioned person already has that user name, another connection already manages the person, another connection removed someone with that email, or the email matches an account Autoheal can't link: more than one account, an unverified email, or a suspended account. See People who are already in Autoheal and Offboarding.

A group push fails: 409 conflict

This connection already has a group with that name. A group with that name made in Autoheal never causes this: both are kept, and User groups asks for a review.

A group member is refused: 400

The member isn't a person this connection provisioned. Assign them in your identity provider so they're provisioned first.

An email change is refused: 409

The person can manage access in your organization or one of its projects, so your identity provider can't change the email they sign in with on its own. Anything else in the same update, such as disabling them, still applies. Another admin confirms the new email on the person's page under Users; the identity provider's next sync then goes through.

Suspending or removing someone fails: 409

They are the last active person who can manage access. Give someone else that role on IAM, then let your identity provider retry.