Agent Audit/Docs/Setup/SSO
SSO · 6 MINOIDC + SAML 2.0 · provider tabs

Single sign-on.

Wire your identity provider to Agent Audit so users at @yourcompany.com sign in via your IdP and land in the right tenant with the right role. Pick a provider tab below and follow the steps for your stack only.

Your Agent Audit endpoints.

Every IdP needs to know where to redirect to after sign-in. Paste these two values into your IdP's OAuth or SAML application configuration verbatim — trailing slash matters.

OIDC redirect URIhttps://www.agentaudit.co.uk/api/auth/sso/oidc/callback
SAML ACS URLhttps://www.agentaudit.co.uk/api/auth/sso/saml/acs
SAML Entity ID (SP)https://www.agentaudit.co.uk

Set up OIDC.

Pick the IdP you use. Each tab tells you exactly which buttons to click and what to copy back.

1. Create the OAuth 2.0 Client in Google Cloud

  1. Open Google Cloud Console → APIs & Services → Credentials.
  2. Click Create credentials → OAuth client ID.
  3. If asked, configure the consent screen first (Internal, app name "Agent Audit", logo optional).
  4. Application type: Web application.
  5. Name: Agent Audit.
  6. Authorised JavaScript origins → add https://www.agentaudit.co.uk.
  7. Authorised redirect URIs → add https://www.agentaudit.co.uk/api/auth/sso/oidc/callback.
  8. Click Create.

Google shows you the Client ID (long, ends in .apps.googleusercontent.com) and the Client secret (starts GOCSPX-).

2. Values for the Agent Audit form

  • Issuer URL: https://accounts.google.com
  • Client ID: the long …apps.googleusercontent.com string
  • Client secret: the GOCSPX-… string
  • Email domain: the domain users sign in with (eg. vpnetworks.co.uk)

