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.
- In Sign-in → Verified domains, click Add a domain and type your email domain, for example
acme.com. Public mailboxes likegmail.comare refused. - 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>
- Name (host):
- 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/callbackThe 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.
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. |