Single sign-on

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 event and recorded in the audit log.