Setting up SAML SSO with JumpCloud

JumpCloud is a cloud directory platform, a modern alternative to on-premises Active Directory that combines identity, SSO, and device management in one console. Payhawk supports JumpCloud as an identity provider for SSO over SAML, so your team can sign in with their JumpCloud credentials, and you manage that access alongside the users and devices you already administer there.

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

Creating and configuring the SAML application

1. Open the JumpCloud Admin Console and create a new SSO application named Payhawk using the Custom SAML App option.

2. Configure the following key parameters:

   • IdP Entity ID and SP Entity ID: use the SP Entity ID provided by Payhawk, urn:amazon:cognito:sp:eu-central-1_mcW4Iwl7p.

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

   • SAML Subject NameID: set this to email.

   • SAML Subject NameID Format: choose emailAddress.

   • Declare Redirect Endpoint: enable this setting.

   • IdP URL: specify the JumpCloud IdP SSO URL for this application.

Mapping the email attribute

Payhawk requires a single attribute named email.

1. In the application's Attributes section, add a user attribute mapping with the Service Provider Attribute Name set to email and the JumpCloud Attribute Name set to email.

2. Make sure the attribute is included in the SAML assertion sent to Payhawk.

Assigning users

1. On the User Groups tab of the application, assign the Payhawk application to the relevant users and groups.

2. Confirm each assigned user has a valid email that matches their Payhawk account.

Exporting the IdP metadata and sending it to Payhawk

1. Export the metadata XML file for this SAML application. It contains the JumpCloud SSO endpoint, entity ID, and signing certificate that Payhawk needs.

2. Contact your Payhawk Implementation Manager or Payhawk Support 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 JumpCloud, and complete any 2FA step.

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

Migration from Google to JumpCloud

If you are switching from Google SSO to JumpCloud, no migration is needed in Payhawk as long as the email attribute returned by JumpCloud matches the corporate email previously used in Google SSO.

• Payhawk identifies users by email. To avoid duplicate accounts or lost access to cards, expenses, or permissions, ensure the JumpCloud email attribute matches the existing Payhawk email.

• If the email differs, a new Payhawk user account is created, and the prior data does not transfer.

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 bound to the Payhawk application through a JumpCloud user group.

• Duplicate account after switching IdP - the email attribute does not match the email already in Payhawk. Align the emails before the first sign-in.

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