SAML: Entra Enterprise application

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:

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, 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:

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:

Entra issues tenantid and objectidentifier on its own; see Microsoft's SAML token claims reference. 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/<tenant ID>/. 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, 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.

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.