Entra ID integration

Table of Contents

• Multiple connections
• Step 1: Register a new app in Microsoft Azure
• Step 2: Create a Client secret key
• Step 3: Add API permission for your app (Only when using auth type Service to service)
• Why Huma needs User.ReadWrite.All
• Step 4: Connect Huma to Entra ID
• Authorization types
• Step 5: Activate the integration

Active integration

• Integration is active
• Synchronize users
• Deactivated or deleted users 
• Supported fields - Employee fields
• Supported fields - Position fields

General questions

• FAQ: Entra ID and Huma position integration

Enable log in with Entra

• Enabling Employee Login with Entra ID

Multiple connections

If you need to configure multiple integration instances, follow the setup guidance provided here.

1: Register a new app in Microsoft Azure

To configure an integration in Huma, you must have a "System role with full access permissions for Organization".

If you are unsure which roles are required on the Entra ID side to complete the integration setup, please contact Entra ID support for guidance.

1. To give Huma access to your Entra ID, you must create an app in your Azure account to connect it to, and give it permission to access Entra.
2. Log in to your Microsoft Azure account.
3. In the top search bar, enter 'App registrations' and click on the search result.

4. Click on the 'New registration' button.

5. Provide a name for your app, for example, 'Huma'

6. In the 'Supported account types' section, select 'Accounts in this organizational directory only'

7. 'Redirect URI'

• • If you're connecting via 'Service to service' (Recommended):
    • Leave the redirect URI field empty.
      
      
  • If you're connecting via 'With user account' in Huma:
    
    • Choose 'Web' as the application type.
    • Set the redirect URI to

      https://auth.humahr.com/oauth

• Read more about 'Service to service' and 'With user account' under Connect Huma to Entra ID

2: Create a Client secret key

1. In the 'Overview' page, click 'Add a certificate or secret'
2. Click the 'New client secret' button
3. Provide a name for the client secret, for example, 'Huma client secret'
4. Choose an expiry period. After this period you need to create a new client secret and reconnect with Huma
5. Click the 'Add' button
   
6. Copy the 'Value key' and paste it somewhere. You will not be able to see this key after you navigate away from this page

3: Add API permission for your app

1. Navigate to 'API permissions' and click the 'Add a permission' button
2. Choose 'Microsoft Graph' and then 'Application permissions'
3. Search for 'User' and open it
4. Select 'User.ReadWrite.All' and click the 'Add permission' button
5. Click the 'Grant admin consent for [your company]' button
   

Why Huma needs User.ReadWrite.All

Huma doesn't only read users from Entra ID. It also writes to Entra ID. That's why read access isn't enough, and Huma won't connect without this permission.

With this permission, Huma can:

• Read users – list users in Entra ID so you can import and match them with Huma.
• Create users – add people from Huma to Entra ID, either during synchronization or automatically when you add them in Huma. New users are created as disabled accounts.
• Update users – keep the supported fields up to date in Entra ID when you change them in Huma.

Huma doesn't use the permission to delete or deactivate users, change groups or roles, or reset passwords for existing users.

🔗 See Supported fields for the fields that are updated.

Connect Entra with Huma 

1. Log in to your Huma organization
2. Go to 'Integrations' and choose 'Microsoft Entra ID'
3. Please read all the information about the Entra ID integration before moving to next step.
   • "How to use"
   • "Supported features"
   • "Supported fields" 
4. Click 'Set up' in the upper right corner
   
   

Authorization types

Authorization types

• Service to service (Recommended)
  The authorization is connected to your Huma organization.

• With your user account
  The authorization is connected to the user who sets this up. If the user loses the User Administration role in Microsoft Azure, the integration will stop working.

