Set up SSO and Directory Sync for your Agent Identity Security tenant

Role	Responsibility
Agent Identity Security System Admin	Creates the identity provider configuration in Agent Identity Security, opens hosted setup, and monitors status.
IdP Admin (Entra, Okta, and so on)	Configures the enterprise application, user and group assignments, and SCIM provisioning in your identity provider.

Prerequisite

Make sure you have the following before you start:

An Agent Identity Security account with the System Admin role, or a role that includes the system_config:write permission.
Admin access to your company's identity provider (for example, Microsoft Entra ID, Okta, or Google Workspace).
The domain or domains your users sign in with (for example, acme.com). Agent Identity Security may already have a tenant login domain to prefill this value.

Where to go in Agent Identity Security: Go to Settings > SSO & Identity.

Important: A provider is complete only when domains, SSO, and Directory Sync are all configured. Complete all steps in order.

Key concepts

Identity provider configuration

An identity provider configuration is one IdP connection in Agent Identity Security. Keep the following in mind:

One configuration equals one identity provider for example, one Entra tenant or one Okta org.
If your company uses multiple identity providers, create one configuration per IdP.
The configuration name is required, must be unique, and can't be changed after you save.
Agent Identity Security doesn't show internal WorkOS IDs on this page.

Domain

A domain is the part of a user's email address after the @ symbol for example, [email protected] → acme.com. Agent Identity Security uses the domain at login to route the user to the correct identity provider. Keep the following in mind:

You can add multiple domains per configuration by separating them with commas for example, acme.com, acme.io.
Domains can't overlap with another configuration.
On the New Configuration page, if Agent Identity Security already has a tenant login domain, the Domains field is filled in and shown as read-only. Select Edit to change it before you save. If no login domain is available, enter the domain yourself.
Editing the domain on this form updates only this configuration. It doesn't change the tenant login domain.

Create a configuration

The configuration is the container for your identity provider connection. You must create it before you can set up SSO or Directory Sync.

Sign in to Agent Identity Security as a System Admin.
Go to Settings > SSO & Identity.
Do one of the following:
- If no providers exist, select Set up identity provider.
- If providers already exist, select Add.
On the New Configuration page, enter a unique Configuration name.

Tip: The configuration name can't be changed after you save. Choose a name that clearly identifies the identity provider.
Confirm the Domains field:
- If a tenant login domain is present, it appears as read-only. Select Edit only if you need to change it.
- If no tenant login domain is present, enter one or more comma-separated domains.
Select Save & Next.

Note: Save & Next remains unavailable until both the configuration name and domain fields are filled in.

After you save, Agent Identity Security stays on the New Configuration page and shows the saved name and domains, along with options to Configure SSO, Refresh, and Skip for now. Directory Sync options don't appear yet.

The configuration is saved. If the name you entered is already in use, Agent Identity Security displays: Configuration name '{name}' is already in use. Choose a different unique name and try again.

Configure SSO

SSO lets users sign in to Agent Identity Security with their corporate identity provider credentials. SSO is available only after the configuration has at least one domain.

What happens at login: When a user enters their email on the Agent Identity Security login page, Agent Identity Security checks the domain against your configurations and redirects them to the matching IdP.

Do one of the following:
- On the New Configuration page after Step 1, select Configure SSO.
- On an existing provider card, select Configure on the SSO row.
Complete the hosted setup: choose your identity provider, create the enterprise application, exchange SAML/OIDC metadata, and assign users or groups.
Return to Agent Identity Security and select Refresh.
Confirm the SSO row shows Configured and the button has changed to Manage.

Once SSO is configured, Skip for now is removed from the SSO row and Directory Sync options appear.

SSO is configured. If you need to finish later, select Skip for now to return to the Identity Providers list. The provider card shows Pending: Configure SSO (or Pending: SSO setup while setup is in progress).

Configure Directory Sync

Directory Sync automatically provisions and deprovisions users in Agent Identity Security from your IdP directory. It also handles role assignment through group-to-role mapping.

Important: Directory Sync is available only after SSO is configured. If the Directory Sync row is unavailable, hover over it for guidance: Configure SSO to make Directory Sync available.

Do one of the following:
- On the New Configuration page after SSO is configured, select Configure Directory Sync.
- On an existing provider card, select Configure on the Directory Sync row.
In the hosted setup, connect your IdP directory — for example, Entra SCIM or Okta SCIM.
Set up the SCIM endpoint and token, map IdP groups to Agent Identity Security roles, and assign users or groups.

Note: Multiple IdP groups can map to one Agent Identity Security role.
Return to Agent Identity Security and select Refresh.
Confirm the Directory Sync row shows Configured and the button has changed to Manage.
When both SSO and Directory Sync show Configured, select Done (bottom-right) to return to Settings > SSO & Identity.

Directory Sync is configured. The provider list status stays Pending: Configure Directory Sync (or Pending: Directory Sync setup) until this step is complete.

