Skip to content
Docs

Single Sign-On (SSO)

AgentWatch supports enterprise single sign-on through two protocols:

  • OIDC/OAuth2 — works with any standards-compliant OpenID Connect provider (Google Workspace, Microsoft Azure AD, Okta, Auth0, GitHub, Keycloak, and more).
  • SAML 2.0 — works with SAML identity providers (Microsoft Entra ID, Okta, PingFederate, ADFS, and others). Use SAML when your IdP does not support OIDC or when enterprise policy mandates SAML.

Both protocols share the same user provisioning pipeline, domain restriction enforcement, and pending-approval workflow.

How It Works — OIDC/OAuth2

Section titled “How It Works — OIDC/OAuth2”
User clicks "Sign in with <Provider>"
         │
         ▼
┌────────────────────────────────────────────────────────┐
│  AgentWatch OIDC Auth Layer                            │
│                                                        │
│  1. Fetch OIDC discovery doc from issuer URL           │
│     (<issuer>/.well-known/openid-configuration)        │
│     → authorization_endpoint, token_endpoint, jwks_uri │
│     (discovery result cached for 1 hour)               │
│                                                        │
│  2. Generate state + nonce (expire in 10 minutes)      │
│  3. Redirect user to identity provider                 │
└────────────────────────────────────────────────────────┘
         │
         ▼
  Identity Provider (Google / Azure AD / Okta / etc.)
  User authenticates and consents
         │
         ▼  (Authorization code + state returned)
┌────────────────────────────────────────────────────────┐
│  AgentWatch OIDC Callback Handler                      │
│                                                        │
│  4. Validate state (CSRF protection)                   │
│  5. Exchange code → access token + id_token            │
│  6. Fetch user profile from userinfo endpoint          │
│  7. Validate email domain (if domainRestriction set)   │
│  8. Provision user (see Auto-Provisioning below)       │
│  9. Issue AgentWatch session token + JWT               │
│ 10. Redirect to /admin/sso-callback?token=…&sess=…     │
└────────────────────────────────────────────────────────┘
         │
         ▼
  User logged in to AgentWatch dashboard

How It Works — SAML 2.0

Section titled “How It Works — SAML 2.0”
User clicks "Sign in with <Provider>"
         │
         ▼
┌────────────────────────────────────────────────────────┐
│  AgentWatch SAML Auth Layer                            │
│                                                        │
│  1. Generate SAML AuthnRequest (unsigned)              │
│  2. Redirect user to IdP entry point (SSO URL)         │
└────────────────────────────────────────────────────────┘
         │
         ▼
  Identity Provider (Entra ID / Okta / ADFS / etc.)
  User authenticates; IdP issues SAML Assertion
         │
         ▼  (IdP POSTs assertion to AgentWatch callback)
┌────────────────────────────────────────────────────────┐
│  AgentWatch SAML Callback Handler                      │
│                                                        │
│  3. Validate assertion signature (using SP certificate)│
│  4. Extract email + display name from SAML attributes  │
│  5. Validate email domain (if domainRestriction set)   │
│  6. Provision user (see Auto-Provisioning below)       │
│  7. Issue AgentWatch session token + JWT               │
│  8. Redirect to /admin/sso-callback?token=…&sess=…     │
└────────────────────────────────────────────────────────┘
         │
         ▼
  User logged in to AgentWatch dashboard

SAML Single Logout (SLO): SLO is not yet supported. Logging out of AgentWatch does not propagate to the IdP. Enterprise SLO is on the roadmap.

Provider Fields Reference

Section titled “Provider Fields Reference”

OIDC/OAuth2 Fields

Section titled “OIDC/OAuth2 Fields”
Field Required Description
Protocol Yes Select OIDC
Display Name Yes Label shown on the login page button (e.g., Acme Corp SSO)
OIDC Issuer URL Yes Base URL of the IdP. AgentWatch appends /.well-known/openid-configuration to discover endpoints automatically.
Client ID Yes OAuth2 application/client ID from the IdP
Client Secret Yes OAuth2 client secret. Stored encrypted; never exposed after saving.
Callback / Redirect URI Auto-filled Copy this value into your IdP app registration — this is where the IdP sends users after authentication.
Scopes Yes OAuth2 scopes. Use openid profile email for standard OIDC providers.
Domain Restriction No Comma-separated email domains (e.g., yourcompany.com,partner.com). Leave blank to allow any domain.
Default Role Yes Role for auto-provisioned users: admin, manager, viewer
Enabled Yes Toggle the provider on/off without deleting it
Auto-create users Yes on: new SSO users are provisioned automatically. off: users must be pre-created or manually approved.

SAML 2.0 Fields

