# Microsoft Entra ID (https://docs.fuser.studio/docs/teams/sso/entra) Entra ID connects to Fuser over **SAML 2.0** using a non-gallery enterprise application. > [!WARNING] Entra's default claim names do not work > > Entra sends its claims under the `http://schemas.xmlsoap.org/...` namespace by default. Fuser matches attribute names exactly, so those claims are invisible to it and sign-in falls back to the NameID — which for guest accounts is a tenant-internal string, not a working address. > > Step 4 adds the plain-named claims that make the connection reliable. Do not skip it. > [!WARNING] Guests keep their home-domain address > > Fuser binds a provider to one DNS-verified email domain and, when it first creates an account, only accepts addresses inside it. What it checks is the **asserted address**, not the account's status in your tenant. > > That usually rules out B2B guests, because a guest's `user.mail` is their own company's address — `person@othercompany.com` — and no claim configuration changes what that value is. A guest you have deliberately given a mailbox on your verified domain signs in normally. > > For everyone else, use a member account on your verified domain, or invite them to Fuser by email. ## Set up [#set-up] ### Create the enterprise application [#create-the-enterprise-application] In the [Microsoft Entra admin center](https://entra.microsoft.com), go to **Identity** → **Applications** → **Enterprise applications** → **New application** → **Create your own application**. Name it (for example, `Fuser`), choose **Integrate any other application you don't find in the gallery**, and create it. Open the new application, go to **Single sign-on**, and choose **SAML**. ### Collect Entra's details [#collect-entras-details] On the **Set up Single Sign-On with SAML** screen you need three things: | Fuser field | Where to find it in Entra | | ----------------------- | ----------------------------------------------------------------------------------- | | **Issuer** | Section 4, **Microsoft Entra Identifier** — `https://sts.windows.net//` | | **Sign-on URL** | Section 4, **Login URL** — `https://login.microsoftonline.com//saml2` | | **Signing certificate** | Section 3, **Certificate (Base64)** — download it and open it in a text editor | Copy the certificate including its `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines. ### Register the provider in Fuser [#register-the-provider-in-fuser] In Fuser, open **Settings** → **Workspace** → **Security** → **Single Sign-On**, choose **SAML**, and enter your email domain along with the three values above. Click **Add provider**. Back in Entra, edit section 1, **Basic SAML Configuration**, and paste Fuser's values: | Entra field | Paste from Fuser's provider card | | ---------------------------------------------- | -------------------------------- | | **Identifier (Entity ID)** | **Entity ID / Audience URI** | | **Reply URL (Assertion Consumer Service URL)** | **ACS URL** | Leave **Sign on URL**, **Relay State**, and **Logout Url** empty. Fuser does not support IdP-initiated sign-in, so the Fuser tile in My Apps will not work — members sign in from Fuser. ### Configure the claims [#configure-the-claims] Still in the SAML screen, edit section 2, **Attributes & Claims**. Use **Add new claim** for each of the following, and leave the **Namespace** field **empty** every time. The namespaced claims Entra created for you can stay — Fuser ignores them. | Claim name | Source attribute | Required | | ------------- | ------------------ | -------- | | `email` | `user.mail` | Yes | | `givenName` | `user.givenname` | No | | `surname` | `user.surname` | No | | `displayName` | `user.displayname` | No | `displayName` is only read when `givenName` and `surname` are both absent, so send either the pair or the single claim — not necessarily all three. > [!WARNING] Choose the Name ID deliberately > > Entra's **Unique User Identifier (Name ID)** defaults to `user.userprincipalname`. Fuser stores it as the account identifier and resolves returning members by it, so it must be unique per person and stable over time — see [The NameID identifies the account](https://docs.fuser.studio/docs/teams/sso.md#the-nameid-identifies-the-account). > > `user.objectid` is the safer source: a GUID that survives a rename, where a UPN or mail address can be changed and later reassigned to someone else. If you are configuring a new connection, prefer it. > > Changing the Name ID on an existing connection is not free — members are re-attached by email address on their next sign-in, which works but leaves the old link behind. Never use the **transient** format, which issues a fresh value on every sign-in. ### Assign users [#assign-users] Go to **Users and groups** in the enterprise application and assign the people or groups who should have access. Entra grants nothing by default. > [!WARNING] Assignment takes time to propagate > > A member who is not yet assigned gets a Microsoft error page reading **AADSTS50105** — the signed-in user is not assigned to a role for the application. The same error appears for a few minutes after you assign someone, while the change propagates. Wait and retry before assuming the configuration is wrong. ### Verify the domain and test [#verify-the-domain-and-test] Add the TXT record shown on Fuser's provider card, wait for the card to flip to **Verified — SSO active**, then sign in from Fuser with a Entra-managed address on that domain. See [Verifying the domain with DNS](https://docs.fuser.studio/docs/teams/sso.md#verifying-the-domain-with-dns) for the details. ## Rotating the signing certificate [#rotating-the-signing-certificate] Entra certificates expire, by default three years after creation. Entra emails the app's notification address 60, 30, and 7 days out. Fuser stores the certificate you pasted at registration and does not fetch updates from your federation metadata. It holds exactly one certificate, so rolling the certificate in Entra means removing the provider in Fuser and adding it again with the new one. **Expect an interruption.** Entra's overlap window — where old and new certificates are both valid — does not spare you, because Fuser can only trust one of the two at a time. Microsoft gives the same advice for service providers that accept a single certificate. Schedule the swap for a quiet window. Removing and re-adding mints new endpoint URLs and a new DNS record, so plan on re-pasting them in your IdP and verifying the domain again — see [Provider settings are final](https://docs.fuser.studio/docs/teams/sso.md#provider-settings-are-final). ## Troubleshooting [#troubleshooting] The member is not in **Users and groups** for the enterprise application, or the assignment has not propagated yet. Assign them and retry after a few minutes. The assertion carried an address that is not inside your verified domain. Two distinct causes: * **The `email` claim is missing**, so Fuser fell back to the NameID and got a UPN that is not a working address — a `#EXT#` guest identifier, or a UPN that differs from the mailbox. Add the plain `email` claim sourced from `user.mail`. * **The asserted address belongs to another domain.** Typical for a B2B guest, whose `user.mail` is their own company's address. No claim configuration changes that value. See the note at the top of this page. Use the **Microsoft Entra Identifier** from section 4, not the application ID or the Entra tenant ID on its own. It ends with a trailing slash, which is part of the value. The `givenName` and `surname` claims are missing or still namespaced. Add them with an empty namespace field. ## What's Next? [#whats-next] - [SSO overview](https://docs.fuser.studio/docs/teams/sso.md): Domain verification, enforcement, and what members see. - [Members](https://docs.fuser.studio/docs/teams/members.md): Roles, invitations, and seat management.