You're viewing documentation for our latest API. This will not impact your integration, but you will need the documentation relevant to you. If you have an account with Checkout.com you have received an email confirming which version to use.
Select Google from the list of identity providers.
Select Start Configuration.
Make a note of the Assertion Consumer Service (ACS) URL and Service Provider Entity ID values provided here. You’ll be prompted for these when you create your SAML application in Google.
Sign in to Google to create a new SAML application. Each SAML application you create is only valid for a single Checkout.com account.
If you plan on enabling SSO with both live and test Dashboard environments, we recommend you give each SAML application a unique and recognizable name. For example, Checkout.com Test and Checkout.com Live.
Populate the Single sign-on URL field with the Assertion Consumer Service (ACS) URL value provided in the Dashboard.
Populate the Audience URI (SP Entity ID) field with the Service Provider Entity ID value provided in the Dashboard.
Set the mandatory attribute statements as shown in the following table:
The user's first name.
The user's last name.
The user's email address.
You must configure the idpGroups attribute statement before any user can sign in via your IdP:
Create a new group with a unique and identifiable name. For example, CKO Role IAM Admin.
Map the group to a preset or custom role from the Dashboard. The role must have the security:manage permission assigned in the Dashboard. For example, you can map the CKO Role IAM Admin group to the IAM Admin role from the Dashboard.
Assign the group to your user. You'll need to be assigned to a group with the security:manage permission to complete the SSO setup.
Create a filter for the group. For example, you can set a filter for all groups that contain CKO Role in their name.
Create any additional groups you require. To simplify group filtering, we recommend following a pattern when naming your groups. For example, CKO Role Disputes Manager and CKO Role Developer.
Map the groups to roles from the Dashboard.
If you skip the idpGroups configuration, you will not be able to complete the 'Review SAML attributes' section of this guide.
You can also configure the idpEntities attribute statement if you plan to limit user access to specific entities:
Create a new group with a unique and identifiable name. For example, CKO Entity The Cake Shop.
Map the group to an entity from the Dashboard. For example, you can map the CKO Entity The Cake Shop group to the The Cake Shop entity from the Dashboard.
Assign the group to the users that require access.
Create a filter for the group. For example, you can set a filter for all groups that contain CKO Entity in their name.
Create any additional groups you require. To simplify filtering, we recommend following a pattern when naming your groups. For example, CKO Entity The Cake Shop and CKO Entity The Donut Shop.
Map the groups to entities from the Dashboard.
Once you’ve created your SAML application, export your application certificate as a CRT, CER, CERT, or PEM file. You’ll need to upload this to the Dashboard at a later step.
In your Google Workspace SSO portal, make a note of your SSO URL and Entity ID values.
Then, to continue your setup, head back to the Dashboard and go to Team > Single Sign On .
In the Configure Metadata section, provide the required SAML application metadata in the fields:
Identity Provider Issuer URL, also referred to as an Entity ID
Identity Provider Single Sign-on URL, also referred to as an Identity Provider URL or SAML Endpoint
Upload the application certificate
To allow your users to use SSO from the Dashboard sign in page, you must add your email domains.
Your email domain is the portion of your corporate email address after the @. For example, for a user email [email protected], the domain is checkout.com. Domains can only be claimed by a single Checkout.com account.
You cannot claim generic email provider domains, such as gmail.com or hotmail.co.uk.
In 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. Reach out to [email protected] if you have any issues.
Provide SAML attribute values for each Checkout.com entity in the available fields.
To give users access to specific entities, you must map the entities available within the Dashboard to the corresponding SAML attribute values that you will later assign to your users.
If you set an idpEntities attribute when you created your SAML application:
Navigate to Directory > Users.
Select More options > Manage custom attributes.
Select the ADD CUSTOM ATTRIBUTE option to create an Entities attribute.
Set the No. of values option to Multi-value.
Add the attribute to your application's SAML attribute mapping with the app attribute name idpEntities.
To map the idpGroups attribute:
Navigate to Group membership.
Add the necessary groups.
Set App attribute to idpGroups.
If you opt out of entity-level access controls, all of your users will have access to all of the entities on your Checkout.com account.
To assign roles within your IdP, you must map the SAML attribute values that will be assigned to your users to the roles from the Dashboard.
In the configuration, provide these SAML attribute values for each Checkout.com role you intend to assign to your users.
To access the Dashboard, each user must be assigned a valid role that matches those available from the Dashboard.
Once you've filled out all required fields, select Continue.
To allow your users to use SSO from the Dashboard sign in screen, you must verify the email domains you added in a previous step.
Create a text (TXT) record in your domain name server (DNS), with the provided domain verification token. If you don't have the necessary permissions, you may need to coordinate with your organization’s IT administrator to update your DNS.
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.
Once your DNS changes are active, head back to the Dashboard and:
Go to Team > 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.
When you've successfully verified your email domains, you can enable IdP-initiated SSO from the Dashboard:
Go to Team > 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 via Google.
To test IdP-initiated SSO:
In Google, check that your user account has been assigned all required attributes. Your user will need to have the Owner or IAM Admin role assigned to continue setting up SSO.
Sign in to the Dashboard, using the SAML application within Google. Service provider-initiated SSO will not work at this stage.
If your user was authenticated successfully, go to Team > Single Sign-on and select Review SAML attributes. If you are unable to access the Dashboard through Google, you can sign in with your existing email and password combination.
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.
Once you have successfully accessed the Dashboard via SSO and reviewed your SAML attributes, you can enable service provider-initiated sign in from the Team > 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 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 Team > Single sign-on screen.
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.