1. Register Agent Audit in Microsoft Entra ID

  1. Open Microsoft Entra admin centre → Identity → Applications → App registrations.
  2. Click New registration.
  3. Name: Agent Audit.
  4. Supported account types: Single tenant (or multi-tenant if you sell to your customers' tenants too).
  5. Redirect URI: Web, value https://www.agentaudit.co.uk/api/auth/sso/oidc/callback.
  6. Register.

2. Mint a client secret

  1. In the new app → Certificates & secrets → New client secret.
  2. Description: Agent Audit SSO. Expires: 12-24 months (per your policy).
  3. Copy the Value column right now — you cannot view it again later.

3. Values for the Agent Audit form

  • Issuer URL: https://login.microsoftonline.com/<your-tenant-id>/v2.0 — the tenant id is on the app's Overview page as Directory (tenant) ID.
  • Client ID: the Application (client) ID on the Overview page (a UUID).
  • Client secret: the Value you copied above.
  • Email domain: the domain users sign in with.
Common gotcha: using https://login.microsoftonline.com/common/v2.0 as the issuer. That works for sign-in but the JWS validation rejects the resulting ID token because iss in the token is the per-tenant URL. Always use your tenant id in the issuer.

1. Create an OIDC Web App in Okta

  1. Sign in to your Okta admin console.
  2. Applications → Applications → Create App Integration.
  3. Sign-in method: OIDC — OpenID Connect. Application type: Web Application.
  4. Name: Agent Audit.
  5. Grant type: Authorization Code.
  6. Sign-in redirect URIs: https://www.agentaudit.co.uk/api/auth/sso/oidc/callback.
  7. Sign-out redirect URIs (optional): https://www.agentaudit.co.uk/dashboard/login/.
  8. Controlled access: pick the group(s) that should be allowed to sign in.
  9. Save. Okta shows you the Client ID and Client secret.

2. Values for the Agent Audit form

  • Issuer URL: https://<your-org>.okta.com (or the custom authorisation-server URL if you configured one).
  • Client ID: from the Okta app's General tab.
  • Client secret: from the Okta app's General tab.
  • Email domain: the domain users sign in with.

1. Create a Regular Web Application in Auth0

  1. Open Auth0 Dashboard.
  2. Applications → Create Application.
  3. Name: Agent Audit. Type: Regular Web Applications.
  4. On the new app → Settings tab.
  5. Allowed Callback URLs: https://www.agentaudit.co.uk/api/auth/sso/oidc/callback.
  6. Allowed Logout URLs: https://www.agentaudit.co.uk/dashboard/login/.
  7. Save changes.

2. Values for the Agent Audit form

  • Issuer URL: https://<your-tenant>.auth0.com/ — note the trailing slash; Auth0 includes it in iss.
  • Client ID: from the Settings tab.
  • Client secret: from the Settings tab.
  • Email domain: the domain users sign in with.

Set up SAML 2.0.

Use SAML if your IdP doesn't expose OIDC, or if your security team mandates it. Agent Audit accepts XML-DSIG-signed AuthnResponses against the certificate you upload; assertions are single-use within their provider (anti-replay).

1. Create a SAML 2.0 App in Okta

  1. Applications → Create App Integration → SAML 2.0.
  2. Name: Agent Audit.
  3. Single sign on URL: https://www.agentaudit.co.uk/api/auth/sso/saml/acs.
  4. Audience URI (SP Entity ID): https://www.agentaudit.co.uk.
  5. Name ID format: EmailAddress. Application username: Email.
  6. Attribute statements (add): email → user.email; displayName → user.displayName.
  7. Finish, then on the app's Sign On tab click View SAML setup instructions.

2. Values for the Agent Audit form

  • IdP SSO URL: the Identity Provider Single Sign-On URL Okta gives you.
  • Entity ID: Okta's Identity Provider Issuer.
  • IdP X.509 certificate (PEM): the PEM-formatted certificate Okta gives you (begins -----BEGIN CERTIFICATE-----).

1. Enable SAML on an Enterprise app

  1. Entra admin centre → Enterprise applications → New application → Create your own application.
  2. Name: Agent Audit. Choose Integrate any other application you don't find in the gallery.
  3. On the new app → Single sign-on → SAML.
  4. Basic SAML Configuration:
    • Identifier (Entity ID): https://www.agentaudit.co.uk
    • Reply URL (ACS): https://www.agentaudit.co.uk/api/auth/sso/saml/acs
  5. Attributes & Claims: keep the default emailaddress; add displayName if you want.
  6. SAML Certificates → download the Certificate (Base64).

2. Values for the Agent Audit form

  • IdP SSO URL: the Login URL from the Set up section.
  • Entity ID: the Azure AD Identifier from the Set up section.
  • IdP X.509 certificate (PEM): the contents of the downloaded Certificate (Base64).

1. Any SAML 2.0 IdP

Configure your IdP to send an AuthnResponse to the ACS URL with the SP Entity ID below. The response (or assertion) must be XML-DSIG signed with one of:

  • RSA-SHA256 / SHA384 / SHA512
  • ECDSA-SHA256 / SHA384 / SHA512

SHA-1 signatures are explicitly rejected.

2. Required claims

  • NameID: emailAddress format, or an attribute named email / mail.
  • Issuer: must match the Entity ID configured in Agent Audit.
  • AudienceRestriction: must include https://www.agentaudit.co.uk.
  • Conditions.NotBefore / NotOnOrAfter: a clock-skew of 120s is allowed.
  • SubjectConfirmationData.NotOnOrAfter: in the future.

Save the provider in Agent Audit.

  1. Sign in to /dashboard/ as an admin.
  2. Open Settings → Identity.
  3. Click Kind → pick OIDC or SAML 2.0.
  4. Paste the values you collected above.
  5. Click Save provider.

The Email-domain field is forgiving — if you paste a full email like hak@yourco.com we strip the local part and store yourco.com.

Test sign-in.

  1. Open an incognito browser tab.
  2. Go to /dashboard/login/.
  3. Enter your email — note the domain must match the provider's email domain exactly.
  4. You should be redirected to your IdP, sign in, and land on the dashboard.
What you'll see if it works. The dashboard sidebar shows your email at the bottom, and your tenant name in the topbar. If it doesn't work, the error parameter on the login URL tells you why (eg. ?error=sso_aud) — see the next section.

Troubleshooting.

If sign-in fails, the URL bar shows a stable error code. Common ones:

Everything else: email us with the error code and we'll dig in.