# Single sign-on

Let your team sign in to the dashboard through your own identity provider, and — when you are ready — require it. OpenID Connect, one connection per team, set up from Settings → Security.

## Before you start

- Single sign-on is an add-on on the Scale plan and above, and included on Enterprise.
- Your provider must speak **OpenID Connect**. Okta, Microsoft Entra ID and Google Workspace all do; SAML is not supported.
- You need to be able to add a TXT record to each email domain you want to cover.

## Set it up, step by step

### 1. Add the add-on

From Settings → Usage, on Scale or above. On Enterprise it is already there and nothing is added to your invoice.

### 2. Create an app in your identity provider

A web application using the authorization code flow, with the scopes `openid`, `email` and `profile`. Give it the redirect URI shown under Settings → Security → Single sign-on — `/auth/sso/callback` on your dashboard's origin — and copy the issuer URL, client ID and client secret it gives you.

- **Microsoft Entra ID:** use your tenant's own issuer. The shared `/common`, `/organizations` and `/consumers` issuers are refused, because any tenant in the world can sign a token for them.
- **Google Workspace:** the token's `hd` claim must be one of your verified domains, so a personal Google account is never let in.

### 3. Create the connection

In Settings → Security → Single sign-on: a display name, the issuer, the client ID and the client secret. The secret is write-only — it is encrypted at rest and never shown again.** Test connection** fetches your provider's discovery document and reports the endpoints it found, or exactly why it could not.

> Every address the connection contacts must be `https` on port 443 and on the platform's allowlist of identity-provider hosts. A test that reports the host is not on the allowlist is not something you can fix from the dashboard — ask us.

### 4. Prove each email domain

Add the domains your people sign in with. Each one is proved by a TXT record with the token the dashboard shows you:

The SSO domain verification record:

```text
_rasket-sso.acme.example.  TXT  "rasket-sso-verification=<token>"
```

A domain can belong to one team across the whole platform. Verification is checked when you ask and again every week.

### 5. Activate

Activation needs the add-on. From then on, anyone with an address on a verified domain can choose **Continue with SSO** on the login page, or open your team's sign-in URL — `/auth/sso/<connection id>` on the dashboard's origin, shown beside the redirect URI — and land in your team.

### 6. Enforce, if you want to

Enforcement means a member reaches the team only from a session your provider signed in. It can be turned on once the connection is active and a domain is verified, and only by an admin who is either signed in through it or exempt.

Turning it on from a password session makes you exempt in the same step, so nobody locks themselves out.

## Who gets in

A successful sign-in is matched to a person in this order:

- Someone who has signed in through this connection before is that person.
- Otherwise, an existing account with the same address is linked, and marked verified.
- Otherwise, an account is created on the spot — no password, no verification email — and added to your team. That is just-in-time provisioning.

Someone new to the team joins as an admin, unless a pending invitation to their address names another role — then they get that role. Someone already on the team keeps the role they have. An address outside your verified domains is refused even if your provider vouches for it: the DNS record, not the provider's `email_verified` flag, is the proof that you control those mailboxes. Two-factor authentication is not asked for on an SSO sign-in, because your provider is the second factor.

## What enforcement does not touch

API keys and OAuth tokens are credentials of the team, not of a person, and keep working exactly as before. Enforcement is about who can open the dashboard.

- Approving an [OAuth](https://www.rasket.com/docs/oauth) app for an enforced team needs an SSO session or an exemption, as the dashboard does.
- An invitation to an enforced team can be accepted only after signing in through it.

## Break-glass

An admin can mark any member **SSO exempt** from Settings → Team → Members, so the team is still reachable on the day your provider is down. Exemption requires that member to have two-factor authentication turned on, and every exempt sign-in to an enforced team is written to the audit log.

## Turning it off

Disabling the connection clears enforcement **first**, then stops SSO sign-in, so nobody is locked out in between. The same happens if the add-on is removed or the plan drops below Scale. Sessions already open run to their normal expiry.

## When a sign-in fails

The login page shows one of five codes. Your provider's own message is never repeated there.

| Code | Means |
| --- | --- |
| `sso_state` | The sign-in expired or its state did not match. Start again from the login page. |
| `sso_exchange` | Your provider could not be reached or refused the code — often a wrong client secret or redirect URI. |
| `sso_token` | The ID token did not verify, or carried no usable email address. |
| `sso_domain` | The address is not on one of the connection's verified domains. |
| `sso_disabled` | The connection is not active. |