> 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** (or search for it by name) and click its card. If a Microsoft Entra ID instance is already connected, click **+ Create instance**
4. Enter an **Instance name** (required), for example the name of the Microsoft tenant
5. 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="warning" %}
Without this role, Microsoft Entra refuses to let Harmony reset the password of any user who holds an admin role. Password resets for admins always fail until the role is assigned, including those requested through the [Password Reset Request](https://github.com/harmonyso/public-docs/tree/main/ai-agents/agents/password-reset-request.md) agent.
{% endhint %}
**How to assign the role**
You need the **Global Administrator** or **Privileged Role Administrator** role in Microsoft Entra to assign it.
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. Search and select **Harmony Entra ID**
5. Click **Add** to confirm the assignment
Once assigned, Harmony can reset passwords for every user in your Microsoft Entra directory, admins included. The same role also lets Harmony reset MFA for, and deactivate, users who hold an admin role.
{% hint style="info" %}
Adding users to a role-assignable group also needs the **Privileged Role Administrator** role assigned to **Harmony Entra ID**, in the same way.
{% endhint %}
#### 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 in Active Directory for synced accounts** 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 **Sign out everywhere after the reset** 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, below **Reset in Active Directory for synced accounts**. 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 a Microsoft Entra ID P1 or P2 license; left empty without one)
**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
* Application inventory synced automatically to your Harmony software catalog
**Login Events**
Harmony captures and normalizes Entra sign-in activity into a consistent event format. Microsoft provides sign-in logs through its API only to tenants with a Microsoft Entra ID P1 or P2 license. 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 twice a day.
{% 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
Field mapping is not configured on the integration card. To configure it, contact Harmony support with the Entra attribute to use for each employee field.
***
#### 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, listed under **Microsoft Entra** in the workflow builder - no need to switch between tools or trigger manual processes outside of Harmony.
**Available workflow blocks**
**User management blocks:**
* **Create User** - provision a new user in your Microsoft Entra directory as part of a workflow, useful for onboarding and provisioning automation
* **Get User** - retrieve an existing user's details from Entra to use in downstream workflow steps
* **Assign Manager** - set or update a user's manager in Entra, enabling automated org hierarchy management
**Group ownership blocks:**
* **Add Group Owners** - assign owners to a Microsoft Entra group as part of onboarding or access management workflows
* **Remove Group Owners** - 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 **API Request** block under **Microsoft Entra** 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 Microsoft Entra ID
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 ID P1 or P2** license. For organizations without one, this field will be left empty rather than causing sync errors. If you have a P1 or P2 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 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).
* Microsoft Entra ID 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 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 `automate deployments from our CI pipeline` 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.