# SAML: Entra Enterprise application > Connect Microsoft Entra ID to Botyard over SAML 2.0 with a non-gallery Enterprise application: Basic SAML Configuration, claims, signing, metadata and single logout. Canonical URL: https://docs.botyard.io/docs/sso/entra-saml This guide connects Entra ID to a Botyard organization over SAML 2.0, using a non-gallery Entra Enterprise application. You need to be a Botyard organization owner and able to create Enterprise applications in your Entra tenant (for example as a Cloud Application Administrator). Setup goes in one pass: Botyard's values are fixed for your organization, so you can paste them into Entra before the connection exists. ## 1. Open Botyard's SAML values 1. In Botyard, open **User menu** › **Settings** › **General** › **Single sign-on**. 2. On the **Identity provider** card, under **Protocol**, select **SAML 2.0 (Enterprise app)**. 3. Keep this page open. Section **1. Give Entra these values** lists: | Botyard label | What it is | Path in the value | | ---------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------- | | **Identifier (Entity ID)** | Botyard's SAML entity ID for your organization | `…/sso/saml2/sp/metadata?providerId=saml-` | | **Reply URL (Assertion Consumer Service URL)** | Where Entra posts the SAML response | `…/sso/saml2/sp/acs/saml-` | | **Sign on URL** | Botyard's start of an SP-initiated sign-in | `…/sso/saml2/sp/start/saml-` | | **Logout URL** | Botyard's single logout endpoint | `…/sso/saml2/sp/slo/saml-` | | **Service provider metadata** | All of the above as a SAML metadata document | Same URL as the Identifier | Copy each value with its copy button, and don't type it by hand. Entra matches the Identifier exactly. ## 2. Create the Enterprise application 1. In the [Microsoft Entra admin center](https://entra.microsoft.com), go to **Enterprise applications** → **New application** → **Create your own application**. 2. Name it (for example "Botyard"), choose **Integrate any other application you don't find in the gallery (Non-gallery)**, and create it. 3. Open **Single sign-on** and choose **SAML**. ## 3. Basic SAML Configuration Edit **Basic SAML Configuration** and enter the values from Botyard: | Entra field | Botyard value | | ------------------------------------------ | ---------------------------------------------- | | Identifier (Entity ID) | **Identifier (Entity ID)** | | Reply URL (Assertion Consumer Service URL) | **Reply URL (Assertion Consumer Service URL)** | | Sign on URL | **Sign on URL** | | Logout Url | **Logout URL** | Leave **Relay State** empty. The **Sign on URL** matters. Botyard does not accept IdP-initiated SAML sign-ins: a response that does not answer a request Botyard issued is refused. Entra's My Apps tile opens the Sign on URL, which starts a normal SP-initiated sign-in, so the tile keeps working. ## 4. Attributes & Claims Botyard identifies a user by the tenant ID and object ID claims Entra includes in every SAML token. It reads the email and name claims for display only, never as an identifier. 1. Edit **Attributes & Claims**. 2. Open **Unique User Identifier (Name ID)** and set **Name identifier format** to **Persistent**. Use a source attribute that never changes for the user, such as `user.objectid`. 3. Make sure these claims are present, under these exact claim names: | Claim name | Used for | | -------------------------------------------------------------------- | ------------------------------------------ | | `http://schemas.microsoft.com/identity/claims/tenantid` | Pins the sign-in to your tenant. Required. | | `http://schemas.microsoft.com/identity/claims/objectidentifier` | The user's stable identity. Required. | | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` | Email address | | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` | First name | | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` | Last name | | `http://schemas.microsoft.com/identity/claims/displayname` | Display name | Entra issues `tenantid` and `objectidentifier` on its own; see Microsoft's [SAML token claims reference](https://learn.microsoft.com/en-us/entra/identity-platform/reference-saml-tokens). You don't add them. The email and name claims are in Entra's default claim set; keep them. Don't remove or rename them. ## 5. Signing Under **SAML Certificates**, edit **Token signing certificate**: * **Signing Option**: **Sign SAML assertion**, or **Sign SAML response and assertion**. Botyard requires a signed *assertion*. **Sign SAML response** alone is refused. * **Signing Algorithm**: **SHA-256**. Botyard refuses SHA-1 signatures and digests. Botyard doesn't sign its own SAML requests and doesn't need encrypted assertions, so leave **Verification certificates** and token encryption off. ## 6. Give Botyard Entra's metadata Under **SAML Certificates**, copy **App Federation Metadata Url**. Back in Botyard, under **2. Paste Entra's values here**: 1. Choose **Metadata URL** and paste it into **App Federation Metadata Url**, or choose **Paste XML** and paste the downloaded **Federation Metadata XML**. 2. Click **Connect SAML identity provider**. Botyard reads your tenant and the signing certificates from the metadata. Every other Entra endpoint is derived from the tenant, so nothing else in the document needs to be correct. The metadata must: * describe a single Entra tenant: an `entityID` of `https://sts.windows.net//`. Other identity providers are not supported over SAML. * carry one to three signing certificates; * be at most 256 KiB; * when given by URL, be served over HTTPS from `login.microsoftonline.com`. The connected card then shows **SAML 2.0**, **Active**, the **Tenant ID**, the **IdP entity ID**, and where the **Metadata** came from. ## 7. Assign users and test 1. In Entra, open the application's **Users and groups** and assign the people or groups who should be able to sign in. 2. Sign in as an assigned user through the application's tile in [My Apps](https://myapps.microsoft.com), or open the **Sign on URL** directly. First-time users join your organization as members. To create, update and remove members ahead of sign-in, set up [provisioning with SCIM](/docs/sso/entra-scim). ## Single logout Single logout is on. Only logout requests that Entra sends to Botyard must be signed. * **Entra → Botyard.** When a user signs out of Entra, Entra sends a logout request to the **Logout URL**. Botyard accepts it only if it is signed with SHA-256 or stronger by a certificate from your metadata, names your tenant as issuer and Botyard's Logout URL as destination, is within its validity window, and hasn't been seen before. Botyard then ends every Botyard session that user started through this connection; sessions they started some other way are left alone. Any other logout request is refused and signs nobody out. * **Botyard's reply to Entra is unsigned.** Botyard holds no SAML signing key, so the logout response it sends back to Entra carries no signature. * **Botyard → Entra.** Signing out of Botyard ends the Botyard session only. It does not sign the user out of Entra. * **Return leg.** If Entra sends a logout response back to Botyard, Botyard doesn't check its signature. It only accepts a response that answers a logout request Botyard itself sent for this connection and that is still pending. Such a response signs nobody out: the Botyard session ended before Botyard contacted Entra. If Entra reports that its side did not complete, the browser lands on the sign-in page with `sso_logout_incomplete`. After an Entra-initiated logout, requests that need organization access stop at once. A short tail remains elsewhere: Botyard's sign-in cache can keep a browser session alive for up to 10 minutes, and an access token already issued for non-organization pages, such as your own profile, stays valid for up to an hour. ## Rotate the signing certificate Entra publishes its next signing certificate in the metadata before it becomes active. Before you make a new certificate active in Entra: 1. In Botyard, on the **Identity provider** card, click **Refresh metadata**. 2. Submit the same **App Federation Metadata Url**, or paste the new XML. Botyard trusts every signing certificate in the metadata (up to three), so sign-ins keep working through the rollover.