> For the complete documentation index, see [llms.txt](https://documentation.ardoq.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.ardoq.com/integrations/out-of-the-box-integrations/entra-id.md).

# Entra ID

Import user, group, and application data from Microsoft Entra ID.

By integrating with Microsoft Entra ID, you can import employee details—including names, email addresses, and profile images—directly into an Ardoq workspace.

Additionally, you can also import groups and applications associated with your Entra ID configuration.

## Prerequisites for Using Microsoft Entra ID with Ardoq <a href="#h_f997ed72fd" id="h_f997ed72fd"></a>

* You must be an admin of your Ardoq organization
* You must have access to Entra ID in Microsoft Azure with the permissions to create a new enterprise application

We'll be creating an enterprise application that can read user, group, and application data on behalf of Ardoq. This will require creating the application, giving it the correct permissions, and creating a client secret.

### Creating an Azure Application to Connect Entra ID to Ardoq <a href="#h_9e6525b6c5" id="h_9e6525b6c5"></a>

1. Navigate to the Azure Portal for the instance you want to connect
2. Go to the Microsoft Entra ID service
3. Go to **Manage** > **Enterprise applications**
4. Click **New application** and select **Create your own application**
5. In the dialog that follows, select the **Integrate any other application you don't find in the gallery (Non-gallery)** option
6. Name your application and save it
7. Next, go to **App registrations** in the Entra ID service menu
8. Select your application
9. In the page that follows, select **Certificates & secrets** and then the **Client secrets** tab
10. Click **New client secret**
11. Give it a name and set an expiration date
    1. **Note**: the Ardoq integration will stop working when the client secret expires and will require a new client secret
12. Next, go to the **API permissions** tab
13. Click **Add a permissions**, select **Microsoft Graph**, and then **Application permissions**
14. Search and add the following permissions:
    1. Application.Read.All
    2. Group.Read.All
    3. User.Read.All
15. Click **Add permissions**
16. Finally, click **Grant admin consent for Default Directory**

With the application ready, note down the tenant ID, client ID, and the client secret, which we will use to create the connection in Ardoq.

## Available Resources <a href="#h_a67ca69e1a" id="h_a67ca69e1a"></a>

Each of the available resources is tied to the permissions you have configured in your enterprise application connection above, and they are as follows:

* Users
* Groups
* Applications

If you do not need all the available resources, you can use more limited permissions.

### Users <a href="#h_a8b4080dfa" id="h_a8b4080dfa"></a>

Ardoq brings in all basic fields associated with persons in Entra ID including name, email, job title, office location, country, department, phone numbers, and others.

Additionally, the Entra ID integration brings in manager relationships, allowing you to structure your company hierarchy through the import.

The Group ID field brings in a comma-separated list of group IDs that the user is a member of. These can be mapped against the Group IDs in the Groups table.

Finally, Entra ID extension attributes (from 1 to 15) are also available in the integration. This will allow you to bring in your own custom attributes into Ardoq.

#### Profile Pictures <a href="#h_4ff119d7db" id="h_4ff119d7db"></a>

Profile pictures of users can be imported into Ardoq to help visualize people components. This can be done through by clicking the **Settings** button during the data selection step.

<figure><img src="https://2484004798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnlnB7uZ29iLVLzqGbCym%2Fuploads%2Fa7ECginfU2Ntr77ScXvQ%2Fimage.png?alt=media&amp;token=461d4afa-1dee-45e8-87d3-9790697f1ab5" alt=""><figcaption></figcaption></figure>

&#x20;Toggle the **Import profile pictures** option to enable the feature.

<figure><img src="https://2484004798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnlnB7uZ29iLVLzqGbCym%2Fuploads%2FAMlHLWZkhAiExl96F0dd%2Fimage.png?alt=media&amp;token=8c166a0a-dc2c-47ef-bb0a-b01f1e2c57e0" alt=""><figcaption></figcaption></figure>

​Enabling this toggle will automatically select the user ID and Display name fields because they are required for importing profile pictures.

#### User Hierarchy <a href="#h_cebc85a6b8" id="h_cebc85a6b8"></a>

All users have an ID associated with them that makes for a natural custom ID mapping. Users are also brought into the tabular importer with a field called `Manager ID`. The `Manager ID` is simply another user ID, pointing at a user's direct manager.

To build the hierarchy in Ardoq you can map the `Manager ID` column with the `Reference` type as a `Source component` with a reference type `Manages`. Set the `Format` to `Custom ID` and select the `Field name` to be the field name of your user ID column. Set the other options to your preference.

With this configuration, you are saying that the ID in the `Manager ID` column refers to the person who manages the person for the current row and creates a references called `Manages`, or in other words `Person A managed Person B`.

### Groups <a href="#h_4413172876" id="h_4413172876"></a>

Groups fields include the group name and group category, as well as group owner contact details.

Groups also contains a **Parent Group ID** that stores the ID of a particular group's parent. This way you can set up group hierarchies as well.

The Users table will contain additional fields to help mapping users to groups, specifically the **Group ID** field, which is a comma-separated list of group IDs that a particular user belongs to.

### Applications <a href="#h_965d3f0582" id="h_965d3f0582"></a>

Applications that are registered to your Entra ID platform can also be brought into Ardoq, including its App ID, its tags, and owner details.

## Pre-fetch Filtering <a href="#h_965b7076da" id="h_965b7076da"></a>

### Handling Large User Data Imports from Microsoft Entra ID <a href="#h_86e73c207c" id="h_86e73c207c"></a>

If you'd like to pull only a subset of data from Microsoft Entra ID, you can configure a pre-fetch filter to fetch specific users, groups, and applications. This can help reduce load times and prevent potential timeouts.

The filter option is available in the **Select data** step of the import under the Filters button for all tables.

{% hint style="info" %}
**Note**: Microsoft Graph API has a known limitation due to which we cannot use the `ne/NOT/endsWith` filters on fields like Manager ID, email, or name, as the request will fail.
{% endhint %}

#### Example Queries <a href="#h_8bf75bffbc" id="h_8bf75bffbc"></a>

You don't have to write out the full query notation in Ardoq — the scope of the table already defines which data will be queried. That is, you don't have to use the full format like `$filter=collection/any(property:property/subProperty eq 'value-to-match')`; it is enough to use the name of the property.

For example, applying the filter `displayName eq 'Backend Group'` on the Groups table will retrieve groups with the Display name column equal to Backend Group.

Be sure to use the ID form (in camel case) as listed in the resource selection table and not the Field name:

<figure><img src="https://2484004798-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnlnB7uZ29iLVLzqGbCym%2Fuploads%2FHlv1O5TxzkFExUV5yDg0%2Fimage.png?alt=media&amp;token=9d9a310f-1f45-4a1a-bd8f-a5cd3b88e48f" alt=""><figcaption></figcaption></figure>

### Naming Conventions in the Microsoft Graph API <a href="#h_c1aca5f3fb" id="h_c1aca5f3fb"></a>

The user-facing Microsoft resources do not always have matching names when using filter queries. If you wish to filter specific tables exposed by the integration, refer to the following names and query patterns:

* Enterprise Applications: `WindowsAzureActiveDirectoryIntegratedApp`
  * E.g.: `tags/any(t:t eq 'WindowsAzureActiveDirectoryIntegratedApp')`
* Managed Identities: `servicePrincipalType eq 'ManagedIdentity'`
* Microsoft Applications: `appOwnerOrganizationId eq f8cdef31-a31e-4b4a-93e4-5f571e91255a`