Skip to content
Docs

SAML SSO Setup

Let employees sign in to AgentWatch with your IdP. The steps are the same for Entra ID / Okta / any SAML 2.0 IdP; Google Workspace is shown. Dream big, build fast.

Concept: AgentWatch is the Service Provider (SP); your IdP asserts the user’s identity. You exchange two things: AgentWatch’s ACS URL + SP Entity ID go into the IdP; the IdP’s SSO URL + Entity ID + signing certificate go into AgentWatch.

1. Create the SAML provider in AgentWatch

Section titled “1. Create the SAML provider in AgentWatch”

Settings → Single Sign-On → Add Authentication → SAML 2.0. Enter, from your IdP’s metadata:

  • SAML Issuer (IdP Entity ID) — e.g. https://accounts.google.com/o/saml2?idpid=…
  • SAML Entry Point (IdP SSO URL) — e.g. https://accounts.google.com/o/saml2/idp?idpid=…
  • Certificate — the IdP’s <X509Certificate> (PEM-wrapped: -----BEGIN CERTIFICATE----- … -----END CERTIFICATE-----)
  • Optionally a logo (paste an https URL or upload a local PNG/JPG/SVG — no CDN needed).

Save. AgentWatch now shows the SP values you need:

  • ACS URL — https://<your-host>/<tenant>/… /api/auth/saml/callback/<providerId>
  • SP Entity ID — …/api/auth/saml/metadata/<providerId>

(Click Edit on the provider any time to copy them; or fetch GET /api/auth/saml/metadata/<providerId>.)

2. Configure the app in Google Admin

Section titled “2. Configure the app in Google Admin”

Apps → Web and mobile apps → Add app → Add custom SAML app.

  1. Download Google’s IdP metadata (that’s the Issuer/SSO-URL/cert for step 1).
  2. Service provider details: paste AgentWatch’s ACS URL and Entity ID.
  3. Name ID: format EMAIL, value = Basic Information → Primary email.
  4. Turn the app ON for the right org unit / group.

3. Sign in (SP-initiated)

Section titled “3. Sign in (SP-initiated)”

Go to the AgentWatch login page → “Sign in with ”. You’re redirected to the IdP, authenticate, and land back signed in. First-time users are auto-provisioned per your group mappings (if enabled).

Troubleshooting

Section titled “Troubleshooting”
  • Google shows 403 app_not_configured_for_user (“Service is not configured for this user”). SP-initiated SAML is working (AgentWatch redirected you to Google) — this error is on Google’s side and means the user Google is authenticating is not one the SAML app applies to. Fix both: (1) the signer must be a real account in this Google Workspace directory — a placeholder like janedoe@exampletenant.com doesn’t exist in the directory, so use a real @your-workspace-domain user (click “Use a different account” and make sure the browser’s active Google session is that user); and (2) in Google Admin → Apps → Web and mobile apps → your AgentWatch SAML app → User access, turn the app ON for that user’s Org Unit / group. The email you type on the AgentWatch login only selects the tenant/provider for the SAMLRequest — Google authenticates whoever’s Google session is active.
  • Google shows 400 malformed_certificate on “TEST SAML LOGIN”. The IdP app’s certificate is expired or malformed — regenerate the certificate in the Google SAML app, re-download metadata, and re-paste the new certificate into AgentWatch. Prefer testing via SP-initiated login (the AgentWatch login button), not Google’s IdP-initiated “TEST SAML LOGIN.”
  • AgentWatch “Test” flags the certificate. The SAML Test button validates the IdP URL + parses the certificate and reports if it’s expired/malformed — fix it at the IdP and re-import.
  • Nothing happens / old builds. Tenant SP-initiated SAML requires 2.0.198+. On older builds the login button did not redirect. Upgrade the deployment.
  • No provider found. The provider must be enabled and in the same organization/tenant you’re signing into.

© Iterate.ai · AgentWatch · Dream big, build fast.