SSO setup — Microsoft Entra ID (Azure AD)

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 field	Value
Reply URL (ACS)	`https://<your-pact-host>/v1/sso/saml/acs`
Identifier (Entity ID)	`https://<your-pact-host>/v1/sso/saml/metadata.xml`
Sign on URL (optional)	`https://<your-pact-host>/login`

Exact values: Admin → SSO (SAML) → Show SP metadata.

1. Create the Enterprise Application

Entra admin center → Identity → Applications → Enterprise applications → New application.
Create your own application → name it "Pact" → Integrate any other application you don't find in the gallery → Create.
Open the app → Single sign-on → SAML.
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:

Purpose	Entra claim name
Email	`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`
First name	`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname`
Last name	`http://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

In Entra: SAML Certificates → App Federation Metadata Url — copy it.
In Pact: Admin → SSO (SAML) → Add IdP.
Paste the Metadata URL → Fetch (fills entity ID, SSO URL, signing cert).
Set Display name ("Microsoft Entra ID") and Email domain (acme.com).
Leave attribute mappings blank to use the schema-URI defaults, or set them to match your custom claims.
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 value	Pact role
`<admins-group-object-id>`	`admin`
`<managers-group-object-id>`	`manager`

Highest-precedence match wins; groups elevate only.

5. Assign users, then test

Entra: Users and groups → Add user/group — assign the people who should have access.
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

Admin → SSO → Domains → add acme.com, add the TXT record, Verify.
Designate a break-glass admin under Enforcement → Break-glass emergency admins first.
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.