PPact
Security & Privacy

SSO setup — Microsoft Entra ID (Azure AD)

Step-by-step SAML 2.0 single sign-on and SCIM 2.0 provisioning setup for Microsoft Entra ID (Azure AD), with exact claim names and group-to-role mapping.

Connect Microsoft Entra ID (formerly Azure AD) to Pact for SAML 2.0 single sign-on and optional SCIM 2.0 provisioning. Roughly 10 minutes.

Before you start

  • Owner or admin in Pact; Application Administrator (or Global Admin) in Entra.
  • Your sign-in domain (e.g. acme.com).
  • Open Admin → Single Sign-On (/admin/sso) in Pact and the Entra admin center (entra.microsoft.com).

Pact's Service Provider values

Entra fieldValue
Reply URL (ACS)https://<your-pact-api-host>/v1/sso/saml/acs/<workspace-id>
Identifier (Entity ID)https://<your-pact-api-host>/v1/sso/saml
Logout URL (optional)https://<your-pact-api-host>/v1/sso/saml/slo/<workspace-id>
Sign on URL (optional)https://<your-pact-host>/login

Copy these from Pact, not from this page. Admin → Single Sign-On shows the exact values for your workspace, and GET /v1/admin/saml/sp-metadata.xml downloads them as SP metadata. Two details decide whether sign-in works: the ACS URL ends in your workspace ID (the bare /v1/sso/saml/acs only serves a deployment's default workspace), and the Entity ID is /v1/sso/saml itself — not the metadata URL. An IdP that uses the metadata URL as its audience issues assertions Pact refuses (auth.saml.acs.failure, reason validation_failed).

Entra matches the Reply URL exactly: Pact's sign-in request names the workspace-scoped ACS URL, so a Reply URL without the workspace ID fails at Entra with AADSTS50011.

1. Create the Enterprise Application

  1. Entra admin center → Identity → Applications → Enterprise applications → New application.
  2. Create your own application → name it "Pact" → Integrate any other application you don't find in the gallery → Create.
  3. Open the app → Single sign-on → SAML.
  4. Basic SAML Configuration → Edit:
    • Identifier (Entity ID) → Pact's SP Entity ID.
    • Reply URL (ACS) → Pact's ACS URL.
    • Save.

2. Claims

Entra's default claim names are full schema URIs — Pact's defaults already match these, so you can usually leave the mapping blank. The relevant claims:

PurposeEntra claim name
Emailhttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
First namehttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
Last namehttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

For roles, add a group claim: Attributes & Claims → Add a group claim → Security groups (or Groups assigned to the application), Source attribute Group ID or sAMAccountName. The default group claim name is http://schemas.xmlsoap.org/claims/Group — put that in Pact's Groups attribute field if you customise it.

3. Register Entra in Pact

  1. In Entra: SAML Certificates → App Federation Metadata Url — copy it.
  2. In Pact: Admin → SSO (SAML) → Add IdP.
  3. Paste the Metadata URL → Fetch (fills entity ID, SSO URL, signing cert).
  4. Set Display name ("Microsoft Entra ID") and Email domain (acme.com).
  5. Leave attribute mappings blank to use the schema-URI defaults, or set them to match your custom claims.
  6. Save. Use Refresh later to pick up Entra's rolling signing certs.

4. Group → role mapping (optional)

In the Pact IdP form, Group → role mapping. Entra sends the group Object ID by default, so map those GUIDs (or switch the group claim source to a name attribute and map the names):

IdP group valuePact role
<admins-group-object-id>admin
<managers-group-object-id>manager

Highest-precedence match wins; groups elevate only.

5. Assign users, then test

  1. Entra: Users and groups → Add user/group — assign the people who should have access.
  2. Pact: Admin → SSO (SAML) → Test on the Entra row → complete the login → confirm auth.saml.acs.success in the audit log.

6. (Optional) Signed AuthnRequests

If your Entra policy mandates signed requests: Admin → SSO (SAML) → SP signing key → Generate, re-download SP metadata, then tick Sign AuthnRequests on the IdP. Both AuthnRequests and LogoutRequests are then signed with the encrypted-at-rest SP key.

7. Verify domain + enforce + break-glass

  1. Admin → SSO → Domains → add acme.com, add the TXT record, Verify.
  2. Designate a break-glass admin under Enforcement → Break-glass emergency admins first.
  3. Toggle Require SSO for all users.

If Entra is ever down, break-glass admins keep password login (audited as auth.break_glass.used).

SCIM provisioning (optional)

Entra's enterprise app supports SCIM provisioning natively: Provisioning → Get started → Automatic, Tenant URL https://<your-pact-host>/scim/v2, Secret Token = a Pact SCIM token (mint under Admin → Identity (SCIM)). Pact maps department and manager from the enterprise extension Entra pushes. Full detail: SCIM provisioning.