---
title: "SAML SSO with Okta for Administrators - Payhawk Help Center"
slug: "setting-up-saml-sso-with-okta-identity-engine"
description: "Set up SAML single sign-on for Payhawk in Okta Identity Engine: create the SAML 2.0 app, map the email attribute, assign users, and send the IdP metadata."
updated: 2026-10-23T07:50:01Z
published: 2026-10-23T07:50:01Z
canonical: "payhawk.com/setting-up-saml-sso-with-okta-identity-engine"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://payhawk.com/help/llms.txt
> Use this file to discover all available pages before exploring further.

# Setting up SAML SSO with Okta (Identity Engine)

Okta is a vendor-neutral identity provider, and its modern architecture (the [Okta Identity Engine](https://help.okta.com/oie/en-us/content/topics/identity-engine/oie-index.htm)) allows Administrators to 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.

> [!WARNING]
> 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

To 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](https://www.okta.com/blog/2021/04/oktas-redesigned-admin-console-and-dashboard-now-in-ga/).
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](https://developer.okta.com/help/guides/build-sso-integration/saml2/main/#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.](https://cdn.payhawk.com/Help%20desk%20images%20moved/Setting_up_SAML_SSO_with_Okta_Identity_Engine_20250507_manual.png)

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.