# Enable single sign-on with Azure

You can configure single sign-on (SSO) with Checkout.com to authenticate users on the Dashboard with Azure Active Directory (AD).

With SSO enabled, your users can sign in to the Dashboard from Azure (identity provider-initiated sign in), or from the Dashboard sign-in page (service provider-initiated sign in).

To enable SSO, you must:

- 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 identity provider (IdP), granting you the ability to set up a SAML connection.
- Be able to update your domain host’s DNS record for domain verification, or have access to someone who can.

You’ll need to create separate SAML applications to enable SSO for the live and test Dashboard environments.

To enable SSO, you'll need to:

1. [Initiate an SSO connection](#Initiate_an_SSO_connection).
2. [Create a SAML application](#Create_a_SAML_application).
3. [Configure your SSO connection in the Dashboard](#Configure_your_SSO_connection).
4. [Verify email domains](#Verify_email_domains).
5. [Enable identity provider initiated sign in](#Enable_identity_provider_initiated_sign_in).
6. [Review SAML attributes](#Review_SAML_attributes).
7. [Enable SSO routing](#Enable_SSO_routing).

---

## Initiate an SSO connection

To initiate your setup:

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 _Azure_ from the list of identity providers.
5. Select _Start Configuration_.
6. Make a note of the _Assertion Consumer Service (ACS) URL_ and _Service Provider Entity ID_ values provided. You’ll be prompted for these when you create your SAML application in Azure.

---

## Create a SAML application

Sign in to Azure 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_.

### Configure attribute statements

1. Populate the _Single sign-on URL_ field with the _Assertion Consumer Service (ACS) URL_ value provided in the Dashboard.
2. Populate the _Audience URI (SP Entity ID)_ field with the _Service Provider Entity ID_ value provided in the Dashboard.
3. If you're configuring SSO for the production environment, set https://dashboard.checkout.com as the _Default Relay State_. If you're configuring SSO for the sandbox environment, use https://dashboard.sandbox.checkout.com instead.
4. Set the required attribute statements as shown in the following table:

| Attribute name | Attribute value | Description |
| --- | --- | --- |
| `firstName` | `user.firstName` | The user's first name. |
| `lastName` | `user.lastName` | The user's last name. |
| `email` | `user.email` | The user's email address. |

### Configure group attribute statements

You must configure the `idpGroups` attribute statement before any user can sign in via your IdP:

1. Create a new group with a unique and identifiable name. For example, _CKO Role IAM Admin_.
2. Map the group to a preset or custom role from the Dashboard. The role must have the `Manage team security settings including single sign-on` permission assigned in the Dashboard. For example, you can map the _CKO Role IAM Admin_ group to the IAM Admin role from the Dashboard.
3. Assign the group to your user. You need to be assigned to a group with the `Manage team security settings including single sign-on` permission to complete the SSO setup.
4. Create a filter for the group. For example, you can set a filter for all groups that contain _CKO Role_ in their name.
5. 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_.
6. Map the groups to roles from the Dashboard.

> **Note**
>
> 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:

1. Create a new group with a unique and identifiable name. For example, _CKO Entity The Cake Shop_.
2. 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.
3. Assign the group to the users that require access.
4. Create a filter for the group. For example, you can set a filter for all groups that contain _CKO Entity_ in their name.
5. 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_.
6. 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.

---

## Configure your SSO connection

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_.

### Add email domains

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 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.

In the _Add domains_ section, add all of the corporate email domains your users use when authenticating with SSO. If you have any issues, you can [request support](https://dashboard.checkout.com/support/new?topic=case_access&issue=case_access_issue_sso).

### Configure metadata

In the _Configure Metadata_ section, provide the required SAML application metadata in the fields:

- Azure AD Identifier
- Login URL
- Upload the application certificate

### Map entities

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.

> **Note**
>
> 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.

### Map groups

To map the `idpGroups` attribute:

1. Add a group claim and select _Groups assigned to the application_.
2. Set _Source Attribute_ to _Cloud-only group display names (Preview)_ to omit the group name in SAML assertions.
3. If the previous option is not available, set _Source Attribute_ to _Group ID_ instead to omit the group ID.
4. Under _Advanced options_, change the name of the group claim to `idpGroups`.

### Map roles

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](https://www.checkout.com/docs/dashboard/team-permissions.md) you intend to assign to your users.

> **Note**
>
> 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_.

---

## Verify email domains

To allow your users to use SSO from the Dashboard sign-in page, you must verify the email domains you added in a previous step.

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 _Domains_, select _Manage domains_.
5. Create a text (TXT) record in your domain name server (DNS), with the provided domain verification token. If you do not 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:

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.

---

## 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 via Azure.

To test IdP-initiated SSO:

1. In Azure, check that your user account has been assigned all required attributes. Your user will need to have the Account owner or IAM Admin role assigned to continue setting up SSO.
2. Sign in to the Dashboard, using the SAML application within Azure. Service provider-initiated SSO will not work at this stage.
3. If your user was authenticated successfully, select the _Settings menu_ in the top navigation bar, and then select _Settings_.
4. Under _Team settings_, select _Single sign-on_.
5. Select _Review SAML attributes_. If you are unable to access the Dashboard through Azure, you can sign in with your existing email and password combination.
6. 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.
7. 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:

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 Azure.

---

## Enable SSO routing

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 sign in via SSO from 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](https://dashboard.checkout.com) and:

1. Select either the _Live_ or _Test_ environment.
2. 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.

### 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.