Skip to content

Enable single sign-on (SAML 2.0)

Last updated: April 29, 2022

This page describes the steps you need to take to configure single sign-on (SSO) with Checkout.com. You can use any Identity Provider (IdP) to enable SSO with Dashboard, as long as they support Security Assertion Markup Language (SAML) 2.0.

The SSO configuration process involves three short setups:

Separate SAML applications are required if you want to set up SSO for both the Live and Test environments on Dashboard.


Identity Provider setup

Step 1: Create a Checkout.com application in Identity Provider

  1. Sign into your Identity Provider portal.
  2. Create a new SAML 2.0 application.
  3. Name the application. For example, Checkout.com Production or Checkout.com Sandbox.

Step 2: Configure the SAML settings

  1. Set Assertion Consumer Service (ACS) URL to http://localhost as a placeholder. Use this for the Recipient URL and Destination URL.
  2. Set Service Provider Entity ID (also called Audience URI) to http://localhost as a placeholder.
  3. Set Default Relay state to:
    • https://dashboard.checkout.com for production
    • https://dashboard.sandbox.checkout.com for sandbox
  4. Set the mandatory attribute statements as shown in the following table:
AttributeDescription

firstName

User's first name

lastName

User's last name

email

User's email

idpGroups

User's Dashboard-assigned role


Service Provider setup

Step 3: Define Dashboard roles

Checkout.com supports various user roles, each with a different level of access to the Dashboard account. See Team Permissions for a breakdown of each role.

  1. Set the idpGroups attribute to propagate your identity provider (IdP) roles as part of the SAML assertion. This helps configure access rights by mapping your IdP roles to the Checkout.com roles.
  2. Create a .json file that defines a mapping between the propagated groups to the Checkout.com’s roles, for example:
1
2
3
4
5
6
{
"ClientGroup1": "Owner",
"ClientGroup2": "Admin",
"ClientGroup3": "Read Only",
"ClientGroup4": "Read Only"
}

Step 4: Extract and securely share your configuration with Checkout.com

You will be given a set of SFTP login credentials, which you will use to securely share the following configurations generated by your IdP:

  • Identity Provider single sign-on URL, Identity Provider URL, or SAML endpoint
  • Identity Provider Issuer URL, or Entity ID
  • A certificate provided as a .crt file, or an X.509 certificate
  • Mapping of IdP groups to roles, as a .json file
  • Corporate email domain or domains. For example, mycompany.com, or mycompany.co.uk

Our team will then register your IdP with this configuration and get in touch with you to complete the setup.


Verify setup

Step 5: Finalize and test IdP-initiated login

When our team contacts you to confirm registration in our system and final setup details, return to your Identity Provider portal.

  1. Replace the placeholder values set in step 2 (ACS URL and the Service Provider Entity ID) with the parameters shared by our team.
  2. Ensure the Checkout.com application and all mandatory attributes defined in the previous steps have been assigned to users.
  3. While signed in as a permitted user, check that a Checkout.com application is visible on the SSO dashboard.
  4. Select the application. If everything is working correctly, it should authenticate you and redirect you to Checkout.com.
  5. If authentication was successful, contact the Checkout.com team to request activation of routing rules (SP-initiated login).

Step 6: Enable routing rules and test Checkout-initiated login

Once you’ve successfully tested IdP-initiated login, and our team has confirmed that routing rules (SP-initiated login) have been activated, take the following steps:

  1. Go to either:
    • https://dashboard.checkout.com (production)
    • https://dashboard.sandbox.checkout.com (sandbox)
  2. Enter your email address and select Next.
  3. If everything is working correctly, you should first be redirected to your IdP login, and then, once authenticated, to your Checkout.com dashboard.