> ## 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.

# Set up SAML with Okta

> Connect Okta to the ProofAge console with SAML 2.0, step by step: the Okta app integration, attributes, the metadata URL and a first test sign-in.

This guide connects an Okta organization to ProofAge. Read [SAML single sign-on](https://docs.proofage.net/console/saml-sso.md) first for what each setting does. You need an administrator account in ProofAge and an Okta administrator who can create app integrations.

**1. Verify your email domain in ProofAge**

In the ProofAge console, open **Settings → SSO**, add your email domain (for example `acme.com`), publish the TXT record shown at your DNS provider and choose **Check now**. See [Verify your email domains](https://docs.proofage.net/console/saml-sso.md#1-verify-your-email-domains).

**2. Create the ProofAge connection**

Still under **Settings → SSO**, choose **Set up single sign-on**. Keep the page open: you need its **Entity ID**, **ACS URL** and **Sign-in URL**.

**3. Create the app integration in Okta**

In the Okta Admin Console, go to **Applications → Applications → Create App Integration**, choose **SAML 2.0** and continue.

Name it `ProofAge`. Under **App visibility**, tick **Do not display application icon to users**: this app's own tile would send an IdP-initiated response, which ProofAge refuses. To give people a tile, add a bookmark app in the last step.

**4. Configure SAML**

| Okta field | Value |
| - | - |
| **Single sign-on URL** | ProofAge's **ACS URL**. Keep **Use this for Recipient URL and Destination URL** ticked. |
| **Audience URI (SP Entity ID)** | ProofAge's **Entity ID** |
| **Name ID format** | `EmailAddress` (or `Persistent`; never `Transient`) |
| **Application username** | `Email` |

Under **Attribute Statements**, add:

| Name | Value |
| - | - |
| `email` | `user.email` |
| `givenname` | `user.firstName` |
| `surname` | `user.lastName` |

`email` is recommended, and required if the Name ID format is `Persistent`. The two name attributes give accounts created on first sign-in a proper name. Leave the signature settings at Okta's defaults (signed). Finish the wizard.

**5. Give ProofAge Okta's metadata**

On the app's **Sign On** tab, copy the **Metadata URL**. In ProofAge, under **2. Tell us about your identity provider**, choose **Metadata URL**, paste it and choose **Save identity provider**. The console then shows Okta's entity ID, Okta's own sign-in URL and the certificate fingerprint.

**6. Assign people**

On the app's **Assignments** tab, assign the people or groups who use ProofAge, including yourself.

**7. Enable and test**

In ProofAge, optionally turn on **Create accounts on first sign-in** and pick the role, then choose **Enable single sign-on**. Test it with your own account: **Profile → Security → Sign-in methods → Link single sign-on for** your organization, or sign out and use **Sign in with SSO** with your work email.

**8. Require it (optional)**

Once your own sign-in through Okta has worked, you can turn on **Require single sign-on** under **Settings → Security**. See [Require single sign-on](https://docs.proofage.net/console/saml-sso.md#7-require-single-sign-on-optional).

**9. Add a dashboard tile (optional)**

Add Okta's **Bookmark App** integration from the catalog, name it `ProofAge`, set its URL to the **Sign-in URL** from **Settings → SSO** in ProofAge (see [The sign-in URL for dashboard tiles](https://docs.proofage.net/console/saml-sso.md#the-sign-in-url-for-dashboard-tiles)) and assign it to the same people. Its tile starts the sign-in at ProofAge, so it works.

## If it fails

The sign-in page says why; most refusals are also in **Settings → Audit log** as *Single sign-on refused*. The usual causes with Okta:

* **"Your identity provider did not send an email address"**: the `email` attribute statement is missing or misspelled, and the Name ID format is not `EmailAddress`.
* **"The identity provider's response could not be verified"**: the Single sign-on URL or Audience URI does not match ProofAge's values exactly, or Okta's signing certificate expired or changed: save the metadata URL in ProofAge again.
* **"This sign-in request expired or was already used"**: the person used the SAML app's own tile, which sends an IdP-initiated response. Hide that tile and use a bookmark app instead, or start at ProofAge.
* **"Your account is not a member of this organization"** or **"No account exists for this address"**: invite the person under **Team**, or turn on **Create accounts on first sign-in**.

See the full list in [When a sign-in is refused](https://docs.proofage.net/console/saml-sso.md#when-a-sign-in-is-refused).


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