Fall '26 edition: Prompt your finance | Join the webinar

Setting up SAML SSO with Okta (Identity Engine)

Prev Next

Okta is a vendor-neutral identity provider, and its modern architecture (the Okta Identity Engine) allows Administrators assemble the exact sign-in policy Payhawk needs from a standard SAML 2.0 application. Once it is in place, your team signs in to Payhawk with their Okta credentials instead of a separate Payhawk password, and who can reach Payhawk follows the app assignments you already manage in Okta.

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 Administrator access to the Okta Admin Console.

  • 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 held in Okta 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 Okta, use the following values. They are the same for every customer.

Setting

Value

Single sign-on URL / Audience - ACS URL

https://id.payhawk.com/saml2/idpresponse

Audience URI (SP Entity ID)

urn:amazon:cognito:sp:eu-central-1_mcW4Iwl7p

Default RelayState

Leave empty

Name ID format

EmailAddress

Required attribute

email, mapped to user.email

Creating and configuring the SAML application

  1. Sign in to the Okta Admin Console as an 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. Select Create App Integration.

  4. In the Create a new app integration menu, select SAML 2.0 as the Sign-in method, then select 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.

  1. On the Create SAML Integration page, under General Settings, enter Payhawk as the app name. Optionally, upload a logo and choose the visibility settings, then select Next.

  2. Under SAML Settings > GENERAL, enter the Payhawk service provider values:

    • For Single sign-on URL, enter: https://id.payhawk.com/saml2/idpresponse. Keep Use this for Recipient URL and Destination URL selected.

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

    • Leave Default RelayState empty.

    • For Name ID format, select EmailAddress, and for Application username, select Email.

  3. Leave the remaining settings at their defaults, or set them according to your preferences.

Mapping the email attribute

Payhawk requires a single attribute named email.

  1. On the same page, under ATTRIBUTE STATEMENTS, add a statement:

    • For Name, enter email.

    • For Name format, leave Unspecified.

    • For Value, enter user.email.

  2. Select Next, complete the feedback step, and select Finish.

Assigning users

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

  2. Confirm each assigned user's Okta email matches their Payhawk account email.

Exporting the IdP metadata and sending it to Payhawk

  1. Open the Payhawk application and go to the Sign On tab.

  2. Under SAML Signing Certificates or SAML Setup, download the Identity Provider metadata as an XML file. It contains the Okta SSO endpoint, entity ID, and signing certificate that Payhawk needs.

  3. Contact your Payhawk Implementation Manager and provide the IdP 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

  1. Go to the Payhawk login page.

  2. Enter a corporate email address on an SSO-enabled domain.

  3. Authenticate with Okta, and complete any Okta Verify or 2FA step.

  4. On success, you return to Payhawk logged in.

Troubleshooting

  • Redirected back to the login page or access denied - confirm the email attribute is sent and its value matches the Payhawk account email exactly.

  • Application not assigned - the user is not assigned to the Payhawk app in Okta.

  • IdP-initiated login fails - this is expected. Users must start from the Payhawk login page.