1. Copy and paste the 'Directory (tenant) ID' from Microsoft Azure into 'Tenant ID' in Huma, and the 'Application (client) ID' from Azure into 'Client ID' in Huma.
2. You will find these values on the 'Overview' page of your app in Microsoft Azure
3. Copy and paste the Client secret value key which you saved earlier. (If you didn't save the value anywhere before, delete the client secret and create a new one) and click 'Continue'
4. When adding users in Huma, you can choose if they should automatically be added in Entra ID. If you leave this inactive, you need to do a manual sync to add the user in Entra ID.
   1. If you're using the Teamtailor integration or the Nuu integration users added to Huma via that integration will also be added to Entra ID.
   2. "Create users" fails when the user is created in Huma with a private email address. Therefore, the user must have a business email address ready beforehand. 
      
      
5. To allow employees to log in using Microsoft Entra ID, simply toggle "Allow login with Entra ID" in the integration setup. This toggle controls whether Entra ID is shown as a login option on your organization's sign-in page.
   
   

IMPORTANT

Within the Entra ID application settings, include this Web Redirect URI under App registrations > Authentication

https://auth.humahr.com/

1. Click 'Save' and a connection is now established between the two systems. Now: On to the next step - it's where the magic happens.
2. Activate the integration. Synchronize users and choose how to handle conflicts or missing values
3. After clicking 'Continue' you will end up in the Synchronize users step
   1. Huma will inform you of any conflicts or inconsistency between Huma & Entra ID and you will have to decide how to handle conflicts and/or missing values. You can decide whether or not you want to update Entra ID based on values in Huma or the other way around.
4. Click 'Next' and decide which users you want to create in Huma & Entra ID
   1. If users in Entra ID do not exist in Huma, you can add users to Huma
   2. If users in Huma do not exist in Entra ID, you can add users to Entra ID
5. After deciding on the above click 'Synchronize users'
6. Huma will now start synchronizing users with Entra ID. You will receive an email confirming the result.

Your connection between Huma and Entra ID is active 

Any changes made to supported fields in Huma (listed below) will be automatically updated in Entra ID in real-time. 

Please be aware that you need to sync users to get the latest changes from Entra ID. Changes made in Entra ID will not be automatically updated in Huma. 

How to synchronize users manually

Use “Synchronize users” whenever you have updated one of the supported fields in Entra ID, or when you want to create new users. For user synchronization to work, the email address must always be identical in both systems.

1. Go to the Entra ID integration in Huma

2. Click “Synchronize users”

3. Follow the steps. 

Note

• If you have created a user in Huma, you must perform a “Manual synchronization” to create the user in Entra ID through the integration (if “create users automatically” is not activated).

• If an error occurs during synchronization, you can see detailed information in the “Error log” on the Entra ID integration page in Huma.

Deactivated or deleted users

• the user will not be deactivated in Entra.
• the user will be locked for updates. 

When a user is deleted in Huma...

• the user will not be deleted in Entra.
• the manual sync will ask you to create the user in Entra ID.
• the user cannot be synced if there have been changes to their record in Entra.

If you deactivate or delete a user in Entra the user will not be able to log into Huma using the Entra integration and the user will not be deleted in Huma. 

Supported fields - Employee fields that are synchronized.

Changes made to supported fields in Huma (listed below) are automatically updated in Entra ID in real time. Changes made in Entra ID however, must be synchronized manually in Huma.

mail

givenName

surname

mobilePhone

streetAddress

postalCode

city

country

employeeId

Supported fields – Position fields that are synchronized.

📄 Learn more about how employee data synchronization works in integrations in general.

⚠️ Note that activating the integration does not transfer historical position data to Entra ID. Only positions that are created or updated in Huma after the integration is activated will be synchronized.

Position data is synchronized only from Huma to Entra ID, not from Entra ID to Huma.

employeeHireDate

jobTitle

FAQ: Huma to Entra ID position integration

Does the integration update position data?

Yes. When supported position fields are changed in Huma, the updates are automatically sent to Entra ID.

In which direction is data synchronized?

Position data is synchronized in one direction only:

Huma → Entra ID

Changes made directly in Entra ID will not be sent back to Huma.

When is position data sent to Entra ID?

Position data is sent to Entra ID when:

• A new position is created in Huma

• An existing position is updated in Huma

• A user with a position in Huma is created in Entra ID through a manual sync

• The change happens after the integration has been activated

Can historical positions be transferred?

No. The integration does not automatically transfer historical position data that existed before the integration was activated.

Why aren’t all position fields synchronized?

Not all position fields can be synchronized between Huma and Entra ID because the two systems store and structure employment information differently. Some fields exist only in one system, or their data structures do not match directly. In other cases, limitations in the Entra ID API or in how data is handled in Huma prevent a full one-to-one mapping between the systems.

Enabling Employee Login with Entra ID

To allow employees to log in using Microsoft Entra ID, simply toggle "Allow login with Entra ID" in the integration setup. This toggle controls whether Entra ID is shown as a login option on your organization's sign-in page.

IMPORTANT:
Within the Entra ID application settings, include this Web Redirect URI under App registrations > Authentication

https://auth.humahr.com/