SSO for CommCare HQ is only available on our CommCare Enterprise Software Plan. You need to contact your Accounting Administrator to set up Okta as an Identity Provider for your account.

You can configure SSO for Okta in the Enterprise Console. The first step is to create your CommCare HQ Application in Okta. After creating the Okta Application, you can configure SSO for Okta in the Enterprise Console. You need to be an Enterprise Admin to be able to do this.

1 In CommCare HQ
- 1.1 Edit Identity Provider
2 In Okta
- 2.1 Create your Application in Okta
- 2.2 Configure SSO in Okta
3 Configure SSO in CommCare HQ
- 3.1 SSO Test Users tab
4 Sign In with Okta SSO
- 4.1 New Users

In CommCare HQ

Edit Identity Provider

You can access Identity Provider settings in the Enterprise Console.

1. In your Project Space, navigate to the Enterprise Console.

2. Navigate to the Manage Single Sign-On page in the side menu.

3. Choose an Identity Provider and click Edit.

In Okta

Create your Application in Okta

1. Navigate to the Application page in Okta Administration.

2. Click on Add App. See documentation here to create an App in Okta.

3. Configure SSO in the Applications page.

Configure SSO in Okta

You need to retrieve information from CommCare HQ to configure SSO in Okta.

1. In the CommCare HQ Enterprise Console, navigate to the Edit Identity Provider page.

Retrieve the necessary information from the Application Details for Okta section. Populate the fields in Okta.

You will need:

a. Sign-in redirect URIs

b. Sign-out redirect URIs

c. Initiate login URI

2. Navigate to the Application configuration page in Okta. Under General Settings, scroll to the Login settings section.

3. Navigate to the Application configuration page in Okta. Under General Settings, scroll to the Login settings section.

4. Complete the Okta Application Details you retrieved from CommCare HQ in Okta.

5. Click Save.

Configure SSO in CommCare HQ

You need to retrieve information from Okta to configure SSO in the CommCare HQ OpenID Provider Configuration section.

You will need:

a. Client ID

b. Client Secret

c. Issuer URI

1. Navigate to the Application configuration page in Okta.

2. Under General Settings, scroll to the Client Credentials settings section.

3. Retrieve the Client ID and Client Secret from the Client Credentials section in Okta. Populate the fields in CommCare HQ.

4. Navigate to the Security page. Select the API section. Retrieve the Issuer URI (f).

5. Complete the information in CommCare HQ.

6. Click Save.

7. After configuring SSO with Okta, you need to set the SSO status to active. Edit the Okta configuration.

8. Scroll down to Single Sign-On Settings and set the SSO status to active.

9. Choose your preferred Login Enforcement. This setting only applies when Single Sign-On is Active.

a. The Global mode will require all users with a username ending in the specified Linked Email Domains to log in with SSO.

b. The Test mode will allow you to pilot test your configuration with a specific set of SSO Test Users. Only the Test Users will be required to log in with SSO when this mode is active.

10. Click Update Configuration.

At least one user must be specified as exempt from signing in with SSO at the login screen. This user can always log in to CommCare HQ with a password in case of any difficulties with the SSO setup. You can do this in the SSO Exempt Users tab.

SSO Test Users tab

You can set Test Users in the SSO Test User tab. These users must log in with SSO from the homepage when your Identity Provider is Active, and Login Enforcement is set to Test Mode. All other users can log in with a regular username and password. This is useful for pilot testing SSO before rolling out changes to the entire organization.

If a user tries to log in to CommCare HQ and is authenticated with Okta, the password field will disappear, and the Okta SSO button will be visible.

If a user tries to log in to CommCare HQ and is not authenticated with Okta, they will be redirected to the Okta log-in screen.

New Users

If a user is authenticated with Okta but doesn’t exist in CommCare HQ, an account will be created for them when they sign in for the first time. They will see the generic landing page after logging in.

If they have an invitation to a Project, they will see the invitation on the landing page.

If a user tries to sign in to CommCare HQ and is not assigned to the Application in Okta, they will see this error message.