Configuring SSO

Access to the Agent Router console runs exclusively through single sign-on (SSO) using an existing OpenID Connect (OIDC) identity provider. Email and password sign-in is not supported.

---

Overview

Agent Router exposes two web interfaces; both authenticate through the same SSO configuration:

• Administrator Dashboard (dashboard.<tenant>.tetrate.ai) for admins.
• Router (router.<tenant>.tetrate.ai) for developers.

This guide covers SSO configuration against an existing identity provider. The work falls into two parts:

• Part 1: Agent Router configuration: form expectations, verification, and troubleshooting.
• Part 2: Identity provider configuration: how to register an OIDC client in the identity provider and collect the values needed by the form. Walkthroughs are available for:
  • Microsoft Entra ID
  • Google Workspace
  • Auth0
  • Generic/other OIDC

Process at a glance

1. Tetrate onboarding wizard: open the Configure SSO step and click IdP setup guide to reveal the Redirect URI. Copy it.
2. Identity provider: register an OIDC client using that Redirect URI. The output is an Issuer, Client ID, and Client Secret.
3. Tetrate form: paste the three values and submit.
4. Verify: sign in on the Dashboard or Router sign-in page.

Open the Configure SSO step in the onboarding wizard first. The Redirect URI shown there is tenant-specific, and the IdP side cannot proceed without it.

Part 1: Agent Router configuration

Step 1: obtain the redirect uri

In the Configure SSO step, click the IdP setup guide button at the top of the form. A panel opens, titled "Configure your SSO provider", with step-by-step instructions and the Redirect URI for the tenant. The format is:

https://auth.<tenant>.tetrate.ai/api/auth/sso/callback/corporate

Use the copy icon to copy the URL.

• The hostname is tenant-specific.
• The trailing path is the same for every customer.
• Most IdPs require the URL to match character-for-character. Any mismatch (scheme, trailing slash, missing path segment) produces a redirect_uri_mismatch error at sign-in.

tip

Always copy the URL from the IdP setup guide panel. Don't type it from memory or copy it from this document.

Step 2: register an OIDC client in your IdP

Use the Redirect URI from Step 1 to register an OIDC client in the identity provider. Walkthroughs for each supported IdP are in Part 2: Identity provider configuration. The output is an Issuer, Client ID, and Client Secret.

Step 3: fill in the configure SSO form

The Configure SSO step collects the values below.

Issuer (identity provider URL)

The base URL of the OIDC provider. Agent Router uses it to discover other endpoints (authorization, token, userinfo, JWKS) and to validate the iss claim in incoming ID tokens.

Common values:

IdP	Issuer format
Entra ID	https://login.microsoftonline.com/<TENANT_ID>
Google	https://accounts.google.com
Auth0	https://<DOMAIN>/
Okta	https://<tenant>.okta.com or https://<tenant>.okta.com/oauth2/default
Keycloak	https://<keycloak-host>/realms/<realm>

The Issuer must match the iss claim the IdP puts in ID tokens exactly. Sign-in failures with no obvious cause usually trace back to an Issuer typo: trailing slash, missing tenant ID, wrong region.

Client ID

The OIDC client ID issued by the IdP.

Client secret

The confidential credential paired with the Client ID. This value is shown only once at creation. Copy it into the form immediately, or store it in a secrets manager.

Discovery URL

The full URL to the IdP's OpenID Connect metadata document:

<Issuer>/.well-known/openid-configuration

note

Agent Router validates the URL on submit by fetching it and confirming the JSON includes issuer, authorization_endpoint, and token_endpoint. If those are missing or the URL is unreachable, the form returns Invalid OIDC discovery URL.

Scopes

Use openid, profile, email.

Admin emails

Email addresses granted Tetrate admin permissions on first SSO login. This is the critical bootstrap mechanism. Without Admin Emails set, the initial SSO sign-in lands in a standard user account without administrative privileges. Agent Router has no email/password fallback, so failure here causes a permanent lockout from administrative functions.

warning

If lockout occurs, contact Tetrate Support to reset the SSO configuration.

Add the email addresses of the people who should be admins from day one.

Attribute mapping

Maps the Tetrate email user attribute to the matching claim name in the IdP's ID token. The default is email → email, which works for Google, Auth0, Okta, and Keycloak as registered in this guide. Entra requires an optional claim to be added before it emits email; see the Microsoft Entra ID section.

Step 4: submit the form

Click Configure. Agent Router validates the discovery URL synchronously. A successful response means:

• The discovery document was reachable from Agent Router's auth pod.
• It contained the required OIDC metadata fields.

It does not mean the Client ID or Client Secret are correct. Those are exercised on the first sign-in attempt.

Step 5: verify

After the form accepts the config, sign in via the Dashboard or Router sign-in page. Both delegate to the IdP. A successful flow lands back in Agent Router signed in as the IdP user.

If the bounce-back lands at an error page instead of Agent Router, check the URL. Most IdPs include an error query parameter (redirect_uri_mismatch, invalid_client, consent_required) that pinpoints the cause.

If sign-in succeeds but the dashboard shows an account with an empty email or no admin permissions, see the troubleshooting table below.

Troubleshooting and common errors

Symptom	Cause	Fix
Invalid OIDC discovery URL on form submit	Issuer typo, IdP unreachable from the auth pod, or IdP returns 404 / non-JSON at /.well-known/openid-configuration	Verify the discovery URL is reachable: curl <issuer-url>/.well-known/openid-configuration | jq -r '.issuer, .authorization_endpoint, .token_endpoint'
Signed in but Tetrate shows empty email	ID token has no email claim, or claim name is non-standard	Update Attribute Mapping to point to the right claim, or add email as an emitted claim in the IdP
Signed in but no admin permission	Email wasn't in Admin Emails at the time of first SSO sign-in	Contact Tetrate Support to reset SSO and re-run with Admin Emails populated

For IdP-side errors (redirect_uri_mismatch, invalid_client, callback mismatch), see the IdP's documentation.

Editing SSO config after onboarding

The same fields are editable from the Settings page in the dashboard sidebar (SSO tab) after onboarding completes. The form is identical; only the route differs. SSO cannot be turned off, but the values can be swapped to point at a different IdP.

To rotate the Client Secret without downtime, create a new secret in the IdP, update Client Secret in Tetrate, verify sign-in works, then delete the old secret in the IdP.

Mfa and multi-IdP

• MFA: Multi-factor authentication is whatever the IdP enforces. Agent Router delegates the entire login screen to the IdP, so MFA prompts, conditional access, and device checks all happen there.
• Multiple IdPs: Agent Router wires one IdP at a time. To switch, edit the config in Settings → SSO.

---

Part 2: identity provider configuration

This section covers how to register an OIDC client in each supported identity provider.

Table of contents

• Microsoft Entra ID
• Google Workspace
• Auth0
• Other OIDC providers

Microsoft Entra ID

What it produces

Value	Where it comes from
Issuer	App registration → Overview → Endpoints → Authority URL
Discovery URL	App registration → Overview → Endpoints → OpenID Connect metadata document
Client ID	App registration → Overview → Application (client) ID
Client Secret	App registration → Certificates & secrets → New client secret

One value is registered in Entra: the Redirect URI for the Tetrate tenant.

Prerequisites

• Access to the Microsoft Entra ID instance.
• The Tetrate Redirect URI. Open the IdP setup guide panel in the Configure SSO step to find it.

Step 1: create an app registration

In the Entra admin center, go to App registrations and click + New registration. Fill in the name and complete the form.

Step 2: add the redirect uri

In the app registration, click Authentication in the left sidebar.

• Click + Add a platform, then choose Web.
• Paste the Redirect URI from the Tetrate onboarding form.
• Click Configure.

Step 3: add optional claims

In the app registration, click Token configuration in the left sidebar, then + Add optional claim.

Field	Value
Token type	ID
Claims	Tick email

Click Add.

Step 4: generate a client secret

In the app registration, click Certificates & secrets in the left sidebar, then + New client secret.

• Add a description, choose an expiry, and click Add.
• Copy the Value column immediately and store it in a secrets manager. Once the page closes, Entra does not reveal it again.

Step 5: collect the issuer URL and client ID

In the app registration Overview:

• Click Endpoints in the top toolbar. A drawer opens with several URLs.
• Copy the Authority URL (use as the Tetrate Issuer).
• Copy the OpenID Connect metadata document URL (use as the Tetrate Discovery URL).
• Copy Application (client) ID (use as the Tetrate Client ID).

Done in Entra

The collected values are:

• Issuer, the Authority URL.
• Discovery URL, the OpenID Connect metadata document URL.
• Client ID.
• Client Secret.

Return to Part 1: Agent Router configuration and paste them into the Configure SSO form.

Google workspace

What it produces

Value	Where it comes from
Issuer	https://accounts.google.com (fixed)
Discovery URL	https://accounts.google.com/.well-known/openid-configuration (fixed)
Client ID	APIs & Services → Credentials → OAuth client ID
Client Secret	APIs & Services → Credentials → OAuth client ID

Two values are registered in Google: the Authorized redirect URI and the Authorized JavaScript Origins for the Tetrate tenant.

Prerequisites

• A Google Cloud project.
• IAM permission on the project to manage OAuth credentials.
• The Tetrate Redirect URI. Open the IdP setup guide panel in the Configure SSO step to find it.

Step 1: create OAuth credentials

Go to Google Cloud Console → APIs & Services → Credentials and click Create Credentials → OAuth client ID.

Step 2: configure the consent screen

Add:

• App name.
• Support email.
• Scopes: openid, profile, email.

Step 3: set the redirect uri

Set the Authorized redirect URI to the Tetrate Redirect URI:

https://auth.<tenant>.tetrate.ai/api/auth/sso/callback/corporate

Step 4: set authorized JavaScript origins

Set Authorized JavaScript Origins to the three Tetrate hostnames for the tenant:

https://auth.<tenant>.tetrate.ai
https://dashboard.<tenant>.tetrate.ai
https://router.<tenant>.tetrate.ai

Step 5: save credentials

Copy:

• Client ID.
• Client Secret.

Done in Google

The collected values are:

• Issuer: https://accounts.google.com.
• Discovery URL: https://accounts.google.com/.well-known/openid-configuration.
• Client ID.
• Client Secret.

Return to Part 1: Agent Router configuration and paste them into the Configure SSO form.

Auth0

What it produces

Value	Where it comes from
Issuer	Build from the Auth0 Domain: https://<DOMAIN>/ (trailing slash)
Discovery URL	Build from the Auth0 Domain: https://<DOMAIN>/.well-known/openid-configuration
Client ID	Applications → app → Settings
Client Secret	Applications → app → Settings

Three values are registered in Auth0: the Callback URL, Allowed Web Origins, and (optionally) the Logout URL for the Tetrate tenant.

Prerequisites

• An Auth0 tenant.
• A role that allows creating applications and viewing secrets.
• The Tetrate Redirect URI. Open the IdP setup guide panel in the Configure SSO step to find it.

Step 1: create the application

Go to the Auth0 Dashboard → Applications and click Create Application. Select Regular Web Application.

Step 2: set the callback URL

Set the Allowed Callback URLs to the Tetrate Redirect URI:

https://auth.<tenant>.tetrate.ai/api/auth/sso/callback/corporate

Step 3: set allowed web origins

Set Allowed Web Origins to the Tetrate hostnames for the tenant:

https://auth.<tenant>.tetrate.ai
https://dashboard.<tenant>.tetrate.ai
https://router.<tenant>.tetrate.ai

Step 4: set the logout URL (optional)

Set Allowed Logout URLs to:

https://auth.<tenant>.tetrate.ai

Step 5: save credentials

From the application Settings tab, copy:

• Domain: build the Issuer as https://<Domain>/ (with trailing slash). For example, acme.us.auth0.com becomes https://acme.us.auth0.com/.
• Client ID.
• Client Secret.

Done in Auth0

The collected values are:

• Issuer: https://<DOMAIN>/ (trailing slash).
• Discovery URL: https://<DOMAIN>/.well-known/openid-configuration.
• Client ID.
• Client Secret.

Return to Part 1: Agent Router configuration and paste them into the Configure SSO form.

Other OIDC providers (Okta, Keycloak, ping, custom)

The flow matches the supported IdPs above; only the IdP UI changes. From the IdP, register a Web application, set the Redirect URI to the value Agent Router's form supplies, enable the openid, profile, email scopes, generate a client secret, and collect Issuer, Client ID, and Client Secret.

For the Issuer, find the IdP's OIDC discovery URL and check that it returns valid JSON with issuer, authorization_endpoint, and token_endpoint:

curl -s "<Issuer>/.well-known/openid-configuration" \
 | jq '.issuer, .authorization_endpoint, .token_endpoint'

The value .issuer returns is what goes into Tetrate's Issuer field. Even small differences (trailing slash, version path) break sign-in.

---

Where to go next

SSO role mapping

Map OIDC roles and groups to Agent Router roles so directory changes propagate on login.

Data plane installation

Bring up the data plane on AWS, Azure, or GCP once SSO is configured.