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

In OneLogin

Create your Application in OneLogin

1. Navigate to the Application page in OneLogin Administration.

2. Click on Add App.

3. Search for OpenID Connect. Click on the OpenID Connect (OIDC) option.

4. Name your Application in the Portal. Click Save.

5. The OpenID Connect (OIDC) Application is created.

6. Retrieve the necessary information from the Application Details section within the Edit Identity Provider page in the CommCare HQ Enterprise Console (see step 4 in the CommCare HQ Configuration section below). Populate the fields.

You will need:

a. Login URL

b. Redirect URIs

c. Post Logout Redirect URIs

Retrieve the information from CommCare HQ.

Complete the information in OneLogin.

7. Click Save.

8. Navigate to the SSO page in the side menu in OneLogin. You will see Enable OpenID Connect settings. You will need this information when you edit the OneLogin Identity Provider in the Enterprise Console in CommCare HQ (see step 5 in the CommCare HQ Configuration section below).

You will need:

d. Client ID

e. Client Secret

f. Issuer URL

Retrieve the information from OneLogin.

Complete the information in CommCare HQ.

Users in OneLogin

You can create or import users in the Users page in OneLogin. Make sure you assign them to your CommCare Application so they can log in to CommCareHQ with SSO.

In CommCare HQ

You must configure the SSO Identity Provider in the Enterprise Console 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.

Identity Provider Tab

4. In the Identity Provider tab, navigate to the Application Details for OneLogin section. Here you will find the information you need to complete in OneLogin (step 6 in the OneLogin Application Configuration above).

You will need:

a. Login URL

b. Redirect URIs

c. Post Logout Redirect URIs

Retrieve the information from CommCare HQ.

Complete the information in OneLogIn.

5. In the Identity Provider tab, navigate to the OpenID Provider Configuration section. You will find the information you need on the SSO page in your OneLogin Application. (Step 8 in the Create your Application in OneLogin section).

You will need:

d. Client ID

e. Client Secret

f. Issuer URL

Retrieve the information from OneLogin.

Complete the information in CommCare HQ.

6. Set SSO to active.

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

Global Mode

Test Mode

8. Click Update Configuration.

SSO Exempt Users tab

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.

Sign In with OneLogin SSO

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

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

New Users

If a user is authenticated with OneLogin 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 OneLogin, they will see this error message.