Overview

We're excited to support SAML as a common Single Sign-on (SSO) protocol for your Merge organization. This guide outlines the prerequisites and the steps to configure SAML, broken down by each provider.

If your organization is using Google SAML (not the standard Sign in with Google button on our login page, which uses OAuth), you will be using these setup instructions from Google.

Prerequisites

SAML is currently only offered on Professional and Enterprise plans. If you want to upgrade your plan, please contact us at [email protected] and our team will assist you.

Setup process

1. Contact your Customer Success Manager (CSM) to set up a SAML provider for you within Merge. Let them know:

   1. The SAML provider you are using

   2. The tenant you want SAML configured in

   3. The name of the Merge organization you want SAML configured for

2. Use the sections below to receive and configure the SAML parameters for your identity provider. Instructions are organized by provider type and Merge organization configuration.

The following sections are available:

• Okta (US multitenant) — follow this section if your identity provider is Okta and your Merge organization is based in the US multitenant.

• OneLogin — follow this section if your identity provider is OneLogin.

• Other providers or non-US Merge organizations — follow this section if your identity provider is not Okta or OneLogin, or your Merge account is a sandbox, EU-based, or single-tenant organization.

Okta (US multitenant)

We support SSO with Okta via SAML, as opposed to other Okta login options such as OAuth or Open ID Connect (OIDC). To get set up with Okta on Merge:

1. Find Merge in the Okta OIN and connect it for your organization.

2. After connecting, go to the Sign On tab and click Edit to enter the following details:

   1. Customer ID: Will be provided by your CSM

   2. Default Relay State: https://api.merge.dev/api/users/sso/saml/relay

   3. Credential details: email

3. After you have configured those, send the following to your CSM:

   1. Metadata XML

      OR

   2. IdP Certificate (also known as Public Certificate, or X.509 Certificate)

   3. IdP Issuer (should be a URL)

   4. IdP SSO URL

Your CSM will use that info to finalize the SAML config for your organization in Merge and will enable SAML at that time. After confirmation that SAML is working, you will have the option to make it the only allowed login method for your organization in Merge.

OneLogin

You will need to create a new integration within the OneLogin portal and configure the below:

1. Log in to the OneLogin Admin Dashboard, hover over the Applications tab, and click Applications > Add Apps in the top right.

2. Search for SAML, and select SAML Test Connector (IdP w/attr).

3. When prompted, change the Display Name of your app to Merge API.

4. Click Save.

5. Go to the SSO tab, copy the value for Issuer URL and SAML 2.0 Endpoint (HTTP), then click the View Details link at the X.509 Certificate field and copy the X.509 Certificate.

6. Send your CSM the Issuer URL, SAML 2.0 Endpoint (HTTP), and X.509 Certificate.

7. Go to the Configuration tab.

8. Enter this regex into the ACS (Consumer) URL Validator field: https:\\/\\/[a-z0-9-]+\\.[a-z]+\\.[a-z]+\\.[a-z]+\\/sso\\/saml\\/[a-z0-9-]+\\/acs\\/

9. Enter this URL into the ACS (Consumer) URL field: https://<DOMAIN>/sso/saml/<SAML_PROVIDER_ID>/acs/

   1. <SAML_PROVIDER_ID> will be provided by your CSM.

   2. <DOMAIN> is your tenant-specific URL. For example:

      1. US multitenant: api.merge.dev

      2. EU multitenant: api-eu.merge.dev

Other providers or non-US organizations

If you're not using OneLogin, using Okta but not in the US multitenant, or using another provider, you'll need to create a new SAML integration with the details below.

The details below have some placeholders:

• <SAML_PROVIDER_ID>: Your CSM will provide this.

• <DOMAIN>: This is your tenant-specific URL. For example:

  • US multitenant: api.merge.dev

  • EU multitenant: api-eu.merge.dev

To get set up:

1. In your identity provider's admin console, create a new SAML integration and configure the following parameters:

   1. Single Sign On URL: https://<DOMAIN>/sso/saml/<SAML_PROVIDER_ID>/acs/

      1. This may also be called the ACS URL.

      2. Make sure to include the trailing slash.

      3. Check the box Use this for Recipient and Destination URL in Okta.

   2. Audience URI (SP Entity ID): https://<DOMAIN>/sso/saml/<SAML_PROVIDER_ID>/

      1. Make sure to include the trailing slash.

   3. Default Relay State: https://<DOMAIN>/api/users/sso/saml/relay

      1. Trailing slash not necessary.

   4. Name ID Format: EmailAddress

   5. Application username: Email

2. Under Advanced settings, configure:

   1. Response: Signed

   2. Assertion Signature: Signed

   3. Signature Algorithm: RSA-SHA256

   4. Digest Algorithm: SHA256

   5. Assertion Encryption: Unencrypted

   6. SAML Request: Unsigned (or SAML Signed Request: Disabled)

   7. Enable Single Logout: Unchecked

   8. Assertion Inline Hook: None (disabled)

   9. Authentication Context Class: PasswordProtectedTransport

   10. Honor Force Authentication: Yes

   11. Attribute Statements: leave blank

   12. Group Attribute Statements: leave blank

3. If using Okta, also configure:

   1. SAML Issuer ID for Okta users: http://www.okta.com/${org.externalKey}

4. If using Microsoft Entra, also configure:

   1. Signing Option: Sign SAML response and assertion

5. After you have configured the above, send your CSM the following values:

   1. Metadata XML (called IDP Metadata in Google)

      OR

   2. IdP Certificate (also known as Public Certificate, or X.509 Certificate)

   3. IdP Issuer (should be a URL)

   4. IdP SSO URL

Final steps

After configuration is completed, confirm to your CSM that SSO is working. If you'd like, we can make SAML required for your organization.