Start provisioning in your IdP

After hosted setup is complete:

Confirm users and groups are assigned to the Agent Identity Security application.
Start provisioning or enable SCIM sync in your IdP.
Trigger an initial sync if your IdP offers Provision on demand or Start provisioning.

Sync timing


IdP	Typical sync delay	Faster option
Microsoft Entra ID	About 40 minutes for assignment changes	Use Provision on demand in Entra
Okta	Varies; often faster than Entra	Use Push Groups or on-demand provisioning if available
Other IdPs	Check your IdP documentation	Look for manual or on-demand sync

Configure role mapping

Role assignment is configured in the Directory Sync hosted setup from Step 3.

In your IdP, create user groups that correspond to Agent Identity Security roles — for example, Agent Identity Security-Admins or Agent Identity Security-ReadOnly.
Assign users to those groups.
Map each IdP group to an Agent Identity Security role. Multiple IdP groups can map to one Agent Identity Security role.
Save the mapping and trigger a sync.

Role mapping is active. Keep the following rules in mind:

Agent Identity Security assigns one role per SSO user. The IdP and Directory Sync are the source of truth.
SSO users can't have their roles changed manually in Agent Identity Security through Users & Roles.
If no mapping matches, the user receives the default role (Read Only Admin) until mapping is configured.

Verify the setup

Pick a test user who is assigned to the IdP application and belongs to a mapped group.
Open the Agent Identity Security login page in a private or incognito browser window.
Enter the test user's email address.
Confirm you're redirected to your IdP login page.
Sign in with IdP credentials.
Confirm the user lands in Agent Identity Security with the expected role.
In Agent Identity Security, go to Settings > Users & Roles and verify the user appears with auth_source = SSO.

The setup is verified. The provider list shows a green check when domains, SSO, and Directory Sync are all configured.

Manage an existing configuration

On Settings > SSO & Identity, each provider card shows Domains, SSO, and Directory Sync in that order.

Table 1. Provider card actions
Action	What to expect
Edit (Domains)	Change comma-separated domains, then save. Selecting Cancel discards changes.
Configure / Manage	Opens hosted setup for SSO or Directory Sync. The button shows Configure until status is Configured, then changes to Manage.
Refresh	Reloads live status from the identity provider.
Delete	Available to users with write permissions even when only one provider remains. Users with those domains will no longer sign in through that provider.

Provider card status labels

Pending: Domains no domain added yet.
Pending: Configure SSO or Pending: SSO setup SSO not yet complete.
Pending: Configure Directory Sync or Pending: Directory Sync setup Directory Sync not yet complete.

Note: A green check appears only when domains, SSO, and Directory Sync are all configured. If SSO is configured and Directory Sync isn't, Agent Identity Security displays: SSO is active but Directory Sync is not configured. Users must be provisioned manually.

Note: Read-only users (system_config:read only) can view providers and statuses. They don't see Add, Edit, Delete, or Configure.

Add multiple identity providers

If your company uses more than one identity provider, create one configuration for each IdP:

Select Add on the Identity Providers page.
Enter a unique Configuration name and unique Domains.
Complete SSO and Directory Sync for that configuration (Steps 2–3).
At login, Agent Identity Security routes users by domain to the matching configuration and IdP.

Troubleshoot common issues


Issue	What to check
Login still asks for a password	The domain isn't added to any configuration, or there's a typo in the domain.
Save & Next stays unavailable	The Configuration name or Domains field is empty.
Configuration name '{name}' is already in use.	Choose a different unique name.
Domains overlap another provider	Each domain can belong to only one configuration.
SSO row is unavailable	Add at least one domain. Hover over the row for guidance: Add at least one domain to make SSO available.
Directory Sync row is unavailable	Configure SSO first. Hover over the row for guidance: Configure SSO to make Directory Sync available.
Provider still shows as pending after SSO	Complete Directory Sync. Status stays Pending: Configure Directory Sync until then.
User gets the wrong role	Check the Directory Sync role mapping and confirm the user's IdP group is correctly mapped.
User doesn't appear in Agent Identity Security	Directory Sync isn't configured, or provisioning hasn't been started in the IdP.
IdP changes aren't reflected in Agent Identity Security	Wait for the sync cycle (about 40 minutes for Entra) or use on-demand provisioning.
Warning: SSO active without Directory Sync	Complete Step 3. Users can sign in but aren't automatically provisioned with the correct roles.

Quick reference checklist

Use this checklist to confirm your setup is complete before going live.

Configuration created with a unique Configuration name and the correct domain or domains.
Tenant login domain reviewed on New Configuration; Edit used only if a different domain is required.
SSO configured and status shows Configured.
Directory Sync configured and status shows Configured.
Provider list shows a green check (no Pending label).
Role mapping configured IdP groups are mapped to Agent Identity Security roles.
Users and groups assigned in the IdP application.
Provisioning started in the IdP, or on-demand sync triggered.
Test SSO login successful with the expected role.