The Single Sign-On (SSO) is an authentication method that allows users to securely identify with multiple applications and websites by using a single set of credentials.
The Security Assertion Markup Language (SAML) facilitates the secure authentication and authorisation of data exchange. SAML is the standard through which Service Providers (SP) and Identity Providers (IdP) communicate with each other to verify credentials.
For any support you may need during the initial setup of the SSO, contact your Implementation Manager.
For any subsequent changes of domains - including adding new domains to your account - contact Payhawk Support at support@payhawk.com.
A high-level overview of the SAML integration process
On a high level, to integrate Payhawk with your IdP by using SAML, you have to enable the standard in the following way:
Create a SAML application in your IdP that will be used with Payhawk.
Assign the SAML application to your users and groups.
Contact your Implementation Manager at Payhawk and provide the following details:
The XML metadata file of your SAML IdP which was downloaded during the creation of the SAML application.
The domain(s) that will be used for authentication.
The attribute mapping, usually email address to the email.
Once Payhawk completes the setup, test the authentication.
While the following sections provide the steps for configuring Okta, Azure, and Google being among the most common IdPs, you can apply the same process to any other IdP of your choice that supports SAML v2.
Once enabled, SAML does not support Identity Provider Initiated authentication. Therefore, if not yet authenticated, your users will still need to open the Payhawk Portal and type their email into the inbox.
Setting up SAML in Okta: Identity
To create a SAML application in Okta Identity Engine and enable SSO for your users, follow the steps:
Navigate to the Okta Developer console and log in as Administrator.
For more information about the console, see Okta’s Redesigned Admin Console and Dashboard.
In the navigation menu, expand Applications and select Applications.
Click on Create App Integration.
In the Create a new app integration menu, select SAML 2.0 as the Sign-in method.
Click on Next.
For more information, see the Prepare your Integration section in the Build a Single Sign-On (SSO) Integration guide on the Okta Developer website.
Now you have to configure the SAML integration for your Okta application:
On the Create SAML Integration page, under General Settings, enter Payhawk as the name of your application.
(Optional) Upload a logo and choose the visibility settings for your app.
Click on Next.
Under GENERAL, for a Single sign-on URL, enter:
https://id.payhawk.com/saml2/idpresponseFor Audience URI (SP Entity ID), enter:
urn:amazon:cognito:sp:eu-central-1_mcW4Iwl7pLeave Default RelayState empty.
Under ATTRIBUTE STATEMENTS, add a statement with the following Information:
For Name, enter the SAML attribute name email.
For Value, enter user.email.
Either leave the default values of the other settings on the page or set them according to your preferences.
Click on Next > Finish.
Once the SAML application is configured, assign access to people and groups.
Download the IdP metadata as an XML file and send it to the Implementation Manager (IM) who will apply this on Payhawk's end.
Setting up SAML in Microsoft Entra (Azure Active Directory)
To create a SAML application in Microsoft Entra and enable SSO for your users, follow the steps:
Open entra.microsoft.com
Go to Enterprise Applications.
Click on New application > Create your own application.
What's the name of your app? enter: Payhawk
Select: Integrate any other application you don't find in the gallery (Non-gallery)
On the application page, click on Getting Started > Single sign-on > SAML
Inside the pane Basic SAML Configuration, Input the following information to configure the Payhawk application:
For Identifier (Entity ID), enter:
urn:amazon:cognito:sp:eu-central-1_mcW4Iwl7p
For Reply URL, enter:
https://id.payhawk.com/saml2/idpresponse
For Attribute mapping, enter [email attribute in your system] → email.
Leave everything else that is optional as empty.
As Unique User Identifier (UPN), use user.userprincipalname because users use their UPNs to log in.
Download the Federation Metadata XML file and send it to the Implementation Manager (IM) who will apply this on Payhawk's end.
Setting up SAML in Google Workspace (GSuite)
To create a SAML application in Google Workspace and enable SSO for your users, follow the steps:
Open the Google Workspaces as an Administrator.
Navigate to the Apps > Web and mobile apps.
Create a new SAML application.
Select Payhawk as the application name.
Download the metadata file.
Fill in the fields in the following way:
For ACS URL, enter:
https://id.payhawk.com/saml2/idpresponse
For Entity ID, enter:
urn:amazon:cognito:sp:eu-central-1_mcW4Iwl7p
For Name ID format, enter EMAIL.
For Name ID, enter Basic Information > Primary email.
Click on Continue.
As Attribute mapping, add Primary email > email.
Click on Finish.
From Web and mobile apps, select your new Payhawk application and enable it for all users who are supposed to use it.
Download the IdP metadata as an XML file and send it to the Implementation Manager (IM) who will apply this on Payhawk's end.
Setting up SAML in JumpCloud
To create a SAML application in JumpCloud and enable SSO for your users, follow the steps:
Open the JumpCloud Admin Console and create a new SAML application.
Type Payhawk as the application name.
On the application configuration page, fill out the following fields. Once ready, click Finish.
For Idp Entity ID and SP Entity ID, enter:
urn:amazon:cognito:sp:eu-central-1_mcW4Iwl7pFor ACS URL, enter:
https://id.payhawk.com/saml2/idpresponseFor SAML Subject NameID, enter email.
For SAML Subject NameID Format, enter emailAddress.
For Declare Redirect Endpoint, enter Checked.
For IDP URL, enter:
https://sso.jumpcloud.com/saml2/payhawkFor Attributes, enter the following:
For Service Provided Attribute Name, enter email.
For JumpCloud Attribute Name, enter email.
Download the IdP metadata as an XML file and send it to the Implementation Manager (IM) who will apply this on Payhawk's end.
Setting up SAML in OneLogin
To create a SAML application in OneLogin and enable SSO for your users, follow the steps:
Login as Administrator in your OneLogin tenant.
Navigate to Applications > Add App and search for Payhawk.
Leave the settings as they are on the initial screen.
Ensure that in Configuration the domain is: payhawk.
Ensure that in Parameters the attribute mapping is: email to Email, and the Included in SAML assertion is checked.
Save the application and enable it for all users who are supposed to use it.
Download the IdP metadata as an XML file from the top right (More Actions > SAML Metadata) and send it to the Implementation Manager (IM) who will apply this on Payhawk's end.