Enable single sign-on with Okta
Last updated: May 31, 2023
You can configure single sign-on (SSO) with Checkout.com to authenticate users on the Dashboard with Okta.
With SSO enabled, your users can sign in to the Dashboard from Okta (identity provider-initiated sign in), or from the Dashboard sign in page (service provider-initiated sign in).
To enable SSO, you must:
- be assigned the Owner or IAM Admin role 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:
- Initiate an SSO connection.
- Create a SAML application.
- Configure your SSO connection in the Dashboard.
- Verify email domains.
- Enable identity provider initiated sign in.
- Review SAML attributes.
- Enable SSO routing.
To initiate your setup, sign in to the Dashboard and:
- Go to Settings > Single Sign-on.
- Select Okta 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 Okta.
Sign in to Okta 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.
- If you're configuring SSO for the live environment, set https://dashboard.checkout.com as the Default Relay State. If you're configuring SSO for the test environment, use https://dashboard.sandbox.checkout.com instead.
- Set the mandatory attribute statements as shown in the following table:
| Attribute name | Attribute value | Description |
|---|---|---|
|
| 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.
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:
- 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.
Head back to the Dashboard and go to Team > Single Sign On to continue your setup.
In the Configure Metadata section, provide the required SAML application metadata in the fields:
- Identity Provider Issuer
- Identity Provider Single Sign-on URL
- 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.
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 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 idpEntities and idpGroups attributes when you created your SAML application, add these under Group Attribute Statements.
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.
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.
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.
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.
To do so from the Dashboard:
- Go to Team > Single Sign-on.
- Under Domains, select Manage domains.
- 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 Okta.
To test IdP-initiated SSO:
- In Okta, 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 Okta. 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 Okta, 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 Okta.
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. 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.
Note
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.