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. 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. These are the following sections:

Okta (US multitenant)

• Follow this section if:

  1. Your identity provider is Okta, and

  2. Your Merge organization is based in the US multitenant

OneLogin

• Follow this section if:

  1. Your identity provider is OneLogin

Other providers or non-US/non-multitenant Merge organizations

• Follow this section if:

  1. Your identity provider is not Okta or OneLogin, or

  2. 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, you'll need to 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, please send the following to your CSM:

   1. Metadata XML

      OR

   2. IdP Certificate (aka 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. Then, 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, and hover over Applications tab and Click Applications > click in the top right the Add Apps button.

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, and copy the value for Issuer URL and SAML 2.0 Endpoint (HTTP) and click on 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),  X.509 Certificate

7. Go to the Configuration tab

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

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

   1. <SAML_PROVIDER_ID> will be provided by your CSM

   2. <DOMAIN>: This will be your tenant-specific URL. For example:

      1. US multitenant: api.merge.dev

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

Other providers or non-US/non-multitenant Merge 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 below details:

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

  • This may also be called the “ACS URL”

  • Make sure to include the trailing slash

  • Check the box “Use this for Recipient and Destination URL” in Okta

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

  • Make sure to include the trailing slash

• Default relay state: https://<DOMAIN>/api/users/sso/saml/relay

  • Trailing slash not necessary

• Name ID Format: EmailAddress

• Application username: Email

• The rest are “Advanced settings”:

  • Response: Signed

  • Assertion Signature: Signed

  • Signature Algorithm: RSA-SHA256

  • Digest Algorithm: SHA256

  • Assertion Encryption: Unencrypted

  • SAML Request: Unsigned (or “SAML Signed Request: Disabled”)

  • Enable Single Logout: Unchecked

  • Assertion Inline Hook: None (disabled)

  • Authentication Context Class: PasswordProtectedTransport

  • Honor Force Authentication: Yes

  • Attribute Statements: leave blank

  • Group Attribute Statements: leave blank

  • If using Okta:

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

  • If using Microsoft Entra:

    • Signing Option: Sign SAML response and assertion

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

• Metadata XML (called IDP Metadata in Google)

Or

• IdP Certificate (aka Public Certificate, or X.509 Certificate)

• IdP Issuer (should be a URL)

• IdP SSO URL

Final steps

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