# Enable single sign-on with Google
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 Admin, 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:
- Have the Account owner or IAM admin [user role](https://www.checkout.com/docs/business-operations/use-the-dashboard/manage-users/user-permissions.md) 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:
1. [Initiate SSO configuration in the Dashboard](#Initiate_SSO_configuration_in_the_Dashboard)
2. [Configure SSO in Google Cloud](#Configure_SSO_in_Google_Cloud)
- [Create a Google group](#Create_a_Google_group)
- [(Optional) Create Google User Attribute to map to Dashboard entities](#Create_Google_User_Attribute_to_map_to_Dashboard_entities_)
- [Create a SAML application](#Create_a_SAML_application)
3. [Continue the SSO configuration in the Dashboard](#Continue_the_SSO_configuration_in_the_Dashboard)
- [Configure domains](#Configure_domains)
- [Configure metadata](#Configure_metadata)
- [Map roles to Google groups](#Map_roles_to_Google_groups)
4. [Finish SSO configuration in the Dashboard](#Finish_SSO_configuration_in_the_Dashboard)
- [Verify email domains](#Verify_email_domains)
- [(Optional) Map entities](#Map_entities)
- [Enable identity provider initiated sign in](#Enable_identity_provider-initiated_sign_in)
- [Review SAML attributes](#Review_SAML_attributes)
- [Enable SSO routing](#Enable_SSO_routing)
---
## Initiate SSO configuration in the Dashboard
1. Sign in to the Dashboard environment for which you want to configure SSO:
- [Live](https://dashboard.checkout.com)
- [Test](https://dashboard.sandbox.checkout.com)
2. Select the _Settings menu_ in the top navigation bar, and then select _Settings_.
3. Under _Team settings_, select _Single sign-on_.
4. Select _Google Cloud IDP_ from the list of identity providers.
5. Select _Start Configuration_.
6. 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.
---
## Configure SSO in Google Cloud
You must perform the following configuration in your Google Cloud environment.
### Create a Google group
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](https://www.checkout.com/docs/business-operations/use-the-dashboard/manage-users/user-permissions.md) in your Dashboard.
1. Sign in to your Google Admin Console for your Workspace account.
2. Create a Google group and name it with a representative name. For example, `checkout_iam_admin`.
3. 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](https://www.checkout.com/docs/business-operations/use-the-dashboard/manage-users/user-permissions.md#Custom_roles). That role is then assigned to every member of the group.
### Create Google User Attribute to map to Dashboard entities `Optional`
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:
1. Navigate to _Directory > Users_.
2. Select _More options > Manage custom attributes_.
3. Select _Add Custom Attribute_.
4. In _Category_, enter a name for the category you want to add.
5. Under _Custom fields_, configure the name of your custom attribute. For example, _CKO-Entities_.
6. 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.
---
### Create a SAML application
1. In Google, navigate to _Apps > Web and mobile apps_.
2. Select _Add app > Add custom SAML app_.
3. 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_.
4. Select _Continue_.
5. In the Google _Identity Providers Details_ page:
1. Save the _SSO URL_ value.
2. Save the _Entity ID_ value.
3. Download the certificate.
6. Select _Continue_.
7. In the _Service Provider Details_ page, configure each field with the following values:
1. _ACS URL_: Use the _Assertion Consumer Service (ACS) URL_ provided in the Checkout.com Dashboard.
2. _Entity ID_: Use the _SP Entity ID_ provided from the Checkout.com Dashboard.
3. _Start URL_:
- Live: `https://dashboard.checkout.com`
- Test: `https://dashboard.sandbox.checkout.com`
8. Select _Continue_.
9. Under the _Attributes Mapping_ section, set the required attribute statements as shown in the following table:
| Google Directory Attribute | App Attribute | Description |
| --- | --- | --- |
| `First name` | `firstName` | The user's first name |
| `Last name` | `lastName` | The user's last name |
| `Primary email` | `email` | The user's email address |
| The custom user attribute that you created (if any)
For example, `CKO-Entities` | `idpEntities` | The user's info to map to Dashboard entities |
10. 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 | `idpGroups` | 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. |
11. Select _Finish_.
> **Information**
>
> You may need to allow users in your organization access to the new SAML application you created
---
## Continue the SSO configuration in the Dashboard
1. Sign in to the Dashboard environment to which you want to configure SSO:
- [Live](https://dashboard.checkout.com)
- [Test](https://dashboard.sandbox.checkout.com)
2. Select the _Settings menu_ in the top navigation bar, and then select _Settings_.
3. Under _Team settings_, select _Single sign-on_.
### Configure domains
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 `person@example.com`, the domain is `example.com`. A domain can be registered by more than one Checkout.com account. Each account must verify ownership of the domain through its own DNS check.
> **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 use when authenticating with SSO. If you encounter any issues, you can [request support](https://dashboard.checkout.com/support/new?topic=case_access&issue=case_access_issue_sso).
For each domain that you inform:
1. Access your domain name server (DNS).
2. 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.
### Configure metadata
> **Information**
>
> You need the _Entity ID_ and _SSO URL_ provided by Google in the _Google Identity Provider Details_ page.
>
> To review this information:
> 1. Log in to Google Cloud.
> 2. Navigate to _Service Provider details > Manage Certificates > Google Identity Provider details_.
In the _Configure Metadata_ section, provide the required SAML application metadata:
1. Use the `Entity ID` provided by Google in the _Identity provider issuer_ field.
2. Use the `SSO URL` provided by Google in the _Identity provider single sign-on_ field.
3. Upload the application certificate you downloaded from Google when creating your SAML application.
### Map roles to Google groups
To map the `idpGroups` attribute:
1. Navigate to _Map roles_.
2. Under _SAML value_ type the Google group name that you created for your IAM admin role. For example, `checkout_iam_admin`.
3. 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_.
---
## Finish SSO configuration in the Dashboard
### Verify email domains
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:
1. Sign in to the [Dashboard](https://dashboard.checkout.com).
2. Select the _Settings menu_ in the top navigation bar, and then select _Settings_.
3. Under _Team settings_, select _Single sign-on_.
4. 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.
### Map entities `Optional`
> **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.
1. Under _Edit entity mapping_, enable the _Limit user access to assigned entities_ flag.
2. Select _Limit user access to assigned entities and entity segments_.
3. Select _Add entity mapping_.
4. Navigate to _SAML Value_.
5. Type one of the values you assigned to your Google users via the custom attribute you created. For example, `UK-Cake-Shop-All-Segments`.
6. 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_.
### Enable identity provider-initiated sign in
When you've successfully verified your email domains, you can enable IdP-initiated SSO:
1. Sign in to the [Dashboard](https://dashboard.checkout.com).
2. Select the _Settings menu_ in the top navigation bar, and then select _Settings_.
3. Under _Team settings_, select _Single sign-on_.
4. Under _Identity provider initiated sign in_, select _Enable_.
### Review SAML attributes
Before you activate SSO for your entire organization, you should test the connection by signing in to the Dashboard using Google credentials:
1. Sign out of the Dashboard.
2. Sign in to Google Cloud.
3. In Google, check that your user account has been assigned all required attributes. You must have the Account owner or IAM Admin role assigned to continue setting up SSO.
4. 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.
5. If your user was authenticated successfully, you see the Dashboard home page.
2. Select the _Settings menu_ in the top navigation bar, and then select _Settings_.
7. Under _Team settings_, select _Single sign-on_.
8. Select _Review SAML attributes_.
9. 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.
10. If the SAML attribute values are correct, select _Looks good_ to finalize the test and enable additional SSO configuration options.
### Enable SSO routing
After you successfully accessed the Dashboard via SSO and reviewed your SAML attributes, you can enable service provider-initiated sign in:
1. Sign in to the [Dashboard](https://dashboard.checkout.com).
2. Select the _Settings menu_ in the top navigation bar, and then select _Settings_.
3. Under _Team settings_, select _Single sign-on_.
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. If a domain is linked to more than one IdP, users select their provider before they authenticate. Routing can be disabled at any time.
To test that routing is working as expected, go to the Dashboard and:
1. Select either the _Live_ or _Test_ environment.
2. 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.
#### SSO sign-in enforcement
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_:
1. Sign in to the [Dashboard](https://dashboard.checkout.com).
2. Select the _Settings menu_ in the top navigation bar, and then select _Settings_.
3. Under _Team settings_, select _Single sign-on_.
> **Note**
>
> To ensure maximum account security, we strongly suggest keeping SSO sign-in enforcement enabled and managing all users through your identity provider.
---
## Disable SSO
For security purposes, and to ensure that you remain in control of your Checkout.com account, you must contact your account manager or [request support](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes) to permanently disable SSO.