Section titled “SAML 2.0 Fields”
Field Required Description
Protocol Yes Select SAML
Display Name Yes Label shown on the login page button
IdP Entry Point (SSO URL) Yes The SAML SSO endpoint from your IdP (e.g., from Entra ID federation metadata: SingleSignOnService Location)
IdP Issuer / Entity ID Yes The IdP’s entity identifier URI (from federation metadata: entityID attribute)
IdP Certificate Yes The X.509 certificate used by the IdP to sign SAML assertions. Paste the base64-encoded certificate body (without PEM headers).
SP Callback URL Auto-filled The URL your IdP must POST the SAML assertion to. Copy this into your IdP’s application as the Reply URL / ACS URL.
SP Entity ID / Identifier Auto-filled The AgentWatch service provider entity ID. Copy this into your IdP’s application as the Identifier (Entity ID).
SP Metadata URL Auto-filled GET /api/auth/saml/metadata/:providerId — download the full SP metadata XML to upload into your IdP if it supports metadata import.
Domain Restriction No Same as OIDC — comma-separated email domains.
Default Role Yes Role for auto-provisioned users
Enabled Yes Toggle on/off
Auto-create users Yes Controls provisioning behavior (see Auto-Provisioning below)

Important: If you see “No account found” after SSO login, either enable Auto-create users or pre-create the user account in AgentWatch first.

General Setup Steps

Section titled “General Setup Steps”
  1. Navigate to Settings → SSO Providers in the AgentWatch dashboard.
  2. Click New Provider.
  3. Select the Protocol: OIDC or SAML.
  4. Select a Quick-Start Template matching your identity provider (Google, Microsoft Entra ID, Okta, Auth0, GitHub, or Custom OIDC/SAML).
  5. Fill in the provider-specific fields (see per-provider guides below).
  6. Copy the Callback URI (and SP Metadata URL for SAML) shown in the form — paste these into your identity provider’s application registration.
  7. Set Domain Restriction if you want to limit logins to specific email domains.
  8. Choose the Default Role for auto-provisioned users.
  9. Configure Auto-create users based on your provisioning policy (see Pending Approval below for the manual-approval workflow).
  10. Toggle Enabled on.
  11. Click Save.
  12. Test by clicking the provider button on the login page.

Provider Setup: Google Workspace (OIDC)

Section titled “Provider Setup: Google Workspace (OIDC)”

Step 1 — Create OAuth2 credentials in Google Cloud Console

  1. Go to console.cloud.google.com → APIs & Services → Credentials.
  2. Click Create Credentials → OAuth client ID.
  3. Select Web application as the application type.
  4. Under Authorized redirect URIs, add the Callback URI from AgentWatch (e.g., https://agentwatch.yourcompany.com/api/auth/sso/callback).
  5. Click Create — note the Client ID and Client Secret.

Step 2 — Configure in AgentWatch

Field Value
Protocol OIDC
Template Google Workspace
Display Name Google Workspace (or your company name)
OIDC Issuer URL https://accounts.google.com
Client ID Paste from Google Cloud Console
Client Secret Paste from Google Cloud Console
Scopes openid profile email
Domain Restriction yourcompany.com (recommended for Workspace)
Default Role viewer
Auto-create users Enabled

Step 3 — Restrict to your Workspace domain (recommended)

In Google Cloud Console → OAuth consent screen, set the app to Internal (only users in your Google Workspace organization can authenticate). Combined with AgentWatch’s Domain Restriction, this gives you two layers of protection.

Provider Setup: Microsoft Azure AD (OIDC)

Section titled “Provider Setup: Microsoft Azure AD (OIDC)”

Use this setup when you want standard OIDC-based SSO with Azure AD. For SAML 2.0 with Microsoft Entra ID, see the next section.

Step 1 — Register an application in Azure

  1. Go to portal.azure.com → Microsoft Entra ID → App registrations → New registration.
  2. Enter a name (e.g., AgentWatch SSO).
  3. Under Redirect URI, select Web and paste the Callback URI from AgentWatch.
  4. Click Register.
  5. Go to Certificates & secrets → New client secret — copy the secret value immediately (it’s hidden after you leave the page).
  6. On the Overview page, copy the Application (client) ID.

Step 2 — Configure in AgentWatch

Field Value
Protocol OIDC
Template Microsoft Azure AD
Display Name Microsoft / Azure AD
OIDC Issuer URL https://login.microsoftonline.com/<your-tenant-id>/v2.0 (replace with your Azure Tenant ID)
Client ID Application (client) ID from Azure
Client Secret Secret value from step 1
Scopes openid profile email
Domain Restriction yourcompany.com
Auto-create users Enabled

Tip: For single-tenant apps, use your specific tenant ID in the issuer URL. For multi-tenant apps, use common instead.

Provider Setup: Microsoft Entra ID (SAML 2.0)

Section titled “Provider Setup: Microsoft Entra ID (SAML 2.0)”

Use this setup when your enterprise requires SAML 2.0 federation with Microsoft Entra ID (formerly Azure Active Directory).

Step 1 — Create an Enterprise Application in Entra ID

  1. Go to portal.azure.com → Microsoft Entra ID → Enterprise applications → New application.
  2. Click Create your own application, name it (e.g., AgentWatch), and select Integrate any other application you don’t find in the gallery (Non-gallery).
  3. Click Create.
  4. Go to Single sign-on → SAML.
  5. In Basic SAML Configuration, set:
    • Identifier (Entity ID): Copy the SP Entity ID shown in AgentWatch’s SAML provider form.
    • Reply URL (Assertion Consumer Service URL): Copy the SP Callback URL from AgentWatch (e.g., https://agentwatch.yourcompany.com/api/auth/saml/callback/<provider-id>).
    • Sign on URL (optional): Your AgentWatch login page.
  6. Click Save.
  7. Under SAML Certificates, download the Federation Metadata XML or copy the Certificate (Base64) value.
  8. On the Set up AgentWatch panel, note the Login URL (entry point) and Azure AD Identifier (issuer).

Step 2 — Configure in AgentWatch

Field Value
Protocol SAML
Template Microsoft Entra ID
Display Name Microsoft Entra ID (or your company name)
IdP Entry Point (SSO URL) Login URL from step 1 (e.g., https://login.microsoftonline.com/<tenant-id>/saml2)
IdP Issuer / Entity ID Azure AD Identifier from step 1 (e.g., https://sts.windows.net/<tenant-id>/)
IdP Certificate Base64 certificate body from the downloaded certificate (without -----BEGIN CERTIFICATE----- headers)
Domain Restriction yourcompany.com
Default Role viewer
Auto-create users Enabled (or disabled for manual approval)

Step 3 — Assign users

In the Entra ID Enterprise Application → Users and groups, add the users or groups that should have access.

Provider Setup: Okta (OIDC)

Section titled “Provider Setup: Okta (OIDC)”

Step 1 — Create an OIDC Web Application in Okta

  1. In your Okta Admin Console, go to Applications → Applications → Create App Integration.
  2. Select OIDC – OpenID Connect, then Web Application.
  3. Under Sign-in redirect URIs, paste the Callback URI from AgentWatch.
  4. Assign the application to users/groups as needed.
  5. Copy the Client ID and Client Secret from the app’s General tab.

Step 2 — Configure in AgentWatch

Field Value
Protocol OIDC
Template Okta
Display Name Okta SSO
OIDC Issuer URL https://your-domain.okta.com (replace your-domain)
Client ID From Okta app
Client Secret From Okta app
Scopes openid profile email
Domain Restriction yourcompany.com
Auto-create users Enabled

Provider Setup: Auth0 (OIDC)

Section titled “Provider Setup: Auth0 (OIDC)”

Step 1 — Create a Regular Web Application in Auth0

  1. Go to manage.auth0.com → Applications → Create Application.
  2. Choose Regular Web Applications.
  3. Under Settings → Allowed Callback URLs, paste the Callback URI from AgentWatch.
  4. Save changes and copy the Client ID and Client Secret.

Step 2 — Configure in AgentWatch

Field Value
Protocol OIDC
Template Auth0
Display Name Auth0 SSO
OIDC Issuer URL https://your-tenant.auth0.com (replace your-tenant)
Client ID From Auth0 application
Client Secret From Auth0 application
Scopes openid profile email
Domain Restriction Optional
Auto-create users Enabled

Provider Setup: GitHub (OAuth2)

Section titled “Provider Setup: GitHub (OAuth2)”

Note: GitHub OAuth is not a standards-compliant OIDC provider and does not support OIDC discovery. Use GitHub for developer-facing access only; prefer a proper OIDC provider for enterprise workforce SSO.

Step 1 — Create a GitHub OAuth App

  1. Go to github.com/settings/developers → OAuth Apps → New OAuth App (personal) or your GitHub Organization settings for org-level apps.
  2. Set the Authorization callback URL to the Callback URI from AgentWatch.
  3. Click Register application — copy the Client ID.
  4. Click Generate a new client secret — copy the secret.

Step 2 — Configure in AgentWatch

Field Value
Protocol OIDC
Template GitHub
Display Name GitHub
OIDC Issuer URL https://token.actions.githubusercontent.com
Client ID From GitHub OAuth App
Client Secret From GitHub OAuth App
Scopes read:user user:email
Domain Restriction Leave blank
Auto-create users Enabled

Provider Setup: Custom OIDC

Section titled “Provider Setup: Custom OIDC”

Use this template for any OIDC-compliant identity provider (Keycloak, PingFederate, OneLogin, Salesforce Identity, etc.).

Requirements:

  • The provider must expose <issuer>/.well-known/openid-configuration (OIDC Discovery)
  • Must support the authorization code flow
  • Must include email in the issued token claims

Configure in AgentWatch:

Field Value
Protocol OIDC
Template Custom OIDC
Display Name Your provider name
OIDC Issuer URL Your provider’s base URL (e.g., https://sso.yourcompany.com/realms/main)
Client ID From your provider’s app registration
Client Secret From your provider’s app registration
Scopes openid profile email (add custom scopes if needed)
Domain Restriction Optional
Auto-create users Based on your provisioning policy

Domain Restriction

Section titled “Domain Restriction”

When Domain Restriction is set, AgentWatch validates that the authenticated user’s email address ends with one of the specified domains before allowing login. This applies to both OIDC and SAML flows.

  • Enter a comma-separated list: yourcompany.com,subsidiary.com
  • The check is case-insensitive
  • Users whose email domain does not match receive an “Unauthorized domain” error and are not logged in, even if they successfully authenticated with the identity provider

Auto-Provisioning and Pending Approval

Section titled “Auto-Provisioning and Pending Approval”

When a user authenticates via SSO for the first time, AgentWatch applies the following logic:

autoCreateUsers User exists in AgentWatch Result
true Yes Log in as existing user
true No Create account with defaultRole, log in immediately
false Yes Log in as existing user
false No Account created with ssoStatus = pending; user is blocked until an admin approves

Pending Approval Workflow

When autoCreateUsers is disabled, newly provisioned SSO users are set to pending status. They cannot log in until an organization admin approves them:

  1. Admin navigates to Settings → SSO Providers → Pending Users.
  2. The list shows all users who signed in via SSO but have not yet been approved.
  3. Click Approve to allow the user to log in, or Reject to permanently block access.

Pre-create users by inviting them via Settings → Users → Invite User before they attempt SSO login to bypass the pending flow entirely.

SSO User Status Values

Status Meaning
none User was not created via SSO
pending SSO login attempted; awaiting admin approval
approved Approved — user can log in
rejected Rejected — user is disabled and cannot log in

Session Tokens for Tool Integration

Section titled “Session Tokens for Tool Integration”

After a successful SSO login (OIDC or SAML), AgentWatch issues a session token in addition to the short-lived dashboard JWT. Session tokens:

  • Format: sess_<uuid>
  • Default expiry: 30 days (configurable per organization)
  • Purpose: authenticate tool calls from editors (VS Code, Cursor, Cline, Continue) and API clients using the standard Authorization: Bearer sess_<...> header

Users can view and revoke their active session tokens under Profile → API Keys & Sessions.

API Reference

Section titled “API Reference”

Provider Management (requires Company Admin)

Section titled “Provider Management (requires Company Admin)”
Method Endpoint Description
GET /api/admin/oauth2/providers List all SSO providers for the organization
POST /api/admin/oauth2/providers Create a new OIDC or SAML provider
GET /api/admin/oauth2/providers/:id Get provider details
PUT /api/admin/oauth2/providers/:id Update provider configuration
DELETE /api/admin/oauth2/providers/:id Delete a provider

OIDC Authentication Endpoints (public)

Section titled “OIDC Authentication Endpoints (public)”
Method Endpoint Description
GET /api/auth/sso/providers List enabled SSO providers (used by the login page)
GET /api/auth/sso/authorize/:providerId Start the OIDC authorization code flow
GET /api/auth/sso/callback OIDC callback handler (state + code exchange)

SAML 2.0 Authentication Endpoints (public)

Section titled “SAML 2.0 Authentication Endpoints (public)”
Method Endpoint Description
GET /api/auth/saml/metadata/:providerId Download SP metadata XML (for IdP registration)
GET /api/auth/saml/authorize/:providerId Generate SAML AuthnRequest and redirect to IdP
POST /api/auth/saml/callback/:providerId SAML assertion callback handler

Pending User Management (requires users.read / users.write permission)

Section titled “Pending User Management (requires users.read / users.write permission)”
Method Endpoint Description
GET /api/tenant/sso/pending-users List SSO users awaiting approval
POST /api/tenant/sso/approve-user Approve a pending user ({ userId })
POST /api/tenant/sso/reject-user Reject a pending user ({ userId })