Provisioning With SCIM
HYPR AgentPass™ accepts System for Cross-domain Identity Management (SCIM) 2.0 provisioning from your identity provider. The people and groups you assign in your directory appear on the People page before anyone signs in. Assign an agent to a provisioned group, and its members can use the agent as soon as they enroll.
The console has setup hints for Okta, Microsoft Entra ID and Ping, and for any other SCIM 2.0 client.
Connect Your Identity Provider
The endpoint URL and the token are on the Directory / SCIM Provisioning card, on the Directory / SCIM tab of Settings → Gateway settings. Changing the card needs Settings: Edit, which Admin has. A role with only Settings: View sees the card read-only.
- In Settings → Gateway settings, click the Directory / SCIM tab.
- Under Identity provider, choose your provider. A hint then shows where each value goes in that provider.
- Under Bearer token, click Generate token. A dialog shows the token. This is the only time it is shown.
- Click Copy, and paste the token into your identity provider's SCIM connection.
- Click Done.
- Under SCIM Base URL, click Copy, and paste the URL into the same connection.
- Turn on Enable SCIM provisioning. The tag beside the card title changes from Not connected to Waiting for first request.
- In your identity provider, map the person's email to
emails[primary]. See How AgentPass Reads a Person. - In your identity provider, assign the people to provision, and then the groups. See Provision People Before Groups.
The tag changes to Receiving once a request from your identity provider succeeds, and stays so while requests keep succeeding. To see what your identity provider sent, check Recent SCIM Activity.
AgentPass records the Identity provider choice with every person and group it provisions, and matches later updates against it. Choose it before you turn on provisioning, and keep it unchanged afterward.
Rotate or Revoke the Token
The token is write-only. After its dialog closes, the card shows only a Configured tag, and the token can't be read again.
To replace the token, click Rotate token, and paste the new token into your identity provider. Rotation takes effect at once. The previous token stops working, and your identity provider's calls fail until it has the new one. If you lose the token, rotate it.
To revoke the current token, rotate it and keep the new one out of your identity provider. To stop all provisioning, turn off Enable SCIM provisioning. AgentPass then refuses every SCIM call. People and groups already provisioned stay as they are.
What Your Identity Provider Can Do
AgentPass supports these operations on the two SCIM resources:
| Resource | Supported operations |
|---|---|
| Users | Create, read, list, look up by userName, email or externalId, replace, update active and name attributes, and delete |
| Groups | Create, read, list, look up by displayName or externalId, replace, update members and displayName, and delete |
Your identity provider can also read the ServiceProviderConfig, ResourceTypes and Schemas endpoints to learn what AgentPass supports. Keep these limits in mind:
- A lookup takes a single
eqfilter on one attribute. - Bulk operations, sorting, ETags and password changes are not supported.
- AgentPass ignores user attributes it doesn't use, such as phone numbers and job titles.
How AgentPass Reads a Person
AgentPass identifies each person by email. It takes the email from the first of these that has a value:
- The
emailsentry marked primary - The first
emailsentry userName, only when it is an email address
A person with no usable email is rejected. In Microsoft Entra ID, userName is the user principal name, which may not be the mailbox. Map the mailbox to emails[primary] so that invitations reach the person.
AgentPass reads these other attributes:
| Attribute | What AgentPass does with it |
|---|---|
externalId | Matches later updates to the same person |
active | Sets whether the person can sign in and use agents. false deactivates them |
name, displayName | Sets the name shown in the console. AgentPass uses name.formatted first, then name.givenName with name.familyName, then displayName |
A few rules apply to every provisioned person:
- The email is fixed. An update that changes a provisioned person's email is rejected, and the person keeps their address.
- Existing people are adopted. If someone with the same email already signed in or was added another way, your directory takes over that record. An email that another directory identity already owns is rejected.
- New people can be invited automatically. With Auto-invite on provision turned on, each newly provisioned active person gets an invitation to enroll a passkey. See Gateway Settings → Email / Invitations.
- Roles come from sign-in. A provisioned person gets a role when they sign in, from your identity provider's mapped values or the default role. See Map Identity Provider Values to a Role.
Deactivating or Deleting a Person
Deactivating or deleting a person in your directory offboards them in AgentPass, the same way an administrator does in the console. See Offboard a Person.
The two directory actions differ in what they leave behind:
| In your directory | In AgentPass |
|---|---|
| Deactivate the person | Access is revoked and sign-in is blocked. The record stays, and appears when you select Show offboarded |
| Delete the person | Access is revoked, and the record is removed |
In both cases, AgentPass revokes the person's agent access, ends their sessions and disconnects their tool connections. It also removes them from their groups and agent assignments, and removes their role. Deactivate rather than delete to keep the person's record and offboarding history.
A deactivated person comes back through your directory only. Invite again is unavailable for them in the console. Reactivate them in your directory, and they can sign in again. Their agents and credentials are not restored, so assign their agents or push their groups again. They get a role at their next sign-in.
How Provisioned Groups Behave
A group that your identity provider pushes appears on the Groups tab of People. Its Source reads Imported, with the provider's name.
- Read-only in the console. Its name and members come from your directory, so change them there. The console has no edit or delete control for it.
- Membership follows the directory. A full push replaces the member list, so anyone it no longer lists is removed. An incremental update adds or removes only the members it names.
- Renames follow. Renaming the group in your directory renames it in AgentPass.
- Assignable like any other group. Assign agents to it on an agent's Assignments tab. See Assigning an Agent to People.
Provision People Before Groups
AgentPass resolves each group member to a person it has already provisioned. A member your identity provider hasn't provisioned yet is left out of the group. Push people first, then groups.
If a group has fewer members than expected, provision the missing people, and push the group again.
Deleting a Group in the Directory
Deleting a provisioned group in your directory deletes it in AgentPass, along with every agent assignment made to that group. People who reached an agent only through that group lose access to it.
Check Recent SCIM Activity
Recent SCIM activity, on the same card, lists the requests your identity provider sent with this tenant's token, and how each one resolved. Choose the Activity period: Last 24 hours, 7 days or 30 days. Counts of Accepted, Failed and Turned away requests sit above the list. Each row shows When, Operation, Target and Outcome. Hover over an outcome to see its detail. Click Refresh to load newer requests, or Load more for older ones.
Requests without a valid token are turned away and not listed. One line says how many there were in the period. When that count grows and your identity provider has stopped syncing, check the token it holds. See Gateway Settings → Directory / SCIM for the Failed sign-in limit.
When a call fails, your identity provider reports the response. This table maps each common response to what to check:
| Response | What to check |
|---|---|
404 on every call, including a connection test | Enable SCIM provisioning is off. Turn it on |
| An authentication error, with the requests counted as Turned away | The token in your identity provider doesn't match. Rotate the token, and paste the new one |
400, missing a usable email | Map the person's email to emails[primary] |
400, email is immutable | The update changes a provisioned person's email, which stays fixed |
| A group with fewer members than expected | Provision the missing people, and push the group again |
Related
- Groups — create groups in the console, and use any group to share an agent
- Users — where people come from, and offboarding
- Roles and Permissions — provisioning creates people; roles decide what they may do
- Gateway Settings — every settings tab, including Directory / SCIM