> ## 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 Microsoft Entra ID

> Connect Microsoft Entra ID to the ProofAge console with SAML 2.0, and make sure each user's Email field is set so Microsoft sign-in and SSO find them.

This guide connects a Microsoft Entra ID tenant to ProofAge with SAML. 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 Entra role that can create enterprise applications, such as Application Administrator.

## Fill in every user's Email field first

> [!WARNING]
>
> Each person who signs in to ProofAge with a Microsoft work account needs the **Email** attribute (`mail`) filled in on their Entra user, with an address on a domain your tenant has verified. Microsoft sends the email address (and the `xms_edov` claim that says the domain owner verified it) only when this field is set.
>
> * **Sign in with Microsoft** with an empty Email field fails with `email_missing` (the sign-in page's address shows `sso_error=email_missing`): "Microsoft did not share an email address for this account. If it is a work account, ask your administrator to fill in its Email field, or use another way to sign in." ProofAge does not fall back to the user principal name.
> * **SAML** reads the address from the `emailaddress` claim, which Entra fills from the same field and leaves out when it is empty. ProofAge then uses the Name ID only if its format is email address; with Entra's default Name ID that is the user principal name, which is right only if it is the person's real email address.

Microsoft 365 tenants with Exchange Online fill the field for every mailbox. Without Exchange mail it is often empty. Set it in the Microsoft Entra admin center under **Users →** the user **→ Properties → Contact information → Email**.

## Connect Entra ID with SAML

**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 enterprise application**

In the Microsoft Entra admin center, go to **Enterprise applications → New application → Create your own application**. Name it `ProofAge`, choose **Integrate any other application you don't find in the gallery (Non-gallery)** and create it.

**4. Set up SAML**

Open **Single sign-on**, choose **SAML**, and edit **Basic SAML Configuration**:

| Entra field | Value |
| - | - |
| **Identifier (Entity ID)** | ProofAge's **Entity ID** |
| **Reply URL (Assertion Consumer Service URL)** | ProofAge's **ACS URL** |
| **Sign on URL** | ProofAge's **Sign-in URL** (see [The sign-in URL for dashboard tiles](https://docs.proofage.net/console/saml-sso.md#the-sign-in-url-for-dashboard-tiles)) |

With the **Sign on URL** set, the ProofAge tile in My Apps starts the sign-in at ProofAge. Without it, the tile sends an IdP-initiated response, which ProofAge refuses. Leave **Relay State** and **Logout Url** empty, and save.

**5. Check the claims**

Under **Attributes & Claims**, Entra's defaults work:

* **Unique User Identifier (Name ID)**: keep it. Do not switch it to a transient format, which ProofAge refuses. By default it is the user principal name, so renaming a user changes it: ProofAge then links the person again by email if their address is on a verified domain; someone who linked single sign-on from their profile without a verified domain links it again there.
* `emailaddress` from `user.mail`: required, see the warning above.
* `name` from `user.userprincipalname`: ProofAge uses this claim as the name of an account created on first sign-in. Change its source attribute to `user.displayname` if you want people's display names instead.

**6. Give ProofAge Entra's metadata**

Under **SAML Certificates**, copy the **App Federation 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 Entra's entity ID, Entra's own sign-in URL and the certificate fingerprint.

**7. Assign people**

Under **Users and groups**, add the people or groups who use ProofAge, including yourself. They see ProofAge in My Apps; to hide it, set **Visible to users?** to **No** under **Properties**.

**8. 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.

**9. Require it (optional)**

Once your own sign-in through Entra ID 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).

## 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 Entra ID:

* **"Your identity provider did not send an email address"**: the person's **Email** field is empty and the Name ID is not in the email address format. Fill in the field.
* **"The identity provider's response could not be verified"**: the Identifier or Reply URL does not match ProofAge's values exactly, or the signing certificate in Entra expired or changed: save the metadata URL in ProofAge again.
* **"This sign-in request expired or was already used"**: the person opened ProofAge from My Apps while the **Sign on URL** was empty. Set it under **Basic SAML Configuration**, 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).

## Sign in with Microsoft without SAML

Your team can also use **Continue with Microsoft** on the sign-in page with no SAML connection at all. It needs the same **Email** field. It cannot be required, and someone without a ProofAge account who uses it creates an organization of their own instead of joining yours: invite people first. See [Sign in with Google or Microsoft](https://docs.proofage.net/console/sign-in-with-google-microsoft.md).


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