SSO & Identity

Configure identity organizations, domain verification, Single Sign-On (SSO), and Directory Sync to control how users authenticate to Agent Identity Security and how their roles are assigned automatically.

The SSO & Identity page is available under Settings > SSO & Identity. Use this page to connect Agent Identity Security to your organization's identity provider (IdP) so that users can sign in with their corporate credentials, and so that user accounts and roles are managed automatically through Directory Sync.

The recommended setup order is:

  1. Create an identity organization
  2. Verify domain ownership
  3. Configure the SSO connection
  4. Configure Directory Sync
  5. Configure role mapping
  6. Verify the setup with a test user

Who does what

Table 1. Roles and responsibilities
Role Responsibility
Agent Identity Security System Admin Creates the organization in Agent Identity Security, opens Admin Portal links, and monitors configuration status.
IdP Admin (Entra ID, Okta, and so on) Configures the enterprise application, user and group assignments, and provisioning in your identity provider.

What you need before you begin

  • 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 email domain or domains your users sign in with — for example, acme.com.
  • DNS access, if domain verification is required for your email domain.

Key concepts

Organization

An organization represents a single IdP configuration in Agent Identity Security. One organization equals one identity provider connection — for example, one Entra ID tenant or one Okta org.

If your company uses multiple identity providers — for example, Entra ID for corporate users and Okta for a subsidiary — create one organization per identity provider.

The first organization uses your tenant name automatically. Additional organizations require a unique name that cannot be changed after saving.

Email domain

The email domain is the part after @ in a user's email address. For example, for [email protected], the domain is acme.com.

At login, Agent Identity Security checks the user's email domain against configured organizations and routes the user to the matching identity provider. You can assign multiple domains per organization using comma-separated values — for example, acme.com, acme.io.

  1. Create an identity organization.
    Tip: Skip this step if an organization already exists for your tenant.
    1. Sign in to Agent Identity Security as a System Admin.
    2. Go to Settings > SSO & Identity.
    3. Under Identity Organizations, select + Add organization.
    4. If this is an additional organization — not the first — enter a unique Organization name.
      Important: The organization name is required for additional organizations and cannot be changed after saving. Choose a name that clearly identifies the organization or tenant — for example, subsidiary or labokta.
    5. In the Email domains (comma-separated) field, enter the email domain or domains associated with this organization.

      Example: acme.com, acme.io

    6. Select Save.

    The organization card appears in the Identity Organizations list, showing the organization name, its WorkOS organization ID, the configured email domains, and an Admin Portal section with links for Domain Verification, SSO Configuration, and Directory Sync.

  2. Verify domain ownership.

    Domain verification confirms that your organization owns the email domain before SSO can activate. Check the status badge on Domain Verification to determine what action to take:

    • Not configured — Setup has not started. Proceed with the steps below.
    • In progress — Setup is underway. Complete remaining steps in the Admin Portal.
    • Configured — Verification is complete. Skip this step.
    1. On the organization card, locate Domain Verification under Admin Portal.
    2. Select Open to launch the Admin Portal in a new browser tab.

      If your IdP admin will handle DNS changes, use Copy to share the Admin Portal link, or Invite to send it by email — your IdP admin does not need access to Agent Identity Security to complete this step.

    3. Follow the instructions in the Admin Portal to add the DNS records provided to your domain registrar or DNS provider.
    4. Return to Settings > SSO & Identity and select Refresh status on the organization card.

    The Domain Verification badge updates to Configured when verification is complete.

  3. Configure Single Sign-On.

    SSO allows users to sign in to Agent Identity Security using their corporate identity provider credentials. Domain verification must show a Configured status before SSO Configuration can be activated.

    1. On the organization card, locate SSO Configuration under Admin Portal and select Open.

      Use Copy or Invite to share the link with your IdP admin if they do not have access to Agent Identity Security.

    2. In the Admin Portal, select your identity provider — for example, Microsoft Entra ID, Okta, or Google SAML.
    3. Follow the on-screen instructions in the Admin Portal. This typically involves the following actions in your IdP:
      • Creating an enterprise application in your IdP.
      • Copying SAML or OIDC metadata between the Admin Portal and your IdP.
      • Assigning users or groups to the application in your IdP.

      For provider-specific instructions, see Microsoft Entra ID or Identity Provider Overview.

    4. Complete all steps in the Admin Portal until SSO is marked as active, then return to Agent Identity Security and select Refresh status.

    The SSO Configuration badge updates to Configured. Users whose email domain matches this organization are now redirected to your identity provider at login.

    Note: When a user enters their email on the Agent Identity Security login page, Agent Identity Security checks the email domain against configured organizations and redirects the user to the matching identity provider via the Admin Portal.
  4. Configure Directory Sync.

    Directory Sync uses automatically provision and deprovision users in Agent Identity Security based on your identity provider's directory. It also handles role assignment through group-to-role mapping.

    Important: Directory Sync is strongly recommended. Without it, SSO users receive the default Read Only Admin role until their role is manually updated. SSO users cannot have their roles changed manually in Agent Identity Security — the identity provider and Directory Sync are the source of truth for role assignment.
    1. On the organization card, locate Directory Sync under Admin Portal and select Open.
    2. In the Admin Portal, connect your IdP directory — for example, Entra ID provisioning or Okta.
    3. Follow the instructions in the Admin Portal to configure the endpoint and bearer token in your IdP.
    4. Complete all steps in the Admin Portal until Directory Sync is active, then return to Agent Identity Security and select Refresh status.

    The Directory Sync badge updates to Configured.

  5. Configure role mapping.

    Role mapping is configured in the Directory Sync section of the Admin Portal. It connects IdP groups to Agent Identity Security roles so that user roles are assigned and updated automatically on each sync.

    1. In your identity provider, create user groups that correspond to Agent Identity Security roles — for example, Agent Identity Security-Admins or Agent Identity Security-ReadOnly.
    2. Assign users to the appropriate groups in your IdP.
    3. In the Admin Portal Directory Sync configuration, map each IdP group to an Agent Identity Security role.

      Multiple IdP groups can map to a single Agent Identity Security role (many-to-one mapping is supported).

    4. Save the mapping and trigger a sync.
    5. In your IdP — for example, in Entra ID Enterprise Applications — confirm that users and groups are assigned to the Agent Identity Security application, then start provisioning or trigger an initial sync.

    Users are provisioned in Agent Identity Security with the roles defined by their IdP group membership.

    Note:

    Sync propagation speed varies by identity provider:

    Table 2. Directory Sync timing by identity provider
    Identity Provider Typical sync delay Faster option
    Microsoft Entra ID ~40 minutes for assignment changes Use Provision on demand in Entra to push individual users immediately.
    Okta Varies; often faster than Entra ID Use Push Groups or on-demand provisioning if available.
    Other IdPs See your IdP documentation Look for a manual or on-demand sync option.
  6. Verify the setup with a test user.
    1. Select a test user who is assigned to the IdP application and to a mapped group.
    2. Open the Agent Identity Security login page in a private or incognito browser window.
    3. Enter the test user's email address and confirm you are redirected to your IdP login page.
    4. Sign in with IdP credentials and confirm the user lands in Agent Identity Security with the expected role.
    5. In Agent Identity Security, go to Settings > Users & Roles and verify the user appears with auth_source = SSO.

    The test user signs in successfully through SSO and is assigned the correct role based on their IdP group membership.

When all three components — Domain Verification, SSO Configuration, and Directory Sync — show a Configured status and the test login succeeds, SSO is fully operational. Users whose email domains match the configured organization authenticate through your identity provider, and their accounts and roles are managed automatically through Directory Sync.

Adding multiple identity organizations

If your company uses more than one identity provider, repeat Steps 1 through 5 for each additional organization. On the SSO & Identity page, select + Add organization, enter a unique organization name and the email domains for that identity provider, and complete domain verification, SSO configuration, and Directory Sync.

At login, Agent Identity Security routes users to the correct organization and identity provider based on their email domain.

Admin Portal link options

For each configuration step, Agent Identity Security provides three ways to access or share the Admin Portal:

Table 3. Admin Portal link options
Button Action
Open Opens the Admin Portal in a new browser tab for the currently signed-in user.
Copy Copies the Admin Portal link to your clipboard so you can share it with your IdP admin.
Invite Sends the Admin Portal link by email to one or more recipients. Use this when your IdP admin does not have access to Agent Identity Security.

Setup checklist

  • Organization created with correct email domain or domains.
  • Domain ownership verified.
  • SSO configured — status shows Configured.
  • Directory Sync configured — status shows Configured.
  • Role mapping configured — IdP groups mapped to Agent Identity Security roles.
  • Users and groups assigned in the IdP application.
  • Provisioning started in IdP or on-demand sync triggered.
  • Test SSO login successful with expected role.

Troubleshooting

Table 4. SSO troubleshooting reference
Issue What to check
Login still asks for a password Email domain not added to any organization, or domain contains a typo. Check Settings > SSO & Identity and confirm the domain is listed correctly.
SSO badge shows In progress Complete the remaining steps in the Admin Portal.
User receives wrong role Check the Directory Sync role mapping. Confirm the user's IdP group is mapped to the correct Agent Identity Security role.
User not appearing in Agent Identity Security Directory Sync is not configured, or provisioning has not started in the IdP. Check sync status and trigger an on-demand sync if available.
IdP changes not reflected in Agent Identity Security Wait for the sync cycle to complete (~40 minutes for Entra ID), or use on-demand provisioning for immediate results.
Warning: SSO active but Directory Sync not configured Complete Step 4. Users can sign in but are not auto-provisioned with the correct roles until Directory Sync is active.
Domain verification failing DNS records have not been added or have not propagated yet. Re-check the DNS record instructions in the Admin Portal and allow time for propagation.