# Configure SSO

> Connect Developer Console access to an OpenID Connect (OIDC) identity provider; single sign-on is required, with no password login.

Access to the Developer 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](#part-1-agent-router-configuration)**: form expectations, verification, and troubleshooting.
- **Part 2: [Identity provider configuration](#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](#microsoft-entra-id)
  - [Google Workspace](#google-workspace)
  - [Auth0](#auth0)
  - [Generic/other OIDC](#other-oidc-providers-okta-keycloak-ping-custom)

## 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.
1. **Identity provider**: register an OIDC client using that Redirect URI. The output is an **Issuer**, **Client ID**, and **Client Secret**.
1. **Tetrate form**: paste the three values and submit.
1. **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:

```text
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](#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:

```text
<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.

:::tip
You should **always** add at least one (1) admin email account.
:::

#### 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](#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](#microsoft-entra-id)
- [Google Workspace](#google-workspace)
- [Auth0](#auth0)
- [Other OIDC providers](#other-oidc-providers-okta-keycloak-ping-custom)

### 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](#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:

```text
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:

```text
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](#part-1-agent-router-configuration) and paste them into the Configure SSO form.

### Auth0

:::tip Evaluation walkthrough
For a ground-up Auth0 path (new tenant through credentials ready for onboarding), see [Set up Auth0 for evaluation](/product-architecture/product-evaluation/auth0-for-evaluation).
:::

#### 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**
- Select **Applications**
- Click **+ Create Application**. 
- Select **Create Manually**.
- Enter a sensible, recognizable name, such as `Tetrate Agent Router Enterprise`
- Select **Regular Web Application**.
- Click **Create**.

#### Step 2: configure application details
- In the next panel, select tab "Settings"
- Navigate to **Basic Information**.
- Copy the values for `Domain`, `Client ID` and `Client Secret` to a text editor or note taking app of choice.
- Scroll to section **Application Properties**
- Set **Application Logo** to URL `https://router.internal.tetrate.ai/favicon.svg`
- Scroll to section **Application URIs**
- Set **Allowed Callback URLs** to the Tetrate Redirect URI: `https://auth.<tenant>.tetrate.ai/api/auth/sso/callback/corporate`
- Set **Allowed Web Origins** to the Tetrate hostnames for the tenant:

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

#### Step 3: set the logout URL (optional)
- Navigate to section **Application URIs**.
- Set **Allowed Logout URLs** to:

```text
https://auth.<tenant>.tetrate.ai
```
- Click button **Save**.

#### Step 5: save credentials (if you have not done so already)

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](#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`:

```bash
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

  <Link to="/agent-router-service/quickstarts/quickstart-console" className="tare-nav-card">
    Console quickstart
    Issue an API key and confirm a first routed request once SSO is working and the gateway is reachable.
  </Link>
  <Link to="/agent-router-enterprise/quickstarts/quickstart-admin-dashboard" className="tare-nav-card">
    Admin Dashboard quickstart
    Review models, providers, users, and usage analytics from the management plane.
  </Link>
  <Link to="/agent-router-enterprise/guides/identity-and-access-management/sso-role-mapping-guide" className="tare-nav-card">
    SSO role mapping (optional)
    After base SSO is verified, map OIDC roles and groups to Agent Router roles.
  </Link>
  <Link to="/agent-router-enterprise/self-hosted-data-plane" className="tare-nav-card">
    Self-hosted path
    If you deferred SSO during onboarding, this is the next step before developer handoff. See the full self-hosted sequence.
  </Link>