SSO User Management (Azure AD)

To set up SSO, you need to create and manage users in your identity provider (Azure Active Directory) 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.

Please note that SSO will override any two-factor authentication configured.



Read more here about creating and managing users in CommCare HQ. 

Read more here about creating users in Azure AD and assigning them to apps.

Sign in and start apps from the My Apps portal.

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 Azure Active Directory. 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. 



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.