> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/integrations/identity-provider/microsoft-entra.md).
# Microsoft Entra
Microsoft Entra ID (formerly Azure Active Directory) is Microsoft's cloud-based identity and access management service. Connecting Entra ID to Harmony enables automated user provisioning, intelligent license management, and seamless access control across your Microsoft 365 ecosystem and integrated applications.
#### What the Microsoft Entra ID integration enables
| Capability | Description |
| --------------------- | ---------------------------------------------------------------- |
| User Provisioning | Automate user lifecycle management across Microsoft 365 services |
| License Management | Track and optimize Microsoft 365 licenses to reduce costs |
| Group Management | Sync security and distribution groups for access control |
| Application Discovery | Identify all enterprise applications and their assignments |
| Automation Workflows | Build custom workflows using Microsoft Graph API |
| Login Event Tracking | Monitor Entra sign-in activity directly within Harmony |
| OOO Calendar Sync | Automatically reroute tickets when agents are out of office |
***
#### Prerequisites
Before connecting Microsoft Entra ID to Harmony, ensure you have:
1. **Microsoft 365 Global Administrator access**
2. **A Harmony account** with admin privileges
{% hint style="info" %}
Global Administrator or Privileged Role Administrator role is required to authorize the Harmony integration.
{% endhint %}
***
#### Connect Microsoft Entra ID
1. **Navigate to Integrations**
1. Log into your Harmony dashboard
2. Navigate to **Settings → Integrations**
3. Find **Microsoft Entra ID** under **Identity Provider**
4. Click **Connect**
2. **Authorize Entra ID**
1. You'll be redirected to Microsoft to authorize the connection
2. Sign in with your **Microsoft 365 admin account**
3. Review the requested permissions
4. Click **Accept** to authorize
5. You'll be redirected back to Harmony
3. **Verify Connection**
Confirm that Microsoft Entra ID shows **Connected** status in your Harmony integrations page.
***
#### Enable Password Reset
Resetting a user's password through Harmony requires an additional Entra role assignment on top of the API permissions already granted to the Harmony application. The **Privileged Authentication Administrator** role must be assigned to the Harmony Entra ID enterprise application.
{% hint style="info" %}
This role assignment is only required if you want Harmony to be able to reset passwords. It is not needed for other Entra ID capabilities.
{% endhint %}
**How to assign the role**
1. In the [Microsoft Entra admin center](https://entra.microsoft.com), go to **Roles and administrators**
2. Search for **Privileged Authentication Administrator** and open the role
3. Click **Add assignments**
4. In the search panel, search for **Harmony** and select **Harmony Entra ID** (Enterprise application)
5. Click **Add** to confirm the assignment
Once assigned, Harmony can reset passwords for users in your Entra ID directory.
#### Users synced from on-premises Active Directory
A password Harmony sets in Microsoft Entra is not written back to your on-premises Active Directory. For users synced from Active Directory, Windows sign-in, VPN and other apps that check Active Directory would keep the old password.
If you connect the [Active Directory integration](/integrations/identity-provider/active-directory.md), turn on **Reset passwords in Active Directory** on this connection in the Password Reset agent. Harmony then resets synced users in Active Directory, with a temporary password the employee must change at their next sign-in. The Active Directory service account needs the [password reset permissions](/integrations/identity-provider/active-directory.md#password-reset-permissions). The setting is offered when exactly one Active Directory connection is enabled.
{% hint style="warning" %}
By default, Microsoft Entra Connect does not sync a temporary password. The employee first uses it to sign in to Windows, or to another system that checks Active Directory, and sets a new password there. That new password then syncs to Microsoft Entra within a few minutes. Until then the temporary password does not work for Microsoft Entra sign-in, and Microsoft Entra keeps accepting the employee's previous password. Harmony leaves an internal note about this on the resolved ticket. If **Revoke active sessions** is on for the connection, the employee is also signed out of Microsoft Entra and signs back in once their new password has synced; turn it off for this connection if your employees cannot reach a domain controller to set one.
There are two ways to change this:
* Turn off **Require a new password at next sign-in** on the connection, under **Reset passwords in Active Directory**. The password Harmony sets is then not a temporary one: it syncs to Microsoft Entra within a few minutes, replaces the previous password there too, and stays valid until the employee changes it. That includes the copy in the message Harmony sent them, so nothing makes them replace it. Choose this when a reset also has to lock the previous password out of Microsoft 365, or when your employees cannot reach a domain controller to set a new one.
* Keep it on and enable the [ForcePasswordChangeOnLogOn](https://learn.microsoft.com/en-us/entra/identity/hybrid/connect/how-to-connect-password-hash-synchronization#synchronizing-temporary-passwords-and-force-password-change-on-next-logon) feature of Microsoft Entra Connect, so the temporary password itself syncs to Microsoft Entra. Microsoft advises enabling it only when self-service password reset and password writeback are enabled on the tenant.
{% endhint %}
{% hint style="info" %}
Users that exist only in Microsoft Entra are still reset in Microsoft Entra, so keep the Privileged Authentication Administrator role assigned.
{% endhint %}
***
#### What Harmony Syncs from Entra ID
Once connected, Harmony automatically syncs:
**Users**
* User profiles (name, email, job title)
* User Principal Name (UPN)
* User status (enabled, disabled) - reflected as Active, Inactive, or Terminated
* Department and office location
* Manager relationships
* Member/Guest type
* Last sign-in activity (requires Microsoft Entra Premium license; left empty for non-Premium accounts)
* Assigned licenses
**Groups**
* Security groups
* Microsoft 365 groups
* Distribution lists
* Group memberships
* All assigned group types per group (a single group can belong to multiple types simultaneously, such as Security and Microsoft 365)
**Applications**
* Enterprise applications, including all associated Entra groups
* App registrations
* User and group assignments
* OAuth permissions
* Application inventory synced automatically to your Harmony software catalog
**Login Events**
Harmony captures and normalizes Entra sign-in activity into a consistent event format. For each sign-in event, Harmony records:
* **Login timestamp** - when the sign-in occurred, reflecting the actual time of the action rather than when Harmony's polling process picked it up
* **IP address** - the network source of the login
* **Device information** - the device used during sign-in
* **Location metadata** - geographic context for the login event
{% hint style="success" %}
Harmony syncs data every 24 hours by default.
{% endhint %}
***
#### Configure Custom Field Mapping
By default, Harmony maps standard Entra ID fields to employee attributes automatically. If your organization uses non-standard or custom Entra fields to store employee information, you can configure custom field mapping overrides.
For example, if your organization stores employee location in a custom Entra attribute rather than the default field, you can map Harmony's location attribute to that custom field instead.
**How field mapping overrides work:**
* Map any supported employee attribute (such as location) to a custom Entra field of your choice
* Override keys are validated against known field mappings, so only supported fields can be remapped
* Custom mappings take effect on the next sync cycle
To configure field mapping, navigate to your Microsoft Entra ID integration settings in **Settings → Integrations** and look for the **Field Mapping** configuration options.
***
#### Outlook Calendar OOO Sync
For organizations on Microsoft 365, Harmony can detect out-of-office (OOO) events directly from Outlook Calendar via the Microsoft Entra integration and update each agent's availability status in real time - no manual status changes needed.
**How it works:**
* Harmony reads OOO events from Outlook Calendar and marks agents as unavailable for the duration of the event
* Tickets are automatically rerouted when an agent is marked out of office, preventing ticket stranding
* Availability status is updated in real time as OOO events are detected
This brings full parity with the existing Google Calendar OOO integration and extends it to cover automatic ticket dispatch.
To enable Outlook Calendar OOO sync, ensure your Microsoft Entra integration is connected and navigate to your availability settings in Harmony.
***
#### Entra User Management in Workflows
You can automate common Microsoft Entra identity management tasks directly from Harmony Workflows using dedicated Entra workflow blocks - no need to switch between tools or trigger manual processes outside of Harmony.
**Available workflow blocks**
**User management blocks:**
* **Create Entra User** - provision a new user in your Microsoft Entra directory as part of a workflow, useful for onboarding and provisioning automation
* **Get Entra User** - retrieve an existing user's details from Entra to use in downstream workflow steps
* **Assign Entra Manager** - set or update a user's manager in Entra, enabling automated org hierarchy management
**Group ownership blocks:**
* **Add Entra Group Owner** - assign an owner to a Microsoft Entra group as part of onboarding or access management workflows
* **Remove Entra Group Owner** - revoke group ownership during offboarding or access review workflows
These blocks connect seamlessly with other workflow actions, conditions, and triggers already available in Harmony.
**Azure Management API support**
The Entra request block in Harmony Workflows also supports Azure Management API endpoints, enabling richer integrations with Azure's management plane alongside existing Entra capabilities.
{% hint style="info" %}
Entra workflow blocks integrate with your existing Microsoft Entra connection. Ensure your Entra integration is connected and authorized before using these blocks in workflows.
{% endhint %}
**Reliable app access assignment**
Harmony checks whether an Entra app has direct assignment configured before offering it as an access provisioning option in a workflow. If an app does not support direct assignment, that option is automatically blocked - preventing workflows from failing mid-execution. This means access request workflows for Entra apps only present assignment methods that are actually supported by the app's configuration.
***
#### AI Agent Support for Entra Account Status
Harmony's AI agent can handle account status and access issues for employees managed in Microsoft Entra ID. The agent intelligently distinguishes between different account states and guides employees or IT staff to the right next step:
* **Suspended accounts** - the agent escalates to a human IT team member, since these require manual intervention
* **Locked accounts** (Smart Lockout detected) - the agent recognizes when an Entra Smart Lockout has triggered and recommends a password reset to resolve the issue
* **Active accounts with login issues** - the agent gathers more context to help diagnose the problem
This allows your team to resolve common Entra account issues faster through the AI agent without requiring manual triage for every request.
***
#### Troubleshooting
Connection fails during authorization
**Solutions:**
1. Ensure you're signing in with a Global Administrator or Privileged Role Administrator account
2. Verify your organization allows third-party app integrations
3. Try clearing browser cache and cookies, then retry the authorization
4. Check if your organization has conditional access policies that might block the connection
User sync incomplete
**Solutions:**
1. Verify users are not hidden in directory
2. For large directories (10,000+ users), allow extra sync time
3. Review sync logs in Harmony for specific errors
4. Contact Harmony support if specific users are consistently missing
Cannot provision new users
**Solutions:**
1. Verify you have available licenses to assign
2. Check that domain is verified in Azure AD
3. Confirm user email format matches verified domains
4. Ensure your organization's user provisioning policies allow external integrations
Last login not showing for some users
Last login data requires a **Microsoft Entra Premium** license. For organizations without a Premium license, this field will be left empty rather than causing sync errors. If you have a Premium license and last login data is still missing, verify that audit log access is included in your Harmony API permissions.
Workflow block fails when assigning app access
If an Entra app access assignment step fails in a workflow, the app may not support direct user assignment. Harmony now automatically blocks this option when direct assignment is not configured on the app, but if you are using an older workflow configuration, review the assignment method selected for that step and update it to a supported option.
***
#### Best Practices
Monitor Integration Health
Regularly check your integration status:
* Review sync logs in Harmony dashboard
* Monitor for any authorization issues
* Check sync completion times for large directories
* Set up alerts for sync failures
Leverage Dynamic Groups
Use dynamic groups for automated membership:
* Auto-add users based on department attribute
* Include users from specific locations
* Filter by job title or employee type
* Reduces manual group management overhead
Enable Security Defaults
Enforce baseline security in Microsoft Entra ID:
* Require MFA for all users
* Protect privileged accounts
* Block legacy authentication
* Security defaults provide immediate protection
Regular Access Reviews
Periodically review access and permissions:
* Audit user group memberships quarterly
* Review license assignments for optimization
* Remove inactive or unnecessary user accounts
* Validate conditional access policies
Use Workflow Blocks for Routine Identity Tasks
Take advantage of Entra workflow blocks to reduce manual effort:
* Automate user provisioning as part of onboarding workflows
* Use the Assign Entra Manager block to keep org hierarchy accurate without manual updates
* Automate group ownership changes during offboarding to prevent orphaned groups
* Chain Entra blocks with other workflow steps for end-to-end automation
***
Need help? Contact [**support@harmony.io**](mailto:support@harmony.io) for assistance with your Microsoft Entra ID integration.
***
#### Data & Privacy
Key privacy principles
For information about how Harmony handles your data, see our [Privacy Policy](https://harmony.io/privacy).
* Azure AD credentials are encrypted at rest and in transit
* Only directory data necessary for IT operations is accessed
* No personal emails or private conversations are read
* User activity data used only for license optimization
* Integration can be revoked at any time from Azure Portal or Harmony
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.harmony.io/integrations/identity-provider/microsoft-entra.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.