Enable single sign-on with Google
Last updated: June 12, 2024
You can configure single sign-on (SSO) with Checkout.com to authenticate users on the Dashboard using your team's Google credentials.
With SSO enabled, your users can sign in to the Dashboard from one of the following:
- Google (identity provider-initiated sign in)
- The Dashboard sign-in page (service provider-initiated sign in)
As an administrator, you can also leverage your identity provider to manage all your user accounts in one central location.
To enable SSO, you must meet the following requirements:
- Be assigned the Owner or IAM Admin role in the Dashboard.
- Have administrative privileges with your Google Cloud account to create a Security Assertion Markup Language (SAML) application on your organization's end, enabling you to configure Google as your external identity provider (IdP).
- Be able to update your domain host’s DNS record for domain verification, or have access to someone with access to do so.
The following process covers how to configure SSO for one of your Dashboard environments.
If you want to configure SSO for both your Live and Test Dashboard environments, you must follow these steps twice, once for every environment:
- Initiate SSO configuration in the Dashboard
- Configure SSO in Google Cloud
- Continue the SSO configuration in the Dashboard
- Finish SSO configuration in the Dashboard
- Sign in to the Dashboard environment for which you want to configure SSO:
- Go to Settings > Single Sign-on.
- Select Google Cloud IDP from the list of identity providers.
- Select Start Configuration.
- In the Configure Single sign-on page, save the following values:
- Assertion Consumer Service (ACS) URL
- SP Entity ID
Both values are required to configure your SAML application in your Google Cloud account.
You must perform the following configuration in your Google Cloud environment.
Before configuring your Google Cloud account as an IdP, you must create a user group in Google to represent the Identity and Access Management (IAM) Administrator or Owner role in your Dashboard.
- Sign in to your Google Admin Console for your Workspace account.
- Create a Google group and name it with a representative name. For example,
checkout_iam_admin. - Assign a user to the group you just created. You will use this user's credentials to log in to the Dashboard and validate your SSO configuration.
You can create multiple Google groups to represent different roles in your Dashboard. For example, checkout_iam_admin, or checkout_support_manager.
When configuring your SSO connection with Checkout.com, you can map your Google group to a predefined Dashboard role or custom role. That role is then assigned to every member of the group.
Each Google user has specific attributes, such as First name, Last name, or Email address. You can create custom user attributes and later map them to specific sets of entities and segments in your Dashboard to limit user access.
For example, assume you have an entity named UK Entity The Cake Shop and two segments associated with it: Food & Beverage and
Entertainment. In Google, you can create a custom attribute called CKO-Entities-Segments with the value UK-Cake-Shop-All-Segments. You can later map this value to the respective entity and segments in your Dashboard enabling users to access the UK Entity The Cake Shop and all associated segments.
To create custom attributes for your Google group users:
- Navigate to Directory > Users.
- Select More options > Manage custom attributes.
- Select Add Custom Attribute.
- In Category, enter a name for the category you want to add.
- Under Custom fields, configure the name of your custom attribute. For example, CKO-Entities.
- Set the Number of Values option to
Multi-value.
You can then access user profiles and assign multiple values to the custom attribute you created. These values represent the combination of entities and segments the user can access. You will define this combination in the Dashboard in a later step.
- In Google, navigate to Apps > Web and mobile apps.
- Select Add app > Add custom SAML app.
- Provide a Name and Description for your SAML app.
Because each SAML application you create is only valid for a single Checkout.com environment, you should give each SAML application a unique and recognizable name if you plan to enable SSO for both Live and Test Dashboard environments. For example, Checkout.com Test and Checkout.com Live. - Select Continue.
- In the Google Identity Providers Details page:
- Save the SSO URL value.
- Save the Entity ID value.
- Download the certificate.
- Select Continue.
- In the Service Provider Details page, configure each field with the following values:
- ACS URL: Use the Assertion Consumer Service (ACS) URL provided in the Checkout.com Dashboard.
- Entity ID: Use the SP Entity ID provided from the Checkout.com Dashboard.
- Start URL:
- Live:
https://dashboard.checkout.com - Test:
https://dashboard.sandbox.checkout.com
- Live:
- Select Continue.
- Under the Attributes Mapping section, set the mandatory attribute statements as shown in the following table:
| Google Directory Attribute | App Attribute | Description |
|---|---|---|
|
| The user's first name |
|
| The user's last name |
|
| The user's email address |
The custom user attribute that you created (if any) For example, |
| The user's info to map to Dashboard entities |
- Under the Group Membership section, configure the Google groups you want to map to a Dashboard role:
| Google groups | App Attribute | Description |
|---|---|---|
The list of groups you created to map to a Dashboard role |
| The complete list of Google groups that will be used for Role mapping in the Dashboard. When a user logs in, Google sends the groups the user is associated with so that we can use this list as a filter for the roles assigned. |
- Select Finish.
Information
You may need to allow users in your organization access to the new SAML application you created
- Log in to the Dashboard environment to which you want to configure SSO:
- Go to Settings > Single Sign-on.
Information
You need the Entity ID and SSO URL provided by Google in the Google Identity Provider Details page.
To review this information:
- Log in to Google Cloud.
- Navigate to Service Provider details > Manage Certificates > Google Identity Provider details.
In the Configure Metadata section, provide the required SAML application metadata:
- Use the
Entity IDprovided by Google in the Identity provider issuer field. - Use the
SSO URLprovided by Google in the Identity provider single sign-on field. - Upload the application certificate you downloaded from Google when creating your SAML application.
To allow your users to use SSO from the Dashboard sign in page, you must add your email domains. This step enables the Dashboard to redirect your users to your IdP as long as you enable this feature.
Your email domain is the portion of your corporate email address after the @ character. For example, for a user email [email protected], the domain is checkout.com. Domains can only be claimed by a single Checkout.com account.
Information
You cannot claim generic email provider domains, such as gmail.com or hotmail.co.uk.
Under the Add domains section, add all of the corporate email domains your users will use when authenticating with SSO. If the domain has already been claimed by another Checkout.com account, you will receive an error message. Contact [email protected] if you encounter any issues.
For each domain that you inform:
- Access your domain name server (DNS).
- Create a text (
TXT) record for the given domain, with the provided verification token you see in the Dashboard. If you do not have the necessary permissions, you may need to coordinate with your organization’s IT administrator to update your DNS.
To map the idpGroups attribute:
- Navigate to Map roles.
- Under SAML value type the Google group name that you created for your IAM admin role. For example,
checkout_iam_admin. - Under Checkout.com Dashboard role, select the IAM Admin role to which you want to map this group.
If you choose to create other Google groups to map to other roles, add them using the Add role mapping button.
To access the Dashboard, each user must be assigned a valid role that matches those available from the Dashboard.
After adding all your mappings, select Continue.
The process for updating DNS entries varies by vendor. In most cases, records are updated and domains can be verified immediately, but in some cases it may take up to 72 hours for the required DNS changes to become effective.
In case your domains are not yet validated by the Dashboard, you can trigger the validation process:
- Navigate to Settings > Single Sign-on.
- Select Verify domains.
Checkout.com will check that the TXT record is part of the DNS record. If the domain status changes to Verified, your verification was successful. If verification fails, you can use a DNS lookup tool to review your DNS record.
Note
If you opt out of entity-level access controls, all of your users will have access to all of the entities and segments on your Checkout.com account.
If you send a Google user custom attribute using the idpEntities SAML attribute, you must map those custom values to a combination of actual entities and segments in your Dashboard. For example, UK-Cake-Shop-All-Segments to the UK Entity The Cake Shop entity and all its associated segments.
- Under Edit entity mapping, enable the Limit user access to assigned entities flag.
- Select Limit user access to assigned entities and entity segments.
- Select Add entity mapping.
- Navigate to SAML Value.
- Type one of the values you assigned to your Google users via the custom attribute you created. For example,
UK-Cake-Shop-All-Segments. - Select Assign access and choose one of the following options, depending on the level of access you want to provide:
- to grant access to all segments of an entity, select Access to all entity data
- to grant access to selected segments, select the specific segments to which you want to give access
You must map all possible values you assign users to with the actual entities in the Dashboard. Otherwise, our platform will not be able to identify which entity a user has access to.
After you've added all of the mappings, select Save.
When you've successfully verified your email domains, you can enable IdP-initiated SSO from the Dashboard:
- Navigate to Settings > Single Sign-on.
- Under Identity provider initiated sign in, select Enable.
Before you activate SSO for your entire organization, you should test the connection by signing in to the Dashboard using Google credentials:
- Sign out of the Dashboard.
- Sign in to Google Cloud.
- In Google, check that your user account has been assigned all required attributes. You must have the Owner or IAM Admin role assigned to continue setting up SSO.
- Sign in to the Dashboard using the SAML application you created in Google. Use the option Test SAML Login.
Service provider-initiated SSO will not work at this stage, it's not yet enabled. - If your user was authenticated successfully, you see the Dashboard home page.
- Navigate to Settings > Single Sign-on and select Review SAML attributes.
- Review the attributes returned within the Dashboard to ensure they match the expected values. If the attributes do not match, return to the SSO configuration page within the Dashboard to edit the values.
- If the SAML attribute values are correct, select Looks good to finalize the test and enable additional SSO configuration options.
After you successfully accessed the Dashboard via SSO and reviewed your SAML attributes, you can enable service provider-initiated sign in from the Settings > Single Sign-on screen. This allows your users to use SSO from the Dashboard sign in page, and disables all non-SSO access to your account.
From this stage onwards, all user management will be delegated to Google.
Once you’ve verified your first domain, you can choose to enable the sign in routing rule.
This option routes users with verified domains to SSO on the Dashboard sign in page and automatically blocks all other sign in attempts. Routing can be disabled at any time.
To test that routing is working as expected, go to the Dashboard and:
- Select either the Live or Test environment.
- Enter your SSO email address, ensuring it matches with a verified domain, and select Next.
If routing was enabled successfully, you will first be redirected to your IdP login, and then to the Dashboard once authenticated.
When SSO routing is enabled, SSO sign-in enforcement is automatically enabled by default. This requires any users signing in to the Dashboard to sign in via SSO.
To allow users with non-verified email domains to sign in to the Dashboard, you can disable SSO enforcement from the Settings > Single Sign-on screen.
Note
To ensure maximum account security, we strongly suggest keeping SSO sign-in enforcement enabled and managing all users through your identity provider.
For security purposes, and to ensure that you remain in control of your Checkout.com account, you must contact your Account Manager or [email protected] in order to permanently disable SSO.