# Single sign-on

> Verify your email domain with DNS, connect your OpenID Connect identity provider, test it, and optionally require SSO.

Single sign-on (SSO) lets your users sign in to the app with your company's identity provider. Vato supports any **OpenID Connect** provider: Microsoft Entra ID, Google Workspace, Okta, Keycloak, Auth0 and others.

## 1. Verify your domain

SSO only creates or links an account when the email address belongs to a **verified domain** of your space. This is what stops anyone from claiming someone else's account.

1. In **Sign-in → Verified domains**, click **Add a domain** and type your email domain, for example `acme.com`. Public mailboxes like `gmail.com` are refused.
2. Click **Show the DNS record** and create this **TXT** record at your DNS host:
   - **Name (host)**: `_vato-verification.acme.com`
   - **Value**: `vato-verification=<the token shown in the console>`
3. Click **Verify**. DNS propagation can take from a few minutes to a few hours.

A verified domain covers its subdomains (`eu.acme.com`). A domain can only be verified by one space.

## 2. Register Vato with your provider

In your identity provider, create a **Web** application with the **authorization code** flow, and register this redirect URI exactly:

```
https://api.vatoide.com/api/enterprise-sso/callback
```

The console shows it under **Redirect URI to register with your provider**, with a copy button.

Request the `openid email profile` scopes. To use group rules, make the provider send the user's groups in a claim (for example `groups`).

## 3. Configure the provider in Vato

In **Sign-in → Identity provider (OIDC)**:

| Field | What to enter |
| --- | --- |
| **Issuer URL** | Your provider's OIDC address, without `/.well-known/…`. Examples: `https://login.microsoftonline.com/<tenant-id>/v2.0`, `https://accounts.google.com`, `https://<org>.okta.com`, `https://<host>/realms/<realm>`. |
| **Client ID** | The application ID from your provider. |
| **Client secret** | Encrypted when saved and never shown again. Leave empty to keep it. Optional for a public client using PKCE. |
| **Requested scopes** | Defaults to `openid email profile`. |
| **Email claim** | `email` by default. With Entra ID you can use `preferred_username` or `upn`. |
| **Name claim** | `name` by default. |
| **Groups claim** | For example `groups`, or `realm_access.roles` with Keycloak roles. Needed for group rules. |

Click **Save the provider**. Vato checks the configuration with your provider before saving.

## 4. Test the connection

Click **Test the connection**. You sign in at your provider and come back to the console. No account is created: the console shows the **Email received**, whether the provider verified it, the **Groups received**, and whether the address domain is verified for your space.

Then, in **Sign-in methods**, turn on **Company SSO (OIDC)**.

## How sign-in works for your users

- **Desktop app**: **Sign in** opens your space's sign-in page in the browser. After signing in at your provider, the page says you are connected, and the app receives its session.
- **Website**: the same SSO button signs them in on vatoide.com.
- On the first SSO sign-in, the account is created (rule **Create accounts on first sign-in**), and a seat is assigned (rule **Assign a seat automatically**). See [Members, rules and settings](members-rules-and-settings.md).

## Require SSO

The rule **Require SSO** blocks password, Google, Apple and magic-link sign-in for addresses in your verified domains: they must use your SSO. It can only be turned on after a successful test. **Owners keep a fallback access**, in case your provider is down.

## Security rules

- An address outside your verified domains is never created or linked by SSO. Such a person can still get a seat by **accepting an invitation** sent to their address.
- If your provider says an address is **not verified**, the sign-in is refused.
- If a Vato account already exists for an address of your domain but never proved its email, its password and sessions are removed when it is linked to your SSO.
- An SSO sign-in must finish in the browser that started it.

## If sign-in fails

The result page explains the problem and shows an error code. The most common ones:

| Code | Meaning |
| --- | --- |
| `email_domain_not_verified` | The address is not in a verified domain of the space. |
| `email_not_verified` | Your provider says the address is not verified. |
| `email_in_use` | A Vato account already exists for this address, outside your verified domains: send an invitation instead. |
| `seat_limit_reached` | All seats are in use. |
| `pending` | The space is not activated yet. |
| `state_expired`, `state_mismatch` | The sign-in took too long or was finished in another browser: start again. |
| `discovery_failed`, `issuer_mismatch` | The issuer URL is wrong. |

## Related pages

- [Branding and sign-in](branding-and-sign-in.md)
- [Members, rules and settings](members-rules-and-settings.md)

Source: https://vatoide.com/docs/enterprise/single-sign-on