All Collections
Payhawk for administrators
Security
Using SSO and setting up SAML with Payhawk
Using SSO and setting up SAML with Payhawk

Set up your SAML application with Payhawk and enable your users to utilise the SSO authentication method.

Miglen Evlogiev avatar
Written by Miglen Evlogiev
Updated yesterday

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.

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:

  1. Create a SAML application in your IdP that will be used with Payhawk.

  2. Assign the SAML application to your users and groups.

  3. By contacting the Support team at Payhawk, 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.

  4. 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:

  1. 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.

  2. In the navigation menu, expand Applications and select Applications.

  3. Click on Create App Integration.

  4. In the Create a new app integration menu, select SAML 2.0 as the Sign-in method.

  5. 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.

The Create a new app integration dialog in Okta Identity Engine with the SAML 2.0 option checked.

Now you have to configure the SAML integration for your Okta application:

  1. On the Create SAML Integration page, under General Settings, enter Payhawk as the name of your application.

  2. (Optional) Upload a logo and choose the visibility settings for your app.

  3. Click on Next.

  4. Under GENERAL, for a Single sign-on URL, enter: https://id.payhawk.com/saml2/idpresponse

  5. For Audience URI (SP Entity ID), enter: urn:amazon:cognito:sp:eu-central-1_mcW4Iwl7p

  6. Leave Default RelayState empty.

  7. Under ATTRIBUTE STATEMENTS, add a statement with the following Information:

    • For Name, enter the SAML attribute name email.

    • For Value, enter user.email.

  8. Either leave the default values of the other settings on the page or set them according to your preferences.

  9. Click on Next > Finish.

  10. Once the SAML application is configured, assign access to people and groups.

  11. Download the IdP metadata as an XML file and send it to the Implementations 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:

  1. Open entra.microsoft.com

  2. Go to Enterprise Applications.

  3. Click on New application > Create your own application.

  4. What's the name of your app? enter: Payhawk

  5. Select: Integrate any other application you don't find in the gallery (Non-gallery)

  6. On the application page, click on Getting Started > Single sign-on > SAML

  7. 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.

  8. As Unique User Identifier (UPN), use user.userprincipalname because users use their UPNs to log in.

  9. Download the Federation Metadata XML file and send it to the Implementations 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:

  1. Open the Google Workspaces as an Administrator.

  2. Navigate to the Apps > Web and mobile apps.

  3. Create a new SAML application.

  4. Select Payhawk as the application name.

  5. Download the metadata file.

  6. 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.

  7. Click on Continue.

  8. As Attribute mapping, add Primary email > email.

  9. Click on Finish.

  10. From Web and mobile apps, select your new Payhawk application and enable it for all users who are supposed to use it.

  11. Download the IdP metadata as an XML file and send it to the Implementations 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:

  1. Open the JumpCloud Admin Console and create a new SAML application.

  2. Type Payhawk as the application name.

  3. 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_mcW4Iwl7p

    • For ACS URL, enter: https://id.payhawk.com/saml2/idpresponse

    • For 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/payhawk

    • For Attributes, enter the following:

      • For Service Provided Attribute Name, enter email.

      • For JumpCloud Attribute Name, enter email.

  4. Download the IdP metadata as an XML file and send it to the Implementations Manager (IM) who will apply this on Payhawk's end.

Setting up SAML in OneLogin

  1. Login as Administrator in your OneLogin tenant and

  2. Navigate to Applications > Add App and search for SAML Custom Connector (Advanced)

  3. As application name type: Payhawk

  4. Under the configuration tab:

    1. RelayState: https://portal.payhawk.com/

    2. Audience (EntityID): urn:amazon:cognito:sp:eu-central-1_mcW4Iwl7p

    3. Recipient, ACS Consumer URL, and Validator, all three set as: https://id.payhawk.com/saml2/idpresponse

    4. SAML initiator: Service Provider

  5. Under the Parameters tab: add a new SAML Custom Connector (Advanced) Field.

    1. Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier

    2. Value: Email

    3. Include in SAML assertion: checked.

  6. Save the application and enable it for all users who are supposed to use it.

  7. Download the IdP metadata as an XML file from the top right: More Actions > SAML Metadata.

  8. Send it to the Implementations Manager (IM) who will apply this on Payhawk's end.


​

Useful resources

Did this answer your question?