> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/connector-configuration/microsoft/5-azuread.md). # Entra ID/O365 connector This page describes how to enable provisioning to Entra ID and Office365 {% hint style="danger" %} **Deprecated. Use the** [**Microsoft Graph PowerShell connector**](/connector-configuration/microsoft/14-psgraph.md) **instead.** This connector drives the **MSOnline** and **AzureAD** PowerShell modules, both of which Microsoft has retired in favour of Microsoft Graph. It still ships and is still patched, so an existing deployment keeps working, but it should not be chosen for a new one. This page is kept short deliberately: it covers what someone already running the connector needs, and points at the replacement for everything else. {% endhint %} The connector manages objects inside Entra ID — users, groups, memberships and licence assignment — and O365 alongside them. Entra provides cloud services that mirror on-premises ones, and where a dedicated connector exists it is the better choice: Exchange mailboxes, online or on premises, belong to the [Exchange connector](/connector-configuration/microsoft/6-exchange.md). | Operation | Supported | | -------------------------------------- | ---------------------------------------------------------------------------- | | Create / update a user or group (Save) | ✅ | | Assign and remove licences | ✅ — including partial licences, with individual plans disabled | | Search | ✅ — users, groups, memberships, service principals, roles and resource usage | | Suspend / resume | ✅ — through `BlockCredential` | | Reset password | ✅ | ## Versions and compatibility The end applications are **Entra ID** and **Office 365**, reached through three PowerShell modules rather than an API of the connector's own: | Module | Used for | State | | ------------ | --------------------------------------------------- | ------------------------ | | **MSOnline** | Most operations — users, groups, licences, roles | **Retired by Microsoft** | | **AzureAD** | Service principals, user managers, some memberships | **Retired by Microsoft** | | **Az** | The Entra resource usage report | Current | That is the reason for the deprecation: two of the three modules are no longer supported by the vendor who wrote them. The connector host needs **PowerShell 5.1** and **.NET 4.7.2 or newer**, the latter being a requirement of the `Az` module. On Windows releases older than Server 2016, install the Windows Management Framework 5.1 first. ## Installing the connector Every .NET/PowerShell connector installs the same way. See [Installing PowerShell connectors](/connector-configuration/microsoft/1-powershellconnectorinstallation.md). Beyond that, all three modules must be present on the connector host. Install them from an **x64** PowerShell console: {% code overflow="wrap" %} ```powershell Install-Module MSOnline Install-Module -Name AzureAD Install-Module -Name Az ``` {% endcode %} {% hint style="info" %} If those fail to download, the session is not using TLS 1.2, which Microsoft requires for NuGet packages and which is not the default in every PowerShell session. Set it and retry: {% code overflow="wrap" %} ```powershell [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 ``` {% endcode %} {% endhint %} ## Starting, stopping, and restarting The installer registers a pair of Windows services named after the connector name you supply. See [Installing PowerShell connectors](/connector-configuration/microsoft/1-powershellconnectorinstallation.md#starting-stopping-and-restarting). ## Command-line parameters and properties The connector takes no command-line parameters. Queue names, concurrency, logging, simulation mode and the RabbitMQ settings live in `Connector.config`, documented for the whole family in [Using PowerShell connectors](/connector-configuration/microsoft/2-powershellconnectorsusage.md#working-with-the-connector-configuration). ## Troubleshooting Troubleshooting for the whole family is in [Using PowerShell connectors](/connector-configuration/microsoft/2-powershellconnectorsusage.md). What follows is specific to this connector. **Most failures here are the connector failing to reach the cloud.** Test each module's sign-in by hand, as the connector does: {% code overflow="wrap" %} ```powershell Import-Module MSOnline $Credentials = Get-Credential Connect-MsolService -Credential $Credentials Get-MSOLUser -MaxResults 1 # proves the service account can read ``` {% endcode %} Most operations use MSOnline, but some use the AzureAD module, so test that one too: {% code overflow="wrap" %} ```powershell Import-Module AzureAD $Credentials = Get-Credential Connect-AzureAD -Credential $Credentials ``` {% endcode %} ### Things to know | Thing to know | Why it matters | | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **`ForceChangePassword` is set to false, and `PasswordNeverExpires` to true, on every save** | Deliberate: OpenIAM holds the password and controls when it changes, so Entra must not demand its own change | | **O365 group membership only takes effect once the licence is provisioned** | Microsoft allows up to 24 hours, though it is usually about 20 minutes. Security groups are assignable immediately | | **The service account needs the `MailRecipients` role** | Without it, O365 group assignment may not be handled correctly | | **The Global Administrator role comes back as `Company Administrator`** | The same role, named differently by the portal and by the PowerShell API. Worth knowing before a synchronization result looks wrong | | **SMTP is disabled when security defaults are enabled** | Microsoft now turns security defaults **on** by default, where they used to be off. Check them under **Entra ID** in the Azure portal, and check the service account's own SMTP permission under **account → mail → manage mail apps** in the Microsoft 365 admin centre | ## Configuring the managed system Follow the standard steps in [Configure a managed system](/administration-guide/lifecycle/configure-managed-system.md). The **Login Id** is the service account, and it must be a **primary account address in email format** — `serviceaccount@openiamdemo.com`, not a bare name. It needs rights to create users in Entra, change their properties, and perform whatever else you intend the connector to do. The connector provisions **users** and **groups**, the latter in all four kinds Entra offers: Security, Distribution, MailEnabledSecurity and Office365. ## Attribute mapping and policy map The principal attribute is **`UserPrincipalName`**. The connector holds no fixed attribute list. On each operation it asks PowerShell what the target cmdlet accepts — `New-MsolUser`, `Set-MsolUser`, `New-MsolGroup` or `Set-MsolGroup` — and passes through whatever matches, so the accepted names are those cmdlets' own parameters. Microsoft documents them, and an attribute the cmdlet does not recognize is dropped rather than rejected, so a typo in the policy map fails quietly. Three attributes behave in a way the cmdlet reference will not tell you: | Attribute | Behaviour | | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `DisplayName` | Required by Microsoft at creation. If the map does not supply it, the connector sets it to the `UserPrincipalName` | | `UsageLocation` | Also required at creation. If the map does not supply it, it defaults to **`US`** — set it explicitly unless that is what you want | | `LicensesToAssignJson` / `LicensesToRemoveJson` | The connector's own attributes, not MSOnline parameters. See below | ### Licences The connector can assign a whole licence pack — E1, E3 and so on — or a pack with individual service plans disabled. Removal always runs **before** assignment, because some licences cannot coexist. **`LicensesToAssignJson`** takes an array of licence names, each with the plans to switch off inside it: {% code overflow="wrap" %} ```json [{"LicenseName":"openiamdemocloud:ENTERPRISEPACK","DisabledPlans":["SWAY","FLOW_O365_P2"]},{"LicenseName":"openiamdemocloud:POWER_BI_STANDARD","DisabledPlans":["BI_AZURE_P0"]}] ``` {% endcode %} That assigns E3 with SWAY and FLOW\_O365\_P2 disabled, and Power BI with `BI_AZURE_P0` disabled. Licence names are specific to your tenant — they carry an organization prefix — so read them from the tenant rather than guessing: ```powershell Connect-MsolService Get-MsolAccountSku ``` Leave `DisabledPlans` as an empty array to enable the whole pack. The list you send is the final state: plans that belong to the pack and are **not** listed are enabled, so this is how you re-enable something previously disabled. **`LicensesToRemoveJson`** removes whole licences, and takes no plan list: {% code overflow="wrap" %} ```json [{"LicenseName":"openiamdemocloud:STANDARDPACK"},{"LicenseName":"openiamdemocloud:POWER_BI_STANDARD"}] ``` {% endcode %} To disable part of a licence rather than remove it, use `LicensesToAssignJson` with `DisabledPlans` instead. ## Reconciliation and synchronization How synchronization and reconciliation work in general is covered in the Administration guide — see [*Synchronize and import data*](/administration-guide/lifecycle/synchronize-and-import-data.md) and [*Configure reconciliation*](/administration-guide/lifecycle/configure-reconciliation.md). Set the search string in the ***SQL Query / Directory Filter*** field on the synchronization page. The connector runs it against the tenant to find the objects to read. Five kinds of object can be synchronized: | What | Query it with | Notes | | -------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Users | `Get-MSOLUser -All \| Select-Object *` | `-SearchString` narrows to one sign-in name; `-MaxResults 1` is useful for a test | | Groups | `Get-MSOLGroup -All \| Select-Object *` | | | Service principals | `Get-AzureADServicePrincipal -All:$true \| Select-Object *` | Uses the AzureAD module rather than MSOnline | | Entra ID roles | `Get-MsolRole` | Takes no parameters. If the attribute name lookup contains `membership`, role members are returned as well | | Entra resource usage | — | Reports usage inside a resource group, subscription or tenant. The service account needs at least the **Reader** role at that level, and the shipped connector covers a fixed set of resource types that can be extended by customizing it | Roles return `Name`, `ObjectId`, `Description`, `IsEnabled`, `IsSystem` and, when asked for, `Membership`. --- # 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.openiam.com/connector-configuration/microsoft/5-azuread.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.