SSO & Identity

Configure identity organizations, domain verification, Single Sign-On, and Directory Sync so that users authenticate through your identity provider and roles are assigned automatically.

Go to Settings > SSO & Identity to connect Agent Identity Security to your identity provider. Each organization represents one IdP connection and is matched to users at login by email domain. Complete the steps in order for each organization you configure.

Note: A System Admin role is required to configure SSO & Identity. See Roles.

Prerequisites:

Before you begin, have the following ready:
  • Admin access to your 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.
  1. Create an identity organization.
    Tip: Skip this step if an organization already exists for your tenant.
    1. Under Identity Organizations, select + Add organization.
    2. If this is an additional organization, enter a unique Organization name.
      Important: The organization name cannot be changed after saving.
    3. Enter the email domain or domains in Email domains (comma-separated) — for example, acme.com, acme.io.
    4. Select Save.
    The organization card appears showing the organization name, ID, email domains, and Admin Portal links for Domain Verification, SSO Configuration, and Directory Sync.
  2. Verify domain ownership.

    Domain verification confirms your organization owns the email domain before SSO can activate. Check the status badge on the organization card:

    • Not configured not started.
    • In progress complete the remaining steps in the Admin Portal.
    • Configured complete, skip this step.
    1. On the organization card, select Open next to Domain Verification.

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

    2. Follow the Admin Portal instructions to add the DNS records to your domain registrar.
    3. Return to Settings > SSO & Identity and select Refresh status.
    The Domain Verification badge updates to Configured.
  3. Configure Single Sign-On.
    Note: Domain Verification must show Configured before SSO Configuration can be activated.
    1. On the organization card, select Open next to SSO Configuration.
    2. In the Admin Portal, select your identity provider and follow the on-screen instructions to complete the connection.

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

    3. Return to Agent Identity Security and select Refresh status.
    The SSO Configuration badge updates to Configured. Users whose email domain matches this organization are redirected to your identity provider at login.
  4. Configure Directory Sync.
    Important: Directory Sync is strongly recommended. Without it, SSO users receive a default Read Only Admin role until their role is manually updated. SSO user roles cannot be changed manually in Agent Identity Security the identity provider is the source of truth.
    1. On the organization card, select Open next to Directory Sync.
    2. In the Admin Portal, connect your IdP directory and follow the instructions to configure the endpoint and bearer token.
    3. Map IdP groups to Agent Identity Security roles in the Admin Portal. Multiple groups can map to one role.
    4. Return to Agent Identity Security and select Refresh status.
    The Directory Sync badge updates to Configured. Users are provisioned with roles based on their IdP group membership.
  5. In your identity provider, confirm users and groups are assigned to the Agent Identity Security application, then start provisioning or trigger an initial sync.
    Note: Sync speed varies by provider. Microsoft Entra ID typically takes ~40 minutes; use Provision on demand to push individual users immediately. Okta is generally faster.
  6. Verify the setup with a test user.
    1. Open the Agent Identity Security login page in a private or incognito browser window and enter a test user's email address.
    2. Confirm you are redirected to your IdP login page, sign in, and confirm the user lands in Agent Identity Security with the expected role.
    3. In Agent Identity Security, go to Settings > Users & Roles and confirm the user appears with auth_source = SSO.
When Domain Verification, SSO Configuration, and Directory Sync all show Configured and the test login succeeds, SSO is fully operational for this organization.
Managing organizations
  • To update email domains, select Edit domains on the organization card.
  • To add another IdP, select + Add organization and repeat Steps 1–5 for the new organization.
  • To remove an organization, select Delete on the card.
    Warning: Deleting an organization removes its Domain Verification, SSO Configuration, and Directory Sync settings. Affected users lose SSO access. This action cannot be undone.