Table of Contents:

Create a new application in Microsoft Entra ID

In Azure

1. Open your Microsoft Azure Account Dashboard.

2. Select Microsoft Entra ID in the Azure Services list. 

Open

3. Select Enterprise Applications in the sidebar menu.

Open

4. Click New application and on the next page, Create your application to create your CommCare HQ application.

5. In the pop-up window, enter your application name, CommCare HQ, and select the Integrate any other application you don’t find in the gallery (Non-gallery) option.

6. Set up Single Sign-On in your application by clicking on the button on the application overview page or by selecting it from the sidebar menu.

7. Select the SAML SSO method. 

Retrieve the SAML configuration information from CommCare HQ

In CommCare HQ

1. In the CommCare HQ settings menu, navigate to the Enterprise Dashboard. 

2. Select Manage Single Sign-On in the Enterprise Dashboard. 

3. Click Edit to see the Azure AD identity provider configuration information in CommCare HQ. 

4. Retrieve information from CommCare HQ to set up SSO in Azure.

5. Map the following fields:
> Identifier (Entity ID)
> Reply URL
> Sign-on URL

Configure SAML with the information retrieved from CommCare HQ

In Azure

1. Navigate to your CommCare HQ application in Azure.

2. Complete the fields with the information retrieved from CommCare HQ.

Manage User Attributes and Claims

In Azure

1. Edit the user attributes and claims.

2. Set the Name Identifier format to Email address

SAML Signing Certificate

In Azure

Download the certificate in Azure. Make sure you choose the Certificate (Base64) option. 

In CommCare HQ

Upload the certificate in CommCare HQ by clicking on the Choose File button.

Retrieve the SAML configuration information from Azure 

In Azure

Retrieve information from Azure to set up SSO in CommCare HQ.

Map the following fields:

> Login URL
> Microsoft Entra Identifier

In CommCare HQ

Complete the fields with the information retrieved from Entra ID.

Test Single Sign-On with CommCare HQ

1. Click on Test.

2. Choose to sign in as your current user or as someone else. 

Manage Users

In Azure

Read the Microsoft documentation on adding and deleting users in Azure Active Directory.

In CommCare HQ

Read the CommCare HQ documentation on adding and deleting web users in CommCare HQ. 

SSO with User Management (Entra ID)

To set up SSO, you need to create and manage users in your identity provider (Microsoft Entra ID) and CommCare HQ account.

For a seamless SSO experience, you need to create users in CommCare HQ and invite them to project spaces before assigning them to the CommCare HQ app in your Identity Provider.

Read more about creating and managing users in CommCare HQ at https://dimagi.atlassian.net/wiki/x/GAnKfw. 
Read more about creating users in Entra ID and assigning them to apps here.
https://support.microsoft.com/en-us/account-billing/sign-in-and-start-apps-from-the-my-apps-portal-2f3b1bae-0e5a-4a86-a33e-876fbd2a4510

Log in via the CommCare HQ login page

Use Case 1

The user has a CommCare HQ account and is assigned to project spaces. 

An organization starts managing how their employees log in to CommCare HQ by implementing Single Sign-On with the help of an Identity Provider, like Microsoft Entra ID. The employee is logged in to the organization's identity provider and navigates to the CommCare HQ login page. When the user types in their email address to log in, CommCare HQ will detect that an Identity Provider manages the user's email domain. The password field disappears, and the Sign In button is replaced with a Sign in with your company's identity provider button. 

Log in via the Identity Provider (AAD)

Use Case 2

The user has a CommCare HQ account and is assigned to project spaces.

The organization creates and manages the user's apps in the Identity Provider. The user logs in to the Identity Provider and chooses CommCare HQ from their list of apps. The user is directed to CommCare HQ without having to authenticate.

Use Case 3

The user has a CommCare HQ account and is invited to project spaces. The user has not logged in to CommCare HQ before.

The user logs in to the Identity Provider and chooses CommCare HQ from their list of apps. The user is directed to CommCare HQ without having to authenticate. The user sees a page in CommCare HQ to accept all invitations to project spaces.

Use Case 4

The user doesn't have a CommCare HQ account.

The user logs in to the Identity Provider and chooses CommCare HQ from their list of apps. The user is directed to CommCare HQ without having to authenticate. The user sees a page that confirms that their CommCare HQ account was created. The user can now create a Project and start using CommCare HQ. 

Use Case 5

The user is a non SSO user, but has a CommCare HQ account.

The user logs into CommCare using generic login page www.commcarehq.org without specific project-space in the login URL. The user needs to enter email address and password to sign in. 

Use Case 6

The user uses mobile worker credentials (username) to sign into CommCare HQ account. Please read the workflow here.

The user can continue to use mobile worker username to sign into CommCare HQ account. 

Entra ID Token and Enabling SSO Remote User Management

Remote User Management is a feature available to Enterprise Accounts that have enabled Single Sign-On (SSO). When a user is removed from your SSO application, the following actions occur:

1. Deactivation: The user will be deactivated in CommCare HQ.

2. API Key Disablement: The user's API key will also be disabled, preventing access to any HQ data.

Users listed in the "SSO Exempt Users" category will not undergo deactivation, and their API access will remain active.

Setting up Client Secret on Entra ID

1. Navigate to App registrations in Microsoft Entra ID Dashboard by clicking on Manage > App registrations and click on the relevant CommCare application.

2. Navigate to Certificates & secrets and click on New Client secret under the Client secrets tab.

3. The expiration date for the client secret can be up to 2 years by customising the start and end date. Client secret values cannot be viewed, except for immediately after creation. The value should be saved for reference later. 

4. Navigate to API permissions under Manage and click on Add a permission.

5. Select Microsoft Graph.

6. Click on Application permissions

7. Select “Application.Read.All” permission, then click on “Add permissions”.

8. Select “User.Read.All” permission, then click on “Add permissions”.

9. Click on “Grant admin consent for {your organization}”. Once done, the status of the permissions should become “Granted for {your organization}” with a green check mark as seen below.

Remote User Management Form in CommCare HQ

Please ensure that client secret on Entra ID is setup based on the instructions provided above before you fill out the Remote User Management Form in CommCare HQ.

1. Enterprise admin users on CommCare HQ navigate to the Enterprise Console on the top right corner of their project space by clicking on the Settings cog.

2. Click on Manage Single Sign-On the User Management panel on the left and then click on the Edit button on the relevant Identity Provider listed.

3. The user can see a section called Remote User Management. This is how it will look the first time:

Tenant ID: Tenant ID can be found in the Overview section of Microsoft Entra ID:

Application ID: Application ID can be found by navigating to Manage> App registrations > All applications - the Application ID can be retrieved from that list.

Client Secret: Click on the application that is used for SSO. In Manage> Certificate & Secrets, list of Secrets with Expiration date for the secret can be viewed but Client secret values cannot be viewed, except for immediately after creation. Enter the Client secret value saved earlier.

Secret Expires On: Enter the expiration date from the same screen above.

4. After all the fields are filled in, click on “Update Configuration” at the bottom of the page, all configurations will be saved. If Auto-Deactivation is checked, all four fields will be required. If any of them are left blank, it will lead to an error message.

The frequency of how CommCare HQ keeps the users list in sync with what is present on the Entra ID portal

The task is scheduled to run once a day at 2:00 AM UTC time

The minimum steps necessary to remove a user’s access to authenticate in CommCare HQ with the Enterprise application in the Azure Portal

1. Click on “Microsoft Entra ID” at the home page.

2. Click on “Enterprise applications” under “Manage”.

3. Click on the application we used for SSO and auto-deactivation.

4. Click on “Users and groups” under “Manage”.

5. Check the user we want to remove, and click on remove.

What happens when a deactivated user is removed from the IdP, deactivated on HQ, and then re-added back to the IdP later?

When the user re-added back to the idP, user can simply log in to HQ through SSO, and will regain access to all unexpired API keys and any previous access to project spaces that they were once a member of.