> ## Documentation Index
> Fetch the complete documentation index at: https://docs.proofage.net/llms.txt
> Use this file to discover all available pages before exploring further.

# SAML single sign-on

> Connect your identity provider to the ProofAge console with SAML 2.0: verify your domains, set up the connection, test it, require it, and keep a way in.

With SAML single sign-on, the people in your organization sign in to the ProofAge console through your identity provider, such as Okta, Microsoft Entra ID or Google Workspace. It is included on every plan.

Only **administrators** set it up, under **Settings → SSO**. Developers and support specialists do not see these settings. Step-by-step guides: [Okta](https://docs.proofage.net/console/saml-okta.md) and [Microsoft Entra ID](https://docs.proofage.net/console/saml-entra.md).

## Before you start

* Each organization has **one** SAML connection.
* The identity provider must sign the SAML response, the assertion, or both. An unsigned response is refused.
* Sign-in starts at ProofAge (SP-initiated). A response your identity provider sends on its own (IdP-initiated sign-in) arrives without a request from ProofAge and is refused. A tile in your identity provider's app dashboard works only if it opens ProofAge's [**Sign-in URL**](#the-sign-in-url-for-dashboard-tiles).
* ProofAge does not provision users through SCIM and does not support Single Logout. Someone you remove in your identity provider can no longer sign in through it, but keeps a console session that is already open until it ends or is revoked, and keeps any other way in their account has (a password, a passkey, Google or Microsoft). Remove them from **Team** too. With **Create accounts on first sign-in** on, removing someone from **Team** alone is not enough: while they are still assigned to the app in your identity provider and their email is on a verified domain, their next single sign-on adds them back with the role for new members. Remove them in both places.

## 1. Verify your email domains

Under **Settings → SSO**, add the domain of your work email addresses, such as `acme.com`, and publish the TXT record the console shows at your DNS provider:

```text theme={null}
TXT  _proofage-challenge.acme.com  "proofage-domain-verification=<token>"
```

Then choose **Check now**. DNS changes can take a while to appear; ProofAge looks only when you ask.

* Matching is exact: `eu.acme.com` is a domain of its own and needs its own record.
* Public mail domains such as `gmail.com` or `outlook.com` cannot be verified.
* A domain can be verified by one organization only. If another organization has verified yours, contact support.
* Up to **10** domains per organization.

Verified domains decide who single sign-on applies to: signing in with only a work email, creating accounts on first sign-in, and **Require single sign-on** all apply to people whose email is on a verified domain. Without a verified domain, members can still link single sign-on to their own account from their profile.

## 2. Create the connection

Choose **Set up single sign-on**. Nothing changes for your team until you enable it. The console shows four values to give your identity provider:

| In the console | What it is | Example |
| - | - | - |
| **Entity ID** | ProofAge's SP entity ID (the audience) | `https://app.proofage.net/sso/saml/<connection id>/metadata` |
| **ACS URL** | Where your identity provider posts the response (reply URL, single sign-on URL) | `https://app.proofage.net/sso/saml/<connection id>/acs` |
| **Metadata URL** | ProofAge's SP metadata, for identity providers that import it | the same address as the entity ID |
| **Sign-in URL** | Where a dashboard tile sends people, so sign-in starts at ProofAge ([below](#the-sign-in-url-for-dashboard-tiles)) | `https://app.proofage.net/sso/saml/<connection id>/login` |

Copy them from the console; the connection ID is yours.

### The sign-in URL for dashboard tiles

To let people start from a tile in your identity provider's dashboard (Okta, Microsoft My Apps), point the tile at the **Sign-in URL** shown under **Settings → SSO**. Opening it starts a normal ProofAge sign-in and sends the person to your identity provider, which signs them straight in when they already have a session there. It works once the connection is enabled (step 6); before that, the sign-in page says "Single sign-on is not available for this organization."

## 3. Configure your identity provider

Create a SAML 2.0 application with the entity ID and ACS URL above, and set:

* **Name ID**: a value that never changes for a person, in the **persistent** or **email address** format. A **transient** Name ID is refused: it differs at every sign-in, so ProofAge could never recognize the person again. ProofAge recognizes a person by the connection and the Name ID, never by the email address alone.
* **Email**: an attribute named `email`, `mail`, `emailaddress` or `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`. If none is sent, ProofAge uses the Name ID when its format is email address. A response without an email address is refused.
* **Name** (optional, used for new accounts): `name`, `displayname` or `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`, or a first and last name as `givenname` and `surname` (or `sn`).

Then assign the application to the people who should use it.

## 4. Tell ProofAge about your identity provider

Under **2. Tell us about your identity provider**, choose one way:

* **Metadata URL**: the `https` address of your identity provider's metadata. ProofAge fetches it once, when you save.
* **Paste metadata XML**.
* **Enter manually**: the identity provider's entity ID, its sign-in URL (`https` only) and its signing certificate (PEM).

Choose **Save identity provider**. The console then shows your identity provider's entity ID, its sign-in URL and each certificate's SHA-256 fingerprint and expiry date. Metadata with two signing certificates keeps both, so a certificate rotation at your identity provider does not interrupt sign-in; metadata with more than two is refused. The metadata URL must answer directly, without a redirect. When the certificate changes, save the metadata again. ProofAge does not warn you before a certificate expires: once it has expired, or your identity provider signs with a certificate ProofAge does not have, every sign-in is refused as "The identity provider's response could not be verified".

Changing, enabling, disabling or deleting the connection asks you to confirm it is you.

## 5. Accounts for new people (optional)

**Create accounts on first sign-in** lets someone on one of your verified domains sign in through your identity provider for the first time and join your organization:

* a person with no ProofAge account gets one, without a password;
* a person who already has a ProofAge account but is not in your organization joins it.

Choose their **Role for new members**: **Support specialist** (the default) or **Developer**. New members never become administrators this way; promote them under **Team** if needed.

With it off, only people who are already members of your organization can sign in through single sign-on, and anyone else is asked to get an invitation.

## 6. Enable and test

1. Choose **Enable single sign-on**. It is available once the identity provider is saved.
2. Test it with your own account: in **Profile → Security → Sign-in methods**, choose **Link single sign-on for** your organization and sign in at your identity provider. Or, if your email is on a verified domain, sign out and use **Sign in with SSO** on the sign-in page.
3. The **Settings → SSO** page then says "You have signed in through this connection."

If something fails, the sign-in page shows why. When ProofAge received a response for a sign-in it started (a signature, email, Name ID or membership problem), the **Audit log** also records the refusal as *Single sign-on refused* with its reason; an expired or IdP-initiated sign-in, a disabled connection and an email domain without single sign-on are not logged. See [When a sign-in is refused](#when-a-sign-in-is-refused).

## 7. Require single sign-on (optional)

Under **Settings → Security**, **Require single sign-on** makes members whose email is on one of your verified domains sign in through your identity provider to work in your organization. Members on other addresses, such as contractors on `gmail.com`, are not affected.

ProofAge refuses to turn it on until:

* the connection is enabled;
* at least one domain is verified;
* you have signed in through the connection yourself (step 6), so you cannot lock yourself out.

A member it applies to who opens the console in another way sees "Sign in with single sign-on to continue in" your organization, with **Continue with single sign-on**. Their account itself is unchanged, and their other organizations in ProofAge are not affected.

The [MCP server](https://docs.proofage.net/integration/mcp/overview.md) and apps connected to ProofAge (such as Zapier) refuse a member it applies to until that member has linked single sign-on to their account.

### Break-glass for administrators

**Break-glass for administrators** is on by default. While it is on, an administrator who signs in another way **and** proves a second factor (password with an authenticator code, a passkey, or Google or Microsoft with an authenticator code) can still open the organization, so an outage at your identity provider cannot lock you out. Turn it off only if you accept that risk.

## How your team signs in

On the sign-in page, **Sign in with SSO** asks for a work email and sends the person to your identity provider. It works for addresses on a verified domain of an organization whose connection is enabled; otherwise the page says "Single sign-on isn't set up for this email domain."

The first time someone signs in through single sign-on, ProofAge finds their account like this:

1. **They have signed in through this connection before** (same Name ID): that account.
2. **Their email is on a verified domain**:
   * a member of your organization whose email address was verified is linked and signed in, and receives an email that single sign-on was added to their account;
   * an account that is not a member joins your organization if **Create accounts on first sign-in** is on, and is refused otherwise;
   * no account: created if **Create accounts on first sign-in** is on, refused otherwise.
3. **Their email is not on a verified domain**: refused. A member links single sign-on from **Profile → Security** while signed in another way.

A session opened through single sign-on:

* does not ask for an authenticator code, and counts as signing in with two factors for [Require two-factor authentication](https://docs.proofage.net/console/security-policies.md#require-two-factor-authentication);
* works in your organization only. To open another organization they belong to, the person signs out and back in with their own account;
* asks for the person's own password, passkey or provider before they add an authenticator app or a passkey or change their sign-in methods. An account created by single sign-on has none of these until the person sets a password with **Forgot password?** on the sign-in page;
* does not show the person's sessions, devices or security activity, and cannot approve the MCP server or a connected app.

## Turning it off

* **Disable** stops single sign-on at once and turns **Require single sign-on** off.
* **Delete connection** also removes everyone's linked single sign-on and turns **Require single sign-on** off. Nobody loses their password or passkeys.
* The last verified domain cannot be removed while **Require single sign-on** is on.

Every change to the connection, the domains and the policy is recorded in the [audit log](https://docs.proofage.net/console/security-policies.md#audit-log).

## When a sign-in is refused

| The sign-in page says | What to check |
| - | - |
| "Your identity provider did not send an email address." | Release an email attribute (step 3). |
| "Your identity provider sent a one-time identifier instead of a permanent one." | Set the Name ID format to persistent or email address. |
| "The identity provider's response could not be verified." | The entity ID, ACS URL and signing certificate on both sides (an expired or replaced certificate: save your identity provider's metadata again); that the response or the assertion is signed; the clocks of your identity provider. |
| "This sign-in request expired or was already used. Please start again." | Start at ProofAge (**Sign in with SSO**) or from a tile that opens ProofAge's [**Sign-in URL**](#the-sign-in-url-for-dashboard-tiles), not from a tile that sends an IdP-initiated response, and finish within 10 minutes. |
| "This sign-in was started in another browser session." | Finish the sign-in in the browser that started it. |
| "Your organization has not verified your email domain…" | Verify the domain (step 1), or have the person link single sign-on from their profile. |
| "Your account is not a member of this organization." / "No account exists for this address…" | Invite the person, or turn on **Create accounts on first sign-in**. |
| "Sign in with your password, then link … from Profile > Sign-in methods, or reset your password to confirm this email." | The person's ProofAge account has an email address that was never verified. A password reset verifies it. |
| "Single sign-on is not available for this organization." | The connection is disabled. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.