# Enable single sign-on with Okta

You can configure single sign-on (SSO) with Checkout.com to authenticate users in the Dashboard with Okta.

With SSO enabled, your users can sign in to the Dashboard from:

- Okta (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 of your user accounts in one central location.

To enable SSO, you must:

- Have the Account owner or IAM admin [user role](https://www.checkout.com/docs/dashboard/team-permissions.md#Pre-defined_roles) in the Dashboard
- Have administrative privileges with your Okta account. You need this to create a Security Assertion Markup Language (SAML) application on your organization's end, which enables you to configure Okta as your external identity provider (IdP)
- Have permissions to update your domain host's DNS record for domain verification yourself, or have access to someone who does

> **Information**
>
> The Live and Test Dashboard environments require separate SAML applications. You must perform the following steps for each environment you want to configure SSO for.

1. [Initiate SSO configuration in the Dashboard](#Initiate_SSO_configuration_in_the_Dashboard).
2. [Configure SSO in Okta](#Configure_SSO_in_Okta).
    - [Create an Okta group](#Create_an_Okta_group).
    - [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).
    - [(Optional) Map entities](#Map_entities).
4. [Finish SSO configuration in the Dashboard](#Finish_SSO_configuration_in_the_Dashboard).
    - [Verify email domains](#Verify_email_domains).
    - [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 you want to configure SSO for:
    - [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 _Okta_ 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_

---

## Configure SSO in Okta

You must perform the following configuration in your Okta environment.

### Create an Okta group

Before you configure your Okta account as an IdP, you must create a user group in Okta 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 the Okta Admin Console for your Workspace account.
2. Create an Okta group and give it a name that will help you identify it. For example, `checkout_iam_admin`.
3. Assign a user to the group. You will use this user's credentials to sign in to the Dashboard and validate your SSO configuration.

You can create multiple Okta groups to represent different roles in your Dashboard. For example, _checkout_iam_admin_, or _checkout_support_manager_.

When you configure your SSO connection with Checkout.com, you can map your Okta 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).

### Create a SAML application

1. In Okta, go to _Applications_ and select _Create App Integrations_.
2. Provide a unique and identifiable name for your SAML app and choose the visibility settings for your users. <br>
Each SAML application you create is only valid for a single Checkout.com environment. 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_.
3. Select _Next_.
4. Populate the fields with following values:
    - _Single sign-on URL_ : Use the _Assertion Consumer Service (ACS) URL_ value provided in the Dashboard
    - _Audience URI(SP Entity ID)_ : use the _Service Provider Entity ID_ value provided in the Dashboard
    - _Default Relay State_:
      - Live: `https://dashboard.checkout.com`
      - Test: `https://dashboard.sandbox.checkout.com`
5. Under the _Attributes Statements(Optional)_ section, set the required attribute statements as shown in the following table:

| Attribute Statement | Attribute value |
| --- | --- |
| `firstName` | `user.firstName` |
| `lastName` | `user.lastName` |
| `email` | `user.email` |

Although Okta labels these fields as optional, they are required for the Checkout.com process.

6. In the _Group Attribute Statements (Optional)_ section, configure the `idpGroups` or `idpEntities` you want to map to a Dashboard role:

| Group Attribute Statement | Filter |
| --- | --- |
| `idpGroups` | Create a filter for the group. For example, you can set a filter for all groups that contain _CKO Role_ in their name. To simplify group filtering, we recommend you follow a pattern when you name your groups. For example, _CKO Role Disputes Manager_ and _CKO Role Developer_. |
| `idpEntities` | Create a filter for the group. For example, you can set a filter for all groups that contain _CKO Entity_ in their name. To simplify filtering, we recommend you follow a pattern when you name your groups. For example, _CKO Entity The Cake Shop_ and _CKO Entity The Donut Shop_. |

7. Select _Finish_.
8. Export the SAML application certificate as a `CRT`, `CER`, `CERT`, or `PEM` file. You'll upload this to the Dashboard in a later step.

---

## Continue the SSO configuration in the Dashboard

1. Sign in to the same Dashboard environment you've been following the previous steps in:
    - [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 will use to authenticate with SSO.

> **Note**
>
> If you encounter 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 verification token provided 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

You must retrieve the _Entity ID_ and _SSO URL_ provided by Okta in the _Okta Identity Provider Details_ page:

1. Sign in to Okta.
2. Go to _Applications_.
3. Select the SAML Application you created in the previous steps.
4. Go to _Sign-on_ > _Metadata details_ > _More details_.

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

1. Enter the `Issuer` provided by Okta in the _Identity provider issuer_ field.
2. Enter the `SSO URL` provided by Okta in the _Identity provider single sign-on_ field.
3. Upload the application certificate you downloaded from Okta when you created your SAML application.

### 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 an Okta user 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, you would map `UK-Cake-Shop-All-Segments` to the _UK Entity The Cake Shop_ entity and all of its associated segments.

1. Go to _SAML Value_.
2. Under _Checkout.com Dashboard entity_, select the entity you want to map the SAML attribute value to.

You must map all possible values you assign users to with the actual entities in the Dashboard. If you do not, our platform will not be able to identify which entity a user has access to.

Once you've mapped all of the SAML attributes, select _Save_.

---

## Finish SSO configuration in the Dashboard

### Verify email domains

The process to update DNS entries varies by vendor.

Some vendors update their records immediately and domains can be verified almost instantly. For other vendors, it may take up to 72 hours for the required DNS changes to be reflected.

If your domains are not yet validated by the Dashboard, you can trigger the validation process:

1. Sign in to the same Dashboard environment you've been following the previous steps in:
    - [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 _Verify domains_. <br>
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 from the Dashboard:

1. Sign in to the same Dashboard environment you've been following the previous steps in:
    - [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. 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 Okta credentials:

1. Sign out from the Dashboard.
2. Sign in to Okta.
3. In Okta, check that your user account has been assigned all required attributes. You must have the Account owner or IAM Admin role assigned to continue with the SSO setup.
4. Sign in to the Dashboard using the SAML application you created in Okta. Use the option _Test SAML Login_. <br>
Service provider-initiated SSO will not work at this stage as it has not been enabled yet.
5. If your user was authenticated successfully, you will be redirected to the Dashboard home page.
6. 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 in the Dashboard to ensure they match the expected values. If the attributes do not match, return to the SSO configuration page in 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 access the Dashboard via SSO and review your SAML attributes:

1. Sign in to the same Dashboard environment you've been following the previous steps in:
    - [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. Enable service provider-initiated sign in.

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

After you verify your first domain, you can 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:

1. Sign in to the same Dashboard environment you've been following the previous steps in:
    - [Live](https://dashboard.checkout.com)
    - [Test](https://dashboard.sandbox.checkout.com)
2. Enter your SSO email address. It must match a verified domain.
3. Select _Next_.

If you enabled routing successfully, you will be redirected to your identity provider to sign in.

Once your user is authenticated, you will be redirected to the Dashboard.

#### SSO sign-in enforcement

When you enable SSO routing, 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:

1. Sign in to the same Dashboard environment you've been following the previous steps in:
    - [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. Disable _SSO enforcement_.

> **Note**
>
> To maintain the security of your account, we strongly recommend you manage your users through your identity provider and do not disable SSO sign-in enforcement.

---

## Disable SSO

To permanently disable SSO in your 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).

This allows us to maintain security and ensure that you remain in control of your Checkout.com account.