---
title: Microsoft Entra ID
aliases: ["/docs/azure-ad/"]
---
runZero integrates with Microsoft ((Entra ID)) (formerly ((Azure AD))) to allow you to sync and enrich your asset inventory, as well as gain visibility into Entra ID users and groups. Adding your Entra ID data to runZero makes it easier to find assets that are not part of your domain.
Note that Entra ID is still referred to as Azure AD within the runZero product.
## Getting started {#azure-ad-getting-started}
To set up the Entra ID integration, you'll need to:
1. Configure Entra ID to allow API access through runZero.
2. Add the Entra ID credential in runZero.
3. Choose whether to configure the integration as [a scan probe or connector task](integrations-inbound.md#integration-probe-connector).
4. Activate the Entra ID integration to sync your data with runZero.
## Requirements {#azure-ad-requirements}
Before you can set up the Entra ID integration, make sure you have access to the Microsoft Azure portal.
## Step 1: Register an Azure application for Entra ID API access {#azure-ad-api-access}
runZero can authenticate to the Entra ID API using either a username and password or a client secret. Register an application to configure Entra ID API access.
1. Sign in to the Microsoft Azure portal.
2. Go to _App registrations_ and click _+ New registration_.
* Provide a name.
* Select the supported account types.
* Optionally add a redirect URI.
3. Click _Register_ to register the application.
4. Once the application is created, go back to the main Azure portal page and select _App registrations_. You should be able to find the application you just registered. (It may help to select the _Owned applications_ tab.) Click on the app's name
5. You should see the an overview of the app registration. Note the following information:
* Application (client) ID
* Directory (tenant) ID
6. Click on the display name of the application to go to its management pages.
7. Select the _Manage > Authentication_ section on the left. Set **Allow public client flows** to _Yes_ and then save the configuration.
8. Go to _API permissions_ and click _+ Add a permission_.
9. Select _Microsoft Graph_ from the list of Microsoft APIs.
10. Select the correct permissions type for your needs:
* **Username & password**: select _Delegated permissions_
* **Client secret**: select _Application permissions_
11. Search for and select the following required permissions:
* _Device.Read.All_
* _Group.Read.All_
* _User.Read.All_
12. Click _Add permissions_ to save the permissions to the application.
13. Click _Grant admin consent_ to grant consent for the permissions to the application.
14. If using a client secret, also perform the following steps:
* Navigate to _Azure Active Directory > App registrations_ and select the application you created.
* Go to _Certificates & secrets_ and click on _New client secret_.
* Enter a description.
* Select the expiration.
* Click _Add_ to create the client secret and save the client secret value.
## Add the Entra ID credential to runZero {#azure-ad-credential}
### Step 2a: Add an Azure Username & Password credential to runZero {#azure-ad-credential-userpass}
1. Go to the [Credentials page](https://console.runzero.com/credentials/new) in runZero and click _Add Credential_.
2. Provide a name for the credential, like `Azure Username & Password`.
3. Choose _Azure Username & Password_ from the list of credential types.
4. Provide the following information:
* **Azure application (client) ID** - The unique ID for the registered application. This can be found in the Azure portal if you go to _App registrations_ and select the application.
* **Azure directory (tenant) ID** - The unique ID for the tenant. This can be found in the Azure portal if you go to _App registrations_ and select the application.
* **Azure username** - The username for your Azure cloud account. This cannot be a federated user account.
* **Azure password** - The password for your Azure cloud account.
5. If you want other organizations to be able to use this credential, select the _Make this a global credential_ option. Otherwise, you can configure access on a per organization basis.
6. Save the credential. You're now ready to set up and activate the connection to bring in data from Azure.
### Step 2b: Add an Azure Client Secret credential to runZero {#azure-ad-credential-clientsecret}
This type of credential can be used to sync all resources in a single directory (across multiple subscriptions).
1. Go to the [Credentials page](https://console.runzero.com/credentials/new) in runZero and click _Add Credential_.
2. Provide a name for the credential, like `Azure Client Secret`.
3. Choose _Azure Client Secret_ from the list of credential types.
4. Provide the following information:
* **Azure application (client) ID** - The unique ID for the registered application. This can be found in the Azure portal if you go to _App registrations_ and select the application.
* **Azure client secret** - To generate a client secret, go to _App registrations_, select your application, go to _Certificates & secrets_ and click on _+ New client secret_.
* **Azure directory (tenant) ID** - The unique ID for the tenant. This can be found in the Azure portal if you go to _App registrations_ and select the application.
* Select the **Access all subscriptions in this directory (tenant)** option to sync all resources in your directory. Otherwise, specify the Azure subscription ID - The unique ID for the subscription that you want to sync. This can be found in the Azure portal if you go to _Subscriptions_ and select the subscription.
5. If you want other organizations to be able to use this credential, select the _Make this a global credential_ option. Otherwise, you can configure access on a per organization basis.
6. Save the credential. You're now ready to set up and activate the connection to bring in data from Azure.
## Step 3: Choose how to configure the Entra ID integration
The Entra ID integration can be configured as either a [scan probe or a connector task](integrations-inbound.md#integration-probe-connector). Scan probes gather data from integrations during scan tasks. Connector tasks run independently from either the cloud or one of your Explorers, only performing the integration sync.
## Step 4: Set up and activate the Entra ID integration to sync data
After you add your Entra ID credential, you'll need to set up a connector task or scan probe to sync your data.
### Step 4a: Configure the Entra ID integration as a connector task
A connection requires you to set a schedule and choose a site. The schedule determines when the sync occurs, and the site determines where any new Entra ID-only assets are created.
1. Activate a [connection to Entra ID](https://console.runzero.com/ingest/azuread). You can access all available third-party connections from the [integrations page](https://console.runzero.com/integrations), your [inventory](https://console.runzero.com/inventory), or the [tasks page](https://console.runzero.com/tasks).
2. Choose the credential you added earlier. If you don't see the credential listed, make sure it has access to the organization you are currently in.
3. Optionally provide a filter following the [Microsoft Graph API filter syntax](https://learn.microsoft.com/en-us/graph/filter-query-parameter?tabs=http). We will only import devices that match the filter.
4. Enter a name for the task, like `Entra ID sync`.
5. Schedule the sync. A sync can be set to run on a recurring schedule or run once. The schedule will start on the date and time you have set.
6. Under **Task configuration**, choose the site you want to add your assets to.
7. If you want to exclude assets that have not been scanned by runZero from your integration import, switch the **Exclude unknown assets** toggle to _Yes_. By default, the integration will include assets that have not been scanned by runZero.
8. If you want to include assets in your integration import that the Entra ID account has marked as inactive, switch the **Include inactive assets** toggle to _Yes_. By default, the integration will not include assets that are marked as inactive.
9. Activate the connection when you are done. The sync will run on the defined schedule. You can always check the [Scheduled tasks](https://console.runzero.com/tasks) to see when the next sync will occur.
### Step 4b: Configure the Entra ID integration as a scan probe
1. Create a new scan task or select a future or recurring scan task from your [Tasks page](https://console.runzero.com/tasks).
2. Add or update the scan parameters based on any additional requirements.
3. On the Probes and SNMP tab, choose which additional probes to include, set the **Azure AD** toggle to _Yes_, and change any of the default options if needed.
4. On the Credentials tab, set the **Azure AD** toggle for the credential you wish to use to _Yes_.
5. Click _Initialize scan_ to save the scan task and have it run immediately or at the scheduled time.
## Step 5: View Entra ID assets
After a successful sync, you can [go to your inventory](https://console.runzero.com/inventory) to view your Entra ID assets. These assets will have an Active Directory icon listed in the _Source_ column.
To filter by Entra ID assets, consider running the following queries:
* [View all Entra ID assets](https://console.runzero.com/inventory?search=source%3Aazuread):
```
source:azuread
```
* [View runZero assets not connected to Entra ID](https://console.runzero.com/inventory?search=source%3Arunzero%20and%20not%20source%3Aazuread):
```
source:runzero AND NOT source:azuread
```
Click into each asset to see its individual attributes. runZero will show you the attributes returned by Entra ID.
The Entra ID integration provides details about users and groups in addition to enriching asset inventory data. Go to Inventory > Users or Inventory > Groups to view the data provided by Entra ID.
## Filtering Entra ID assets {#azure-ad-filtering}
An optional filter can be applied to Entra ID integration tasks. runZero uses Microsoft Graph `$filter` query paramater to filter assets. GraphQL follows the syntax ` [operator] `. Multiple expressions can be combined for more complex filtering by adding an `and` or `or` between expressions.
### Properties {#azure-ad-filtering-properties}
Any property that runZero imports from Entra ID can be used to apply a filter. The following are some examples.
| Entra ID Property | runZero Attribute | Description | Example |
| ------------------------ | ----------------------------------- | -------------------------------------------------- | ------------------- |
| `displayName` | @azuread.dev.displayName | The hostname of the device | EXPLORER-01 |
| `operatingSystem` | @azuread.dev.operatingSystem | The operation system of the device | Windows |
| `operatingSystemVersion` | @azuread.dev.operatingSystemVersion | The version of the specified operoating system | 10.0.x |
| `manufacturer` | @azuread.dev.manufacturer | The manufacturer of the device | Dell Inc. |
| `model` | @azuread.dev.model | The model of the device | Precision 3560 |
| `isManaged` | @azuread.dev.isManaged | Boolean value specifying whether device is managed | true, false |
| `managementType` | @azuread.dev.managementType | Description of how the device is managed | MDM, MicrosoftSense |
| `deviceOwnership` | @azuread.dev.deviceOwnership | Description of who owns the device | Company, Personal |
### Operators {#azure-ad-filtering-operators}
The following are common operators that can be used in an Entra ID filter.
- Equal to (`eq`)
- Not equal to (`ne`)
- Has (`has`)
- Less than (`lt`)
- Greather than (`gt`)
- Less than or equal to (`le`)
- Greater than or equal to (`ge`)
The following are common functions that can be used in an Entra ID filter. Functions follow the syntax `function(, )`.
- Starts with (`startswith`)
- Ends with (`endswith`)
### Example Filters {#azure-ad-filtering-examples}
The following are examples of filters that can be applied to an Entra ID integration.
| Search Filter | Description |
| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------|
| `not(startsWith(operatingSystem, 'Android'))` | Import all assets except those with an Android operating system |
| `not(operatingSystem eq 'iOS') and not(operatingSystem eq 'iPad')` | Import all assets execpt those with an iOS or IPad operating system |
| `startswith(displayName, 'PROD')` | Import all devices with a hostname that starts with PROD |
| `not(startswith(displayName, 'DEV'))` | Import all devices except those with a hostname that starts with DEV |
| `deviceOwnership eq 'Company' or isManaged eq true` | Import all devices that are owned by company or that are configured as managed devices |
For more information about filter syntax and additional examples, check [Microsoft's Graph API documentation](https://learn.microsoft.com/en-us/graph/filter-query-parameter).
## Troubleshooting {#azure-ad-troubleshooting}
If you are having trouble using this integration, the questions and answers below may assist in your troubleshooting.
### Why is the Azure Active Directory integration unable to connect?
1. Are you getting any data from the Entra ID integration?
* Make sure to query the inventory rather than look at the task details to review all the data available from this integration.
* In some cases, integrations have a configuration set that limits the amount of data that comes into the runZero console.
2. Some integrations require very specific actions that are easy to overlook. If a step is missed when setting up the integration, it may not work correctly. Please review this documentation and follow the steps exactly.
3. If the Entra ID integration is unable to connect be sure to check the task log for errors. Some common errors include:
* 500 - server error, unable to connect to the endpoint
* 404 - hitting an unknown endpoint on the server
* 403 - not authorized, likely a credential issue
### How do I solve the following Entra ID errors?
* `(invalid_client) AADSTS7000218: The request body must contain the following parameter: 'client_assertion' or 'client_secret'`
1. This error can be corrected by enabling **Allow Public Client Flows** in Entra ID. This can be accomplished by entering the Application details page under _Authentication > Advanced Settings_. From here you can toggle the **Allow Public Client Flows** setting to _Yes_.
2. It can also be helpful to ensure that application permissions were granted correctly when registering the Azure application for Entra ID API access. To do this, navigate to the API permissions settings page and ensure that each of the API/Permissions have the _type_ set to _application_. Also make sure that the permission granted is _Grant Admin Consent for Default Directory_.
* `failed to get Entra ID groups: invalid response: 403 (403 Forbidden)`
This error is likely due to an issue with credentials. Please review the documentation and check your credentials to ensure everything was entered correctly and no steps were accidentally skipped.