> For the complete documentation index, see [llms.txt](https://docs.elimity.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.elimity.com/ms-entra-pim-azure-resources/step-by-step-deployment-guide.md).

# Step-by-step deployment guide

The Microsoft Entra PIM for Azure resources connector for Elimity Insights fetches Privileged Identity Management data for Azure role-based access control (Azure RBAC).

### Microsoft Entra PIM for Azure resources

The Microsoft Entra PIM for Azure resources connector for Elimity Insights fetches Privileged Identity Management data for Azure roles — Azure role definitions, active role assignments, and eligible (not-yet-activated) role assignments, together with the management group, subscription, resource group or resource they apply to — so you can keep control over privileged access to your Azure resources. Follow the instructions below to set up the connector.

{% hint style="info" %}
This connector covers **Azure roles** (e.g. Owner, Contributor, Reader on a subscription). For Entra directory roles (e.g. Global Administrator) use the [Microsoft Entra PIM Roles](https://docs.elimity.com/ms-entra-pim-roles/step-by-step-deployment-guide) connector; for PIM-managed group memberships use the [Microsoft Entra PIM Groups](https://docs.elimity.com/ms-entra-pim-groups/step-by-step-deployment-guide) connector.
{% endhint %}

#### 1. Which data is imported

The following entity types are imported:

* **Principals** — the users, groups, and service principals that hold or are eligible for an Azure role
* **Roles** — Azure role definitions, built-in and custom (e.g. Owner, Contributor, Reader)
* **Role Assignment Schedule Instances** — *active* PIM role assignments (permanently assigned or currently activated)
* **Role Eligibility Schedule Instances** — *eligible* (not-yet-activated) PIM role assignments

Rather than linking principals to roles directly, each PIM grant is modelled as its own entity (the *schedule instance*). A single principal-role pair can carry state a plain link can't hold — the scope it applies to, its start/end window, how it was granted (direct, inherited, or via a group), and whether it's active or merely eligible. Each instance sits between a Principal and a Role and carries that context as attributes, letting Elimity model just-in-time and time-bound access as a standard identity graph.

{% code overflow="wrap" %}

```mermaid
graph TD;Principal[Principal]; Role[Role]; Assignment[Role Assignment Schedule Instance]; Eligibility[Role Eligibility Schedule Instance];Principal --> Assignment; Principal --> Eligibility; Assignment --> Role; Eligibility --> Role;
```

{% endcode %}

Attributes imported per entity type:

**Principal** — Email, Type (User, Group, ServicePrincipal, ForeignGroup, or Device)

**Role** — Description, Type (BuiltInRole or CustomRole)

**Role Assignment Schedule Instance** — Principal, Role, Assignment type (Assigned or Activated), Type, Member type (Direct/Inherited/Group), Condition, Scope ID, Scope name, Scope type (tenant / managementgroup / subscription / resourcegroup / resource), Start time, End time, Status

**Role Eligibility Schedule Instance** — the same attributes, except Assignment type

Schedule instances are imported for every scope in your tenant: the root scope (`/`), the root management group and every management group, subscription, resource group and resource below it. The Azure resources themselves are not imported as entities: each schedule instance carries the scope it applies to in its Scope ID, Scope name and Scope type attributes.

{% hint style="info" %}
Roles are read at the root management group. A custom role that can only be assigned on a lower scope (e.g. a single subscription) is therefore not imported as a Role; the schedule instances for that role still show its name in their Role attribute.
{% endhint %}

#### 2. Creating a dedicated app registration in Entra ID

As usual we recommend creating a dedicated account for this connector. Follow the steps below to set up a new app registration in Entra ID:

1. In Azure, open your tenant's app registrations by typing 'app registrations' in the global search bar and clicking the **App registrations** service.
2. Click the **New registration** button.
3. Choose a name for this registration (e.g. `elimity-insights-pim-azure-resources`).
4. Leave the defaults for 'Supported account types' and 'Redirect URI' and click **Register**.

Note down both the **client identifier** and the **tenant identifier** for this new app registration.

#### 3. Generating credentials for the new app registration

The connector authenticates as the app registration using a client secret. Click **Certificates & secrets** in the menu on the left and add a new client secret. Immediately note down the **value** of your new secret (Entra shows it only once). Note the secret's expiry date: imports fail once it expires, so plan to rotate it.

#### 4. Granting read access to the root management group

Grant the app registration read access to your tenant's root management group:

1. Temporarily elevate your Global Administrator access to manage the root management group (refer to [the official documentation](https://learn.microsoft.com/en-us/azure/role-based-access-control/elevate-access-global-admin?tabs=azure-portal%2Centra-audit-logs#step-1-elevate-access-for-a-global-administrator) for detailed instructions).
2. Open the overview of your tenant's management groups by typing 'management groups' in the global search bar and clicking the **Management groups** service.
3. Click the **Tenant Root Group** and then click **Access control (IAM)** in the side navigation menu.
4. Click **Add** in the top-left corner of the main content panel, and select **Add role assignment**.
5. Select the **Reader** role and click **Next**.
6. Click **Select members**, search for your newly created app registration, select it and click **Next** again.
7. Click **Review + assign**.
8. Remove your elevated Global Administrator access again.

The connector always reads from the tenant root management group (its identifier equals your tenant identifier); a Reader assignment on a lower management group or subscription is not enough.

#### 5. Creating a source in Elimity Insights

1. Go to **Sources** in the left navigation bar and click **Add Source**.
2. Search for **Custom** and click **Set Up**.
3. Click **Set Up** again and give the source a name (e.g. `Microsoft Entra PIM for Azure resources`).
4. Select **Upload export file**, click **Continue**, and upload the data model file: `data-model-export.json`.
5. Open the **Config** tab and click **Edit**.
6. Set **Enable automatic imports via custom gateway** to `true` and fill in the **Gateway URL**: [`https://microsoft-entra-pim-gateway-75801044224.europe-west1.run.app`](https://microsoft-entra-pim-gateway-75801044224.europe-west1.run.app).
7. Click **Add configuration value** and add the entries below. Keys are case-sensitive.
8. Click **Save and run** to launch your first import. The **Imports** tab shows the summary for each run.

{% file src="/files/Aa9m1VTgtX2QwDSH8Ajr" %}

| Configuration option | Key            | Description                                                         |
| -------------------- | -------------- | ------------------------------------------------------------------- |
| Tenant ID            | `tenantId`     | Tenant identifier you noted down in step 2.                         |
| Client ID            | `clientId`     | Client identifier you noted down in step 2.                         |
| Client secret        | `clientSecret` | Client secret value you noted down in step 3 (store as a password). |

***


---

# 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.elimity.com/ms-entra-pim-azure-resources/step-by-step-deployment-guide.md?ask=<question>&goal=<user_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.