> 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-groups/v2.0.0/step-by-step-deployment-guide.md).

# Step-by-step deployment guide

The Microsoft Entra PIM Groups connector for Elimity Insights fetches Privileged Identity Management data for groups.

### Microsoft Entra PIM Groups

The Microsoft Entra PIM Groups connector for Elimity Insights fetches Privileged Identity Management data for **groups** — which principals hold, or are eligible for, member/owner access to PIM-enabled groups — from Microsoft Entra ID. Follow the instructions below to set up the connector.

{% hint style="info" %}
This connector covers **PIM for Groups** (member/owner access to PIM-enabled groups). 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 Azure roles on management groups, subscriptions and resources use the [Microsoft Entra PIM for Azure resources](https://docs.elimity.com/ms-entra-pim-azure-resources/step-by-step-deployment-guide) connector; for access packages use the [Microsoft Entra ID Governance](https://docs.elimity.com/ms-entra-id-governance/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 group access
* **Groups** — the Entra groups that carry PIM assignments/eligibilities
* **Group Assignment Schedule Instances** — *active* PIM group assignments
* **Group Eligibility Schedule Instances** — *eligible* (not-yet-activated) PIM group assignments

Each PIM grant is modelled as its own entity (the *schedule instance*) sitting between a Principal and a Group. It carries the context a plain link can't hold — the access role (member or owner), how it was granted (direct or via a nested group), its start/end window, and whether it's active or merely eligible.

{% code overflow="wrap" %}

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

{% endcode %}

Attributes imported per entity type:

**Principal** — Type (User, Group, or Service Principal)

**Group** — Created, Description

**Group Assignment Schedule Instance / Group Eligibility Schedule Instance** (identical) — Principal name, Group, Access (member / owner), Type, Membership (Direct / nested group), Start time, End time, Status (Active / Expired)

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

As usual we recommend creating a dedicated account for this connector.

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 **New registration**.
3. Choose a name for this registration (e.g. `elimity-insights-pim-groups`).
4. Leave the defaults for 'Supported account types' and 'Redirect URI' and click **Register**.

Note down both the **client identifier** and the **tenant identifier**.

#### 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** (Entra shows it only once).

#### 4. Granting read permissions to the Graph API

Click **API permissions** and add these **Microsoft Graph → Application permissions**, then grant admin consent:

* `PrivilegedAssignmentSchedule.Read.AzureADGroup` — read active PIM group assignments
* `PrivilegedEligibilitySchedule.Read.AzureADGroup` — read eligible PIM group assignments
* `Directory.Read.All` — enumerate all groups and resolve principal/group display names

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

1. Go to **Sources** → **Add Source** → search **Custom** → **Set Up**.
2. Click **Set Up** again and name the source (e.g. `Microsoft Entra PIM Groups`).
3. Select **Upload export file**, click **Continue**, and upload `data-model-export.json`.
4. Open the **Config** tab, click **Edit**, set **Enable automatic imports via custom gateway** to `true`, and fill in the **Gateway URL**: [`https://pim-entra-groups-gateway-1027270379075.europe-west1.run.app`](https://pim-entra-groups-gateway-1027270379075.europe-west1.run.app).
5. Set **SDK version** to `2`.
6. Click **Add configuration value** and add the four entries below.
7. Click **Save and run**. Monitor the **Logs** tab — this connector logs its progress as it probes the groups (see 5.1); the **Imports** tab shows the per-run summary.

{% hint style="warning" %}
This version of the gateway only supports SDK version 2. With SDK version 1, the import fails before any data is retrieved.
{% endhint %}

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

| Configuration option    | Key (type exactly this)   | Description                                                                                         |
| ----------------------- | ------------------------- | --------------------------------------------------------------------------------------------------- |
| Tenant ID               | `Tenant ID`               | Tenant identifier from step 2.                                                                      |
| Application ID          | `Application ID`          | Client identifier from step 2.                                                                      |
| Application Secret      | `Application Secret`      | Client secret value from step 3.                                                                    |
| Request Timeout Seconds | `Request Timeout Seconds` | The longest one request to the gateway may take, in seconds (type `Text`). At least `120`. See 5.1. |

#### 5.1 How the import is split

The gateway imports the tenant in several short requests instead of one long one. The first request lists the tenant's groups; the next requests, the **parts**, probe the groups for PIM assignments and eligibilities, 8 at a time, until all groups are done.

`Request Timeout Seconds` is a hard limit on every one of those requests. A part stops starting new groups once the time left is shorter than its groups have taken so far, and stops whatever is still running 10 seconds before the limit: what finished is imported, and the rest is handed on to the next part. A group only sends its data once it is complete, so a stopped group never leaves partial data behind.

Set it **below the request limits of the platform the gateway runs on**:

* **Google Cloud Run**: below the service's request timeout, and at least a minute under it.
* **Azure Container Apps**: at most the container app's `terminationGracePeriodSeconds`. The gateway sends a log line at least every 30 seconds, so the ingress never ends a request for being idle.

See [How imports are split](https://docs.elimity.com/technical-guides/gateways-and-import-agents/how-imports-are-split) for the platform settings in detail. This gateway always runs as one chain; it has no `parallel` value.

The logs show one summary line per part, for example `Part 1: 82 group(s) in 110 s, stopped at the request timeout of 120 s with 1 in flight (82/132 probed); 50 left for part 2.`, and a final `Import complete: ...` line.

#### 6. Troubleshooting

**`Invalid configuration: Request Timeout Seconds is required`**

The `Request Timeout Seconds` configuration value is missing. Add it (type `Text`, for example `300`), see step 5.

**`Invalid configuration: Request Timeout Seconds must be at least 120, not ...`** or **`... must be a whole number of seconds, not ...`**

Fix the value: a whole number of seconds, at least `120`.

**`No group finished within the request timeout of ... s (the first was ...)`**

Not a single group could finish within `Request Timeout Seconds`, usually because Microsoft Graph is throttling the app registration. Raise `Request Timeout Seconds`, keeping it within the request limits of the platform the gateway runs on.

**`Listing the tenant's groups took longer than the request timeout ...`**

The first request could not list all groups of the tenant in time. Raise `Request Timeout Seconds`.

***

<br>


---

# 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-groups/v2.0.0/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.
