# Microsoft Entra ID Data Integration

## Overview <a href="#overview" id="overview"></a>

Identity Intelligence’s platform can analyze authentication events in Microsoft Entra ID (formerly Azure AD) to give insights into how users are accessing your applications. In order to provide Insights, you have to set up an integration between Microsoft Entra ID and Identity Intelligence for analysis.  This document will walk you through the process of setting up API access inside of Entra ID and will also walk you through the complementary set up inside of the Identity Intelligence console.

### Important Notes <a href="#next-steps" id="next-steps"></a>

* <mark style="color:blue;">**UPDATE \[2026.05.05]**</mark> - Please note the updated API permissions required to collect Entra ID agent data types for non-Marketplace based integrations - see [#add-api-permissions-1](#add-api-permissions-1 "mention") section below.  After adding the API permissions, review the Advanced settings tab of the integration and set the corresponding data type selection to `Yes`<br>

  <figure><img src="/files/54lrGc61UezLBZXnz5GY" alt=""><figcaption></figcaption></figure>
* <mark style="color:blue;">**UPDATE \[2025.08.20]**</mark> - Cisco Identity Intelligence now has Beta releases of Microsoft Azure Marketplace apps for both the primary Data Integration (this article, see [below](#azure-marketplace-app-data-integration-beta-release)) AND the [Azure Event Hub](/integrations/azure-active-directory-event-hub-streaming.md) streaming capability.  &#x20;
* <mark style="color:$warning;">**Microsoft Licensing**</mark> - Please see the [#azure-a-d-sign-in-log-availability](#azure-a-d-sign-in-log-availability "mention") section below for the implications of Microsoft product licensing on Identity Intelligence data collection for specific data types.&#x20;
* [Microsoft Entra ID B2C](https://learn.microsoft.com/en-us/azure/active-directory-b2c/overview) is *not* supported.
* This integration is for Entra ID data collection.  For SSO to your Identity Intelligence tenant using Entra ID, please use Duo SSO with Entra ID as an external authentication source ([article](https://duo.com/docs/sso#configure-the-duo-single-sign-on-app-in-entra-id)).&#x20;
* If this is a brand new Microsoft Entra ID tenant, for instance a development environment, then make sure to enable a Microsoft Entra ID subscription and resource provider.

### Entra ID Integration <a href="#azure-ad-integration" id="azure-ad-integration"></a>

At a high-level, Entra ID has different activity log types which each contain different sets of information. Identity Intelligence will ingest the Sign-ins and audit logs, as well as the Directory data.  Sign-in and audit logs are available through the Microsoft Entra ID portal.

* Sign-ins – Information about sign-ins and how your resources are used by your users.
* Directory  - User and Group information from your Entra ID.

### Entra ID Sign-in Log Availability <a href="#azure-ad-sign-in-log-availability" id="azure-ad-sign-in-log-availability"></a>

Sign-in logs are available via Microsoft Graph API for 30 days inside Entra ID with a Premium subscription (P1 or P2).

*<mark style="color:red;">**Note**</mark>* - sign-in logs are NOT currently available via Graph API with non-P1 or P2 Entra ID subscriptions, e.g Microsoft Entra ID Free.&#x20;

* Reference:&#x20;
  * **Data Retention** - <https://docs.microsoft.com/en-us/azure/active-directory/reports-monitoring/reference-reports-data-retention>
  * **Sign-in Logs** - <https://docs.microsoft.com/en-us/azure/active-directory/reports-monitoring/concept-sign-ins>

Based on this 30 day retention, Identity Intelligence will start ingestion with the last 30 days of logs.  On subsequent log collections, Identity Intelligence will ingest only the latest logs.

## Manual App Registration Setup Steps <a href="#setup-steps" id="setup-steps"></a>

This section details the manual process to create the Entra ID app registration for Identity Intelligence data collection. &#x20;

{% hint style="info" %}
You do not need to complete this section if you prefer to use the [#azure-marketplace-app-data-integration-beta-release](#azure-marketplace-app-data-integration-beta-release "mention") method detailed below.  Skip to that section.
{% endhint %}

There are 2 high-level steps you need to go through to set up your Microsoft Entra ID API key then connect it to Identity Intelligence.

1. Setup App registration with API permissions and create an app secret in Microsoft Entra ID
2. Add Entra ID API details to Identity Intelligence Dashboard

### Setup App and API secret in Microsoft Entra ID <a href="#setup-app-and-api-secret-in-azure-ad" id="setup-app-and-api-secret-in-azure-ad"></a>

Next, we will create the app in your Microsoft Entra ID tenant, assigning the correct permissions, and add an API secret.&#x20;

Add an app in your Microsoft Entra ID tenant

1. Go to ***Microsoft Entra ID...App registrations***
2. Select ***New registration***

   <figure><img src="/files/M2oQab8xKf2p3YTbRnJD" alt=""><figcaption></figcaption></figure>
3. Fill in the details for the new app

   * Name this app "Identity Intelligence Data Integration" or something similar
   * Make sure to select “*Accounts in this organizational directory only (`Your Entra ID tenant name` only – Single Tenant)*”
   * **No redirect URI is required - leave these fields blank**&#x20;

   <figure><img src="/files/n56YQ64HscpNzzVDh4jj" alt=""><figcaption></figcaption></figure>
4. Select ***Register***
5. Save the following information as it will get entered into the Identity Intelligence dashboard.
   * *Application (client) ID*
   * *Directory (tenant) ID*

<figure><img src="/files/8SXojw6E6IxCAgvFyIpj" alt="" width="563"><figcaption></figcaption></figure>

### Understanding Identity Intelligence API Permissions for Entra <a href="#add-api-permissions" id="add-api-permissions"></a>

There are two groups of API permissions sets that can be used with your Identity Intelligence tenant

* **Read-only** - used for data ingestion and analysis only
* **Read/write** (which includes the first set of read-only permissions) - read/write permissions are used for the defined list of Identity Intelligence [Remediation Actions](/understanding-your-users/remediation-actions.md). &#x20;

Remediation actions can only be taken by administrator or help desk roles in Identity Intelligence and are limited to the list in the above article.  This table outlines the relationship from remediation actions to the API permissions.&#x20;

<table><thead><tr><th width="374">Write Permission</th><th>Associated Remediation Type</th></tr></thead><tbody><tr><td><code>User.ReadWrite.All, User.ManageIdentities.All, Directory.ReadWrite.All</code></td><td>Update User Type, Delete Guest User</td></tr><tr><td><code>User.ReadWrite.All, Directory.ReadWrite.All</code></td><td>User Log out</td></tr><tr><td><code>UserAuthenticationMethod.ReadWrite.All</code></td><td>Reset MFA</td></tr><tr><td><code>User.ReadWrite.All</code></td><td>Delete Guest User</td></tr></tbody></table>

### Add API Permissions

The instructions below are shown for full read/write capabilities.  For a read-only model, please omit the read/write API permissions. &#x20;

1. Go to ***API Permissions*** under your newly created Identity Intelligence Integration app
2. Select ***Add a permission***<br>

   <figure><img src="/files/3wilnaB7oCT3CSAEWvfE" alt=""><figcaption></figcaption></figure>
3. Select ***Microsoft Graph***<br>

   <figure><img src="/files/wJjYTPwmzrVQ6rf6gZJN" alt=""><figcaption></figcaption></figure>
4. Select ***Application Permissions***
   * NOTE - Permissions to be added below must <mark style="color:red;">**ALL**</mark> be of type **Application**
5. **Read-only permissions:**  Please repeat steps 5 and 6 for all of the following permissions. See notes for details.
   * AgentCardManifest.Read.All
   * AgentInstance.Read.All
   * Application.Read.All
   * AuditLog.Read.All
   * DeviceManagementApps.Read.All (<mark style="color:red;">requires Intune license</mark>)
   * DeviceManagementConfiguration.Read.All (<mark style="color:red;">requires Intune license</mark>)
   * DeviceManagementManagedDevices.Read.All (<mark style="color:red;">requires Intune license</mark>)
   * Directory.Read.All
   * Group.Read.All
   * GroupMember.Read.All
   * IdentityRiskEvent.Read.All
   * IdentityRiskyAgent.Read.All (<mark style="color:red;">requires P2 license</mark>)
   * IdentityRiskyServicePrincipal.Read.All (<mark style="color:red;">requires P2 license</mark>)
   * IdentityRiskyUser.Read.All (<mark style="color:red;">requires P2 license</mark>)
   * MailboxSettings.Read
   * Policy.Read.All
   * Reports.Read.All
   * Synchronization.Read.All
   * User.Read.All
   * UserAuthenticationMethod.Read.All
6. **Read/write permissions** for Remediation Actions:
   * User.ReadWrite.All
   * User.ManageIdentities.All
   * Directory.ReadWrite.All&#x20;
   * UserAuthenticationMethod.ReadWrite.All
7. Once added to the list, select ***Add Permissions,*** then select ***Grant admin consent**.* Then select ***Yes***<br>

   <figure><img src="/files/JCMbYqnG3t3ZKFHg9kyX" alt=""><figcaption></figcaption></figure>

### Create Client secret <a href="#create-api-secret" id="create-api-secret"></a>

1. Go to ***Certificates & Secrets*** under your Identity Intelligence Integration app
2. Select <mark style="color:blue;">**New client secret**</mark>
3. Fill in the description, such as "Identity Intelligence Integration", and the desired Expiration timeframe for the secret, (i.e. 12 months). Select ***Add***<br>

   <figure><img src="/files/BeOcmCo7fi34SC0sbcfQ" alt=""><figcaption></figcaption></figure>
4. Save the Secret ID and Secret Value as this will be used later in the Identity Intelligence dashboard

   * Select the **copy** icon to copy and save both to a secure location
   * <mark style="color:$warning;">**Important**</mark><mark style="color:$warning;">:</mark> Once you leave this page you **WILL NOT** be able to get the secret value again. If lost, you will have to delete and create a new one

   <figure><img src="/files/tFaAqd2b7eTKjV7Uj6kM" alt=""><figcaption></figcaption></figure>
5. You can now proceed to the section [#add-azure-a-d-integration-to-oort-dashboard](#add-azure-a-d-integration-to-oort-dashboard "mention")\ <mark style="color:$warning;">Skip the subsequent section</mark> referencing the [#azure-marketplace-app-data-integration-betarelease](#azure-marketplace-app-data-integration-betarelease "mention")

## Azure Marketplace App Data Integration (Beta release)

### Notes

At the present time, when the Azure Marketplace app is updated, for example to include new API permissions for new features and data collection, an existing instance of the application in your Entra tenant is <mark style="color:$warning;">not</mark> updated.&#x20;

The app must be removed and reinstalled to obtain the latest version. &#x20;

### Pre-requisites&#x20;

* An <mark style="color:$warning;">Azure Subscription</mark> - this is separate from an Entra ID P1 or P2 license referenced above and is required for the creation of User-assigned Managed Identities and Resource Groups. &#x20;
* Azure / Entra admin permissions sufficient to&#x20;
  * Create a User-assigned Managed Identity&#x20;
  * Add a role to a Managed Identity which allows it to create App Registrations and Service Principals - Application Administrator role contains the minimum permissions required
* Azure Resource group to deploy Azure Marketplace application. Consider creating or using an  EMPTY resource group, in case of any resource group-level policies that may cause issues

### Create Managed Identity and assign Entra ID role&#x20;

1. Go to portal.azure.com&#x20;
2. Select ***Create a resource***<br>

   <figure><img src="/files/5UjipkHoVkgGOSlLaVvQ" alt=""><figcaption></figcaption></figure>
3. In the search box, enter “**user-assigned managed identity**” and select the resource to create it<br>

   <figure><img src="/files/2CadR6GjQkd8cOhujE6z" alt=""><figcaption></figcaption></figure>
4. On the creation screen, enter the following info: Subscription, Resource Group name for a new resource group, Identity name, and Region

<figure><img src="/files/7qr746oe4tfmux136ApX" alt=""><figcaption></figcaption></figure>

1. Proceed with ***Review and Create*** step. Create the managed identity.&#x20;
2. Go to Entra ID and navigate to roles<br>

   <figure><img src="/files/o2c9lvhqyY9dXMylpdNz" alt=""><figcaption></figcaption></figure>
3. In All roles, find ***Application Administrator*** role and select the <mark style="color:blue;">number</mark> in ***Assignments*** column<br>

   <figure><img src="/files/DmkaVbH34WE95o8bc1rV" alt=""><figcaption></figcaption></figure>
4. Select ***Add assignments***. Locate your managed identity by name, and it to the role. Once you have completed these steps, proceed to the instructions in the next section of the documentation<br>

   <figure><img src="/files/lShDccgc79AMLBPBbPEH" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/NI45OgnKuXs16hoV7Lmo" alt="" width="550"><figcaption></figcaption></figure>

### Install Azure Marketplace Application

1. Within Azure or Entra ID portal, select ***Create a resource***

2. Search for "**Cisco Identity Intelligence**" and select ***Entra ID Data Integration***<br>

   <figure><img src="/files/BTQilWlD8v0KPlNLn7Pe" alt=""><figcaption></figcaption></figure>

3. Select the **Free Plan** option and Create it

4. Enter all the details into the relevant input boxes as per the table and example screenshot below\ <mark style="color:$danger;">**NOTE:**</mark>  As mentioned above, the Azure Resource group specified here to deploy Marketplace offer *MUST* be empty. It cannot have other existing resources already contained within it.<br>

   <figure><img src="/files/vLhT0OJJmpjlQt5jpo8m" alt="" width="563"><figcaption></figcaption></figure>

   <figure><img src="/files/nPhiioeNPSqN9j6kyUfj" alt="" width="563"><figcaption></figcaption></figure>

5. Select **Next**

6. Enter or select the following fields accordingly, as shown in the screenshot and table below<br>

   <figure><img src="/files/jwDbVhAjWv7PZbpcRo8B" alt="" width="563"><figcaption></figcaption></figure>

<table data-header-hidden><thead><tr><th width="261" valign="top">Input Field</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top"><strong>Region</strong></td><td valign="top">Which Azure region Deployment Script should be deployed</td></tr><tr><td valign="top"><strong>App Registration Name</strong></td><td valign="top">Name of App Registration for Data Integration</td></tr><tr><td valign="top"><strong>Assign write permissions</strong></td><td valign="top">Yes or No (Recommended: Yes)<br><br>Identity Intelligence does <strong>NOT</strong> take automated write actions.  Selecting <strong>Yes</strong> grants Identity Intelligence a limited set of write permissions to Entra. If write permissions are granted, <a href="/pages/3VKjD0BCTdCDoTnXRrF4#roles">Admins or Helpdesk users</a> in Identity Intelligence can <strong>manually</strong> trigger certain remediation actions on Entra users, directly within the Identity Intelligence interface, instead of navigating back to Entra to complete the same task(e.g: log user out of active Entra sessions, reset user's MFA). <br><br>For more information on the actions available, see <a data-mention href="#add-api-permissions">#add-api-permissions</a> and  <a data-mention href="/pages/qKAN2j0zanyuw7ewCvxi#remediation-actions">/pages/qKAN2j0zanyuw7ewCvxi#remediation-actions</a></td></tr><tr><td valign="top"><strong>Tenant has Intune License</strong></td><td valign="top">Yes or No  <br>Select <strong>Yes</strong> if this Entra ID tenant has Intune Licenses. This grants Identity Intelligence <code>read</code> permissions to Device Management data. <br>Select <strong>No</strong> if this Entra ID tenant does <em>not</em> have Intune Licenses</td></tr><tr><td valign="top"><strong>Managed Identity Name</strong></td><td valign="top">User-Assigned Managed Identity name from previous section</td></tr><tr><td valign="top"><strong>Managed Identity Resource Group</strong></td><td valign="top">Resource Group name where Managed Identity is created</td></tr></tbody></table>

5. Select **Create**.  The necessary App Registration and Service Principal will be created in Entra ID and corresponding Graph API permissions will be assigned to it&#x20;

### Grant Admin Consent for Graph permissions

Now you need to grant Admin Consent to the permissions that were assigned to the app registration.

1. Navigate to Entra ID and go to ***App Registrations***&#x20;
2. Select ***All Applications*** and enter the Identity Intelligence application name that you specified during the Marketplace app creation steps above<br>

   <figure><img src="/files/N6HC2hOSfidI0ruVz4bi" alt=""><figcaption></figcaption></figure>
3. Select ***App Registration*** and go to the API Permissions pane found in the left menu
4. Select the ***Grant admin consent*** button as shown in the screenshot below<br>

   <figure><img src="/files/awMN7Gv5yAuehjyaP8TY" alt=""><figcaption></figcaption></figure>
5. The **Status** column for all API permissions listed in the table should now be shown as **Granted**. \
   \
   Once you have confirmed all the API permissions have the correct status, proceed to the next section of the documentation and follow the steps listed to create a client secret for this applications <br>

   <figure><img src="/files/UpSW9IGv463xHTqMZH9G" alt=""><figcaption></figcaption></figure>

### Create Client Secret

1. Go to the **Certificates & Secrets** pane in the left menu under your Identity Intelligence app registration
2. Select ***New client secret***<br>

   <figure><img src="/files/fDonjIsvlJmkBAgquod7" alt=""><figcaption></figcaption></figure>
3. Fill in the description using an easily recognizable and memorable name, such as "Identity Intelligence Integration". Then select the desired Expiration timeframe for the secret (recommended: 365 days/12 months) and select ***Add***
4. Select the **Copy** icon to copy both the **Secret Value** and **Secret ID** and paste this information somewhere safe, as this will be needed to complete later steps of the integration set up in Identity Intelligence\
   \ <mark style="color:$warning;">**Important**</mark><mark style="color:$warning;">:</mark> Once you leave this page you ***WILL NOT*** be able to generate the same key again. If the key is lost, you will need to delete the existing secret, create a new one and save that info

<figure><img src="/files/trDb9yItHiF1mtIXlcdJ" alt=""><figcaption></figcaption></figure>

5. After you have pasted the secret value and ID somewhere secure, proceed to the next section of the documentation to add the Entra ID integration to your Identity Intelligence tenant and complete the integration set up prcess.

## Create Microsoft Entra ID Integration in Identity Intelligence <a href="#add-azure-ad-integration-to-oort-dashboard" id="add-azure-ad-integration-to-oort-dashboard"></a>

Next, we will add the integration in the Identity Intelligence dashboard&#x20;

1. Login to the Identity Intelligence Dashboard with an Identity Intelligence Admin role
2. Using the left hand menu bar, navigate to the **Integrations** page. Select the ***Add Integration*** button&#x20;
3. Locate the Microsoft Entra ID integration tile and select the ***Add Integration*** button within that tile
4. Fill in the details for the Microsoft Entra ID Integration. Enter the values saved from earlier on in the Microsoft Entra ID setup for all fields except *Name*

   * *Name - The display name for the Entra Integration that will be used to recongize the integration throughout Identity Intelligence*&#x20;
   * *Directory ID* &#x20;
   * *Application ID*
   * *Secret ID*
   * *Secret VALUE*

   <figure><img src="/files/I44ntN7lPZ6NRUpH9H6c" alt=""><figcaption></figcaption></figure>
5. Select **Connect** to test the connectivity. This may take a few minutes to complete
6. Once the connectivity test is successful, if desired, you can then review the data types that will be collected. Otherwise, proceed to step 7
   1. Navigate to the **Advanced** tab and review the responses to the questions at the top of the page to confirm they are answered correctly based on your Entra Licensing and permissions. Adjust the responses to any questions as needed. We highly recommended keeping your integration set to **Managed** mode. To read more ahout managed data types, refere to our [Managed Integrations](/integrations/managed-integrations.md) documentation
7. Select **Save**. You will now see the integration listed on the Integrations page. Ensure that the integration's Connectivity Status is `Connected`
8. On the right hand side of the row for your Entra integration, select the **3-dot** button to open the pop-up menu. Select **Collect Now** to start the first data ingestion. You can also skip this step and it will happen automatically within the next 24 hours. &#x20;
9. If you would like to enable real-time event streaming, please continue to the [Azure Event Hub Log Streaming for Microsoft Entra ID](/integrations/azure-active-directory-event-hub-streaming.md) article to follow the steps to create an Azure Event Hub integration
10. Congratulations, you have successfully set up the Microsoft Entra ID Integration!

## Update the Microsoft Entra ID API App (client) Secret

It is critical that your Entra ID Secret for the Identity Intelligence integration does not expire. If the secret expires before it can be refreshed, Identity Intelligence will not be able to collect data from Entra until a new secret is created. If too many days lapse before a new secret can be created and assigned, Identity Intelligence will not be able to collect all the historical data and logs generated in that period, which will create gaps in your org's Entra data set.\
\
You can proactively monitor the status of your Identity Intelligence Microsoft Entra ID integration secret via the **Identity Intelligence Client Secret Expiring Soon** check within Identity Intelligence.

The default setting for this check is configured to start alerting 90 days prior to the secret's expiration date. <mark style="color:$warning;">W</mark><mark style="color:$warning;">**e**</mark><mark style="color:$warning;">**&#x20;**</mark>*<mark style="color:$warning;">**highly**</mark>*<mark style="color:$warning;">**&#x20;**</mark><mark style="color:$warning;">**recommend**</mark> [<mark style="color:$warning;">**enabling notifications on this check**</mark>](/understanding-check-failures/customizing-checks.md#notification-settings) to send alerts to the channel of your choosing (email, messaging system, webhooks) so that you can be made aware of the upcoming expiration date with sufficient notice to take the appropriate steps.&#x20;

If you app (client) secret is expiring or has expired, you must:

1. Navigate to Entra ID and **delete** the expiring/expired secret for the Identity Intelligence data integration app

* Having multiple secrets on the same app, even if expired, is not security best practice

2. Create a new app (client) secret and copy it somewhere secure as you will need it to complete later steps. Refer to the [Create Client Secret](#create-api-secret) section of this article for detailed instructions on how to make a new secret

<figure><img src="/files/cFWl3pYbqK6OS53K7iRo" alt="" width="563"><figcaption></figcaption></figure>

3. Navigate back to Identity Intelligence and go to the **Integrations** page. Locate the existing Entra integration that needs to have its app (client) secret updated
4. Select the **3-dot** menu button on the right side of the row for the desired Integration. Select **Edit Settings** from the pop up menu
   1. If you have more than one Entra integration, you can confirm which Microsoft Entra ID app registration is the correct one by comparing the Entra ID integration app (client) **ID** listed in Identity Intelligence console to the Client ID listed in Entra.&#x20;
5. Select the **Reset Credentials** button to remove the previous secret from Identity Intelligence. **Note**: This does **not** delete the Secret in Entra. You must also delete the previous secret within Entra, which the recommended best practice to avoid confusion about which secret is in use

<figure><img src="/files/GHSa3udYjnmsEmhbeAN1" alt="" width="563"><figcaption></figcaption></figure>

6. Paste the new **Secret ID** and **Secret Value** that were generated in Entra during earlier steps into the respective fields. Then select **Save**

<figure><img src="/files/cOfuIBLE0gHxxJJIBXUf" alt="" width="563"><figcaption></figcaption></figure>

7. Back on the **Integations** page, select the **3-dot** menu button for the Microsoft Entra ID integration and select **Test Connectivity** to verify the new secret is working correctly. This may take a few minutes to complete. The **Connectivity** column in the table of Integrations will change to **Connected** once the test is successful. \
   \
   If it shows a status other than Connected, it means something was configured incorrectly and you will need to repeat the steps to resolve the error.&#x20;

<figure><img src="/files/J8IR1sirZFELEg7nKiFF" alt=""><figcaption></figcaption></figure>


---

# Agent Instructions: 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 current page URL with the `ask` query parameter:

```
GET https://docs.oort.io/integrations/azure-active-directory-integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.