# Single sign-on

> Let your team sign in to ACOG through your identity provider over OIDC or SAML, with roles mapped from groups and sign-in routed by email domain.

Product: AI Cost Optimizer Gateway (ACOG). Web version: https://tessarac.com/docs/acog/administer/single-sign-on. Last updated: 2026-10-16.

Connect your identity provider (Okta, Microsoft Entra ID, Ping, Keycloak, Auth0, ADFS and others) so your team signs in with it. People are added to your organization on their first sign-in, with a role mapped from their identity-provider groups.

Open **Admin → Single sign-on**. You need the **Configure single sign-on (OIDC / SAML) identity providers** permission (`admin:sso`).

## 1. Register ACOG with your identity provider

Choose **Add connection** and pick OIDC or SAML. The **Register with your IdP** panel shows the values to give your identity provider, with copy buttons:

| Protocol | Value |
|---|---|
| OIDC | Redirect URI: `https://acog.tessarac.com/api/v1/auth/sso/{connection id}/callback` |
| SAML | Assertion Consumer Service URL: `https://acog.tessarac.com/api/v1/auth/sso/{connection id}/acs` |
| SAML | Service provider metadata: `https://acog.tessarac.com/api/v1/auth/sso/{connection id}/metadata` |

On a self-hosted installation the host is your installation's.

## 2. Configure the connection

**OIDC**

| Field | Notes |
|---|---|
| Issuer URL | Your identity provider's issuer. On the hosted service it must be a public HTTPS address. |
| Client ID and client secret | From the application you registered. The secret is stored encrypted; leave it blank later to keep it. |
| Scopes | Default `openid email profile groups`. Must include the email and groups scopes. |
| Email claim, groups claim | Which claims carry the email address and groups |

**SAML**

| Field | Notes |
|---|---|
| IdP metadata XML | Paste your identity provider's metadata |
| Email attribute, groups attribute | Which attributes carry the email address and groups |

The protocol cannot be changed after the connection is created.

## 3. Map groups to roles

| Setting | Effect |
|---|---|
| **Group → role mapping** | Map an identity-provider group to an ACOG role. The first matching group wins. |
| **Default role** | The role for someone whose groups match no mapping |
| **Email domain allow-list** | Optional. When set, only people with an email address at these domains are added. |


## 4. Route sign-in by email domain

People sign in at the same address as everyone else. To send everyone with an email at your domain to your identity provider automatically, claim the domain under **Email domain routing**: add the DNS TXT record shown (`acog-site-verification=<token>`) to your domain, then choose **Check DNS**. Until the record is verified, the domain routes no sign-ins.

## Recovery

Existing members keep their accounts if you delete a connection, but need another way to sign in. On a self-hosted installation, password sign-in remains available for break-glass recovery if your identity provider is unreachable.

Changes to SSO connections are delivered as the `security.sso_connection_changed` [webhook](https://tessarac.com/docs/acog/administer/webhooks.md) event and recorded in the [audit log](https://tessarac.com/docs/acog/govern/activity-and-audit-log.md).