> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/getting-started-guide/lifecycle/import-users-and-memberships.md).

# Import users and group memberships

Import existing Active Directory users and their group memberships into OpenIAM.

**Goal:** the users from your POC OU exist in OpenIAM with their AD group memberships attached. Still read-only.\
**Time:** 30–45 minutes.\
**Prerequisites:** groups imported ([Import AD groups](/getting-started-guide/lifecycle/import-groups.md)).

## Before you clone: the one flag that matters

The shipped example **AD Powershell USER Example** ships with **Provision to target systems enabled** (`IS_PROVISION = Y`). That means a naive run doesn't just import users — it evaluates them for provisioning to downstream systems. For a first, read-only import you will turn this **off** and re-enable provisioning deliberately on the next page.

{% stepper %}
{% step %}
**Clone the shipped example**

In **Provisioning → Synchronization**, copy **AD Powershell USER Example** (or create a new configuration, copy-pasting the Groovy paths exactly), leaving the shipped example untouched:

| Setting                         | Value                                                                     |
| ------------------------------- | ------------------------------------------------------------------------- |
| Synchronization source          | CONNECTOR                                                                 |
| Managed system                  | your AD managed system                                                    |
| Object / type                   | USER / FULL                                                               |
| Query                           | see step 2                                                                |
| Validation rule                 | `/sync/user/ad/ADPowerShellValidation.groovy`                             |
| Transformation                  | Transformation Script → `/sync/user/ad/ADPowerShellTransformation.groovy` |
| Matching                        | IDM field `PRINCIPAL` ↔ source attribute `SamAccountName`                 |
| Attribute names lookup          | `/sync/user/ad/ADPowerShellAttributes.groovy`                             |
| **Provision to target systems** | **Change to No** (ships as Yes — see above)                               |

What the transformation does with each user: maps name/title/employee ID fields, derives organization and department, sets status from the AD `Enabled` flag and `userAccountControl`, resolves the `Manager` DN to an OpenIAM supervisor (retrying on the next run if the manager isn't imported yet), creates a login from `sAMAccountName`, assigns the default **End User** role, and — the part you're here for — turns each `memberOf` DN into an OpenIAM group membership by matching distinguished names against the groups you imported in [Import AD groups](/getting-started-guide/lifecycle/import-groups.md).
{% endstep %}

{% step %}
**Scope the query and request memberships**

{% code overflow="wrap" %}

```powershell
Get-ADUser -Filter * -SearchBase 'OU=Users,OU=OpenIAM-POC,DC=yourdomain,DC=local' -Properties memberOf,Manager,mail,Department,Title
```

{% endcode %}

{% hint style="warning" %}
`memberOf` is **not** in `Get-ADUser`'s default attribute set — if you don't request it, users import fine and memberships silently don't. `Manager` likewise. Test the query verbatim in PowerShell on the connector host first.
{% endhint %}
{% endstep %}

{% step %}
**Run and verify**

Run the sync and watch `openiam-cli log synchronization`. Then:

1. **Count**: users in Webconsole User Admin search vs `(Get-ADUser -Filter * -SearchBase '<OU>').Count`.
2. **Memberships**: open a user who belongs to 2+ AD groups and confirm the same groups appear on their OpenIAM profile.
3. **Status**: a disabled AD test user should show as disabled in OpenIAM.
4. **Manager**: a user with a `Manager` link should show the supervisor (run the sync twice if managers imported after their reports).
5. **Idempotency**: re-run; counts unchanged.
6. **The safety check**: confirm no operations were sent to AD — the connector log on the Windows host should show only search activity, and no object in the POC OU should have a fresh `whenChanged` from the sync window.
   {% endstep %}
   {% endstepper %}

## If it failed

| Symptom                                  | Likely cause                                                                   |
| ---------------------------------------- | ------------------------------------------------------------------------------ |
| Users import, memberships missing        | `-Properties memberOf` absent from the query, or groups weren't imported first |
| Some users skipped                       | Validation script rejections — check the sync log for per-record reasons       |
| Downstream/provisioning activity in logs | You missed the Provision-to-target flag — stop, fix, investigate what was sent |
| Duplicate logins                         | Re-check matching (`PRINCIPAL` ↔ `SamAccountName`)                             |

## You know this worked when…

{% hint style="success" %}
User count matches, a spot-checked user shows correct memberships/status/manager, re-run is idempotent, and the connector log shows reads only. Record counts and the spot-check user.
{% endhint %}

Next: [Provision a test account to AD](/getting-started-guide/lifecycle/provision-test-account.md).


---

# 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.openiam.com/getting-started-guide/lifecycle/import-users-and-memberships.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.