Microsoft Entra ID (formerly Azure Active Directory) is the identity backbone of Microsoft 365 and Azure, so most organizations already run their user directory there. Registering Payhawk as a non-gallery enterprise application lets your team reach Payhawk with the Microsoft account they use every day, and Conditional Access, MFA, and group-based assignment keep applying exactly as they do for your other apps.
SAML does not support Identity Provider (IdP) initiated authentication. Your users must always start from the Payhawk login page. Two-factor authentication (2FA), where enabled, still applies, and SSO does not replace it.
Before you start
You need a role that can create and manage enterprise applications in Microsoft Entra (for example, Cloud Application Administrator or Global Administrator).
You need Payhawk Administrator rights in Payhawk to coordinate the setup.
Have your authentication domains ready (for example,
yourcompany.com), the email domains your users sign in with.The email Entra sends for each user must exactly match that user's Payhawk account email. Mismatched emails cause failed logins or duplicate users.
Payhawk service provider (SP) settings
То configure the SAML application in Microsoft Entra ID, use the following values Basic SAML Configuration pane. They are the same for every customer.
Setting | Value |
|---|---|
Identifier (Entity ID) |
|
Reply URL (Assertion Consumer Service URL) |
|
Sign on URL / Relay State / Logout URL | Leave empty (optional) |
Required attribute |
|
Creating and configuring the SAML application
Open entra.microsoft.com and sign in.
Go to Enterprise applications.
Select New application > Create your own application.
For the app name, enter Payhawk.
Select Integrate any other application you don't find in the gallery (Non-gallery), then select Create.
On the application page, go to Getting Started > Single sign-on and select SAML.
In the Basic SAML Configuration pane, enter the Payhawk service provider values:
For Identifier (Entity ID), enter:
urn:amazon:cognito:sp:eu-central-1_mcW4Iwl7pFor Reply URL (Assertion Consumer Service URL), enter:
https://id.payhawk.com/saml2/idpresponseLeave everything else that is optional empty.
Mapping the email attribute
Payhawk identifies each user by email, so the assertion must carry the user's email address.
In the Attributes & Claims section, verify that an
emailaddressclaim exists and resolves to the user's email address registered in Payhawk.Most often you will map it to user.userprincipalname or user.mail, whichever matches the email address you used to invite the user to Payhawk.
Assigning users
Go to Users and groups and assign the Payhawk application to the relevant users and groups.
Confirm each assigned user's email matches their Payhawk account.
Exporting the IdP metadata and sending it to Payhawk
In the SAML Certificates section of the Single sign-on page, download the Federation Metadata XML file. It contains the Entra SSO endpoint, entity ID, and signing certificate that Payhawk needs.
Contact your Payhawk Implementation Manager and provide the Federation Metadata XML file, your authentication domain(s), and confirmation of the email attribute mapping.
Payhawk completes the backend configuration and confirms when SSO is ready to test.
Testing the login
Go to the Payhawk login page.
Enter a corporate email address on an SSO-enabled domain.
Authenticate with Microsoft Entra, and complete any Conditional Access or 2FA step.
On success, you return to Payhawk logged in.
Troubleshooting
Redirected back to the login page or access denied - confirm the email claim is sent and its value matches the Payhawk account email exactly. If your users' UPN differs from their email, map the claim to user.mail.
Application not assigned - the user is not assigned to the Payhawk enterprise application in Entra.
IdP-initiated login fails - this is expected. Users must start from the Payhawk login page.