# Single sign-on

Connect a SAML 2.0 or OIDC identity provider to your workspace, verify your email domain over DNS and let your team sign in through it.

With single sign-on, your team signs in to Pozy through your identity provider (Okta, Microsoft Entra ID, Google Workspace, OneLogin, JumpCloud or any other SAML 2.0 or OIDC provider). Your provider's MFA and access policies apply on every sign-in, and people who sign in through it for the first time join your workspace automatically.

SSO is available on every workspace and is set up by the owner. The **Single sign-on (SSO)** panel is in **Settings → Security**.

## Rules that keep it safe

- **Only the workspace owner can set it up, change it or remove it.** It decides who can enter the whole workspace, so admins cannot touch it.
- **One connection links one email domain to one identity provider.** The domain must be the owner's own email domain. Public mailbox domains such as `gmail.com` or `outlook.com` are refused.
- **The domain must be verified over DNS** before the connection routes a single sign-in. That stops anyone from registering a provider for a domain they do not control.
- **New people join as `member`.** The owner role is never granted through SSO. Change roles afterwards on the Users page.

## Set it up

### Create an app in your identity provider

Create a SAML or OIDC app for Pozy. Most providers let you start with placeholder URLs and fix them once Pozy shows the final ones in step 3.

### Connect the provider in Pozy

In **Settings → Security → Single sign-on (SSO)**, enter your email domain (it must match your own email address) and the provider's details:

| Type | What to enter |
| --- | --- |
| SAML 2.0 | Paste the federation metadata XML of the app you created in your provider. Pozy reads the sign-on URL, entity id and signing certificate from it. If your provider cannot export metadata, enter the sign-on URL, IdP entity id (issuer) and signing certificate individually. |
| OIDC | The issuer URL, client ID and client secret of the app. Pozy uses the authorization code flow with PKCE. |

### Copy Pozy's URLs into your provider

Once the connection exists, the panel shows its provider id and the service-provider values to paste back into your provider's app:

| Value | Shape |
| --- | --- |
| SAML ACS URL | `https://pozy.ai/api/auth/sso/saml2/sp/acs/{providerId}` |
| SAML SP entity id | `https://pozy.ai/api/auth/sso/saml2/sp/metadata` |
| SAML SP metadata | `https://pozy.ai/api/auth/sso/saml2/sp/metadata?providerId={providerId}` |
| OIDC redirect URI | `https://pozy.ai/api/auth/sso/callback/{providerId}` |

Copy them from the panel rather than typing them.

### Verify the domain

The panel shows a TXT record. Add it at your DNS provider:

| Host | Value |
| --- | --- |
| `_pozy-sso-{providerId}.yourdomain.com` | The token the panel shows |

Then click **Check DNS record**. DNS changes usually show up within minutes, sometimes a few hours. Until the check passes, the panel says **Waiting for DNS** and the connection routes no sign-ins.

### Test it

Sign in through the provider yourself with your work email. Then ask one teammate to try before you announce it.

## What changes for your team

- People at your domain sign in with their work email and are sent to your identity provider.
- First-time users are added to the workspace as members.
- MFA and conditional access are your provider's job. Pozy's own [two-step verification](https://pozy.ai/docs/security/two-factor) protects password sign-in and is not needed for SSO users.
- API keys and the MCP server keep working as before. SSO controls dashboard sign-in, not API credentials.

## Remove a connection

The owner can remove the connection from the same panel. You type the domain to confirm. People at that domain go back to password and Google sign-in. There is no undo, so check with your team first.

## If it fails

| Message | Cause | Fix |
| --- | --- | --- |
| "We could not find the TXT record yet." | The record is missing, at the wrong host, or still propagating. | Publish the exact host and value from the panel, wait, then check again. |
| "That file has no IdP descriptor." | You pasted service-provider metadata, not your provider's. | Download the metadata of the app inside your identity provider. |
| "The metadata has no HTTP-Redirect or HTTP-POST sign-on URL." | The file is missing the sign-on URL. | Re-export it, or enter the details individually. |
| "The metadata contains no signing certificate." | The file is missing the certificate Pozy checks assertions with. | Re-export it, or paste the certificate individually. |
| "The domain must match your own email address." | The owner's email is at a different domain. | Set it up from an owner account at that domain. |
| "Only the workspace owner can set up single sign-on." | You are signed in as an admin. | Ask the owner. |

Need SSO on a plan that does not include it? Email support@pozy.ai.

## Related

- [SCIM provisioning](https://pozy.ai/docs/security/scim): not available yet; how to handle joiners and leavers today.
- [Roles](https://pozy.ai/docs/security/roles): what a member can do after their first SSO sign-in.