Enable single sign-on with Okta
Last updated: November 28, 2024
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 administrator, you can also leverage your identity provider to manage all of your user accounts in one central location.
To enable SSO, you must:
- Be assigned the Owner or IAM Admin role 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.
- Initiate SSO configuration in the Dashboard.
- Configure SSO in Okta.
- Continue the SSO configuration in the Dashboard.
- Finish SSO configuration in the Dashboard.
- Sign in to the Dashboard environment you want to configure SSO for:
- Select the Settings icon in the top navigation bar and open the Single sign on tab.
- Select Okta 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
You must perform the following configuration in your Okta environment.
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 in your Dashboard.
- Sign in to the Okta Admin Console for your Workspace account.
- Create an Okta group and give it a name that will help you identify it. For example,
checkout_iam_admin. - 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. This assigns every member of the Okta group with the specified Dashboard role.
- In Okta, go to Applications and select Create App Integrations.
- Provide a unique and identifiable name for your SAML app and choose the visibility settings for your users.
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. - Select Next.
- 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
- Live:
- Under the Attributes Statements(Optional) section, set the mandatory attribute statements as shown in the following table:
| Attribute Statement | Attribute value |
|---|---|
|
|
|
|
|
|
Although Okta labels these fields as "optional", these fields are mandatory for the Checkout.com process.
- In the Group Attribute Statements (Optional) section, configure the
idpGroupsoridpEntitiesyou want to map to a Dashboard role:
| Group Attribute Statement | Filter |
|---|---|
| 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. |
| 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. |
- Select Finish.
- Export the SAML application certificate as a
CRT,CER,CERT, orPEMfile. You'll upload this to the Dashboard in a later step.
- Sign in to the same Dashboard environment you've been following the previous steps in:
- Select the Settings icon in the top navigation bar and open the Single sign on tab.
You must retrieve the Entity ID and SSO URL provided by Okta in the Okta Identity Provider Details page:
- Sign in to Okta.
- Go to Applications.
- Select the SAML Application you created in the previous steps.
- Go to Sign-on > Metadata details > More details.
In the Configure Metadata section, provide the required SAML application metadata:
- Enter the
Issuerprovided by Okta in the Identity provider issuer field. - Enter the
SSO URLprovided by Okta in the Identity provider single sign-on field. - Upload the application certificate you downloaded from Okta when you created 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 to authenticate with SSO. If the domain has already been claimed by another Checkout.com account, you'll receive an error message.
Note
If you encounter issues, contact [email protected].
For each domain that you inform:
- Access your domain name server (DNS).
- 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.
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.
- Go to SAML Value.
- 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.
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:
- Sign in to the same Dashboard environment you've been following the previous steps in:
- Select the Settings icon in the top navigation bar and open the Single sign on tab.
- 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:
- Sign in to the same Dashboard environment you've been following the previous steps in:
- Select the Settings icon in the top navigation bar and open the Single sign on tab.
- 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 Okta credentials:
- Sign out from the Dashboard.
- Sign in to Okta.
- In Okta, check that your user account has been assigned all required attributes. You must have the Owner or IAM Admin role assigned to continue with the SSO setup.
- Sign in to the Dashboard using the SAML application you created in Okta. Use the option Test SAML Login.
Service provider-initiated SSO will not work at this stage as it has not been enabled yet. - If your user was authenticated successfully, you will be redirected to the Dashboard home page.
- Select the Settings icon in the top navigation bar and open the Single sign on tab.
- Select Review SAML attributes.
- 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.
- If the SAML attribute values are correct, select Looks good to finalize the test and enable additional SSO configuration options.
After you successfully access the Dashboard via SSO and review your SAML attributes:
Sign in to the same Dashboard environment you've been following the previous steps in:
Select the Settings icon in the top navigation bar and open the Single sign on tab.
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 in 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:
- Sign in to the same Dashboard environment you've been following the previous steps in:
- Enter your SSO email address. It must match a verified domain.
- 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.
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:
- Sign in to the same Dashboard environment you've been following the previous steps in:
- Select the Settings icon in the top navigation bar and open the Single sign on tab.
- 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.
To permanently disable SSO in your account, you must contact your Account Manager or [email protected].
This allows us to maintain security and ensure that you remain in control of your Checkout.com account.