...
| Table of Contents | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Create a new application in Microsoft Entra ID
...
Map the following fields:
> Login URL
> Azure AD Microsoft Entra Identifier
...
In CommCare HQ
Complete the fields with the information retrieved from Entra ID.
...
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.
...
| Panel | ||||||
|---|---|---|---|---|---|---|
| ||||||
If a user is exempt from SSO they can still test signing in with SSO by using the sign-on URL that can be found in the CommCare HQ SSO configuration. |
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:
Deactivation: The user will be deactivated in CommCare HQ.
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
Navigate to App registrations in Microsoft Entra ID Dashboard by clicking on Manage > App registrations and click on the relevant CommCare application.
...
Navigate to Certificates & secrets and click on New Client secret under the Client secrets tab.
...
See here for more detailed steps: https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app#add-a-client-secret
...
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.
...
Navigate to API permissions under Manage and click on Add a permission.
...
Select Microsoft Graph.
...
Click on Application permissions
...
Select “Application.Read.All” permission, then click on “Add permissions”.
...
Select “User.Read.All” permission, then click on “Add permissions”.
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.
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.
...
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.
...
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.
...
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
Click on “Microsoft Entra ID” at the home page.
...
Click on “Enterprise applications” under “Manage”.
Click on the application we used for SSO and auto-deactivation.
...
Click on “Users and groups” under “Manage”.
...
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.