Users

---
name: "cipp-users"
description: "The full multi-tenant M365 user lifecycle in CIPP: create/edit/disable, password and MFA resets, session revocation, the bundled offboarding call, BEC investigation reports, MFA gap reporting, and device/group lookups — plus the ordering constraints that make each sequence correct."
when_to_use: >-
  When creating, editing, disabling, offboarding, or auditing M365 users via CIPP — including
  password resets, MFA resets, session revocation, BEC checks, and MFA enrollment reports. Use
  when: cipp user, create m365 user, disable user, offboard user, reset password, reset mfa,
  revoke sessions, bec check, mfa status, user devices, user groups, m365 offboarding, or business
  email compromise.
---

# CIPP User Management

User management is the highest-volume MSP workflow against CIPP. Every step of the M365 user lifecycle — onboarding, role changes, security incidents, offboarding — has a dedicated tool. Most calls require `tenantFilter`; resolve it via `cipp_list_tenants` before you start.

## Anti-triggers

- **Mailbox-side work during an offboard** — delegate/full-access
  audits, out-of-office, and forwarding are Exchange operations with
  their own tools; use `cipp-mailboxes`. (`cipp_offboard_user` bundles
  OOO and forwarding, but only as offboarding parameters.)
- **A single tenant you hold direct credentials for** — CIPP routes
  through a CSP/GDAP delegation and needs `tenantFilter` on every call.
  Direct Graph work against one tenant is the `m365` plugin
  (`Microsoft 365 Users`) or `microsoft-graph-querying`.
- **Reading who exists for a governance or baseline review** — that is
  read-only identity inventory, not administration; use
  `inforcer-identity-governance`.
- **Creating or auditing the groups themselves** — this skill only
  reads a user's memberships (`cipp_list_user_groups`); use
  `cipp-groups`.
- **A "user" in a security or training console** — Blumira users are
  console operators and KnowBe4 users are training enrollees; neither
  is an Entra identity and neither is administered through CIPP. Use
  `blumira-users` or `knowbe4-users`.

## Tool surface

### Listing & lookup

```
cipp_list_users(tenantFilter='contoso.onmicrosoft.com')
cipp_list_mfa_users(tenantFilter='contoso.onmicrosoft.com')
cipp_list_user_devices(tenantFilter=..., userId='upn-or-objectId')
cipp_list_user_groups(tenantFilter=..., userId='upn-or-objectId')
```

`cipp_list_mfa_users` is the fastest way to find users without strong auth methods registered. Use it for security posture reviews and for bulk MFA enrollment campaigns.

### Lifecycle

```
cipp_create_user(tenantFilter, displayName, userPrincipalName, mailNickname, password,
                 firstName?, lastName?, jobTitle?, department?, usageLocation?)

cipp_edit_user(tenantFilter, userId, displayName?, jobTitle?, department?, ...)

cipp_disable_user(tenantFilter, userId)
```

`usageLocation` (ISO 2-letter country code) must be set before any license can be assigned — set it at create time even if licensing comes later.

### Security actions

```
cipp_reset_password(tenantFilter, userId, password?)        # password optional → CIPP generates one
cipp_reset_mfa(tenantFilter, userId)                        # clears all registered MFA methods
cipp_revoke_sessions(tenantFilter, userId)                  # invalidates all active tokens
cipp_bec_check(tenantFilter, userId)                        # BEC investigation report
```

`cipp_bec_check` runs a Business Email Compromise investigation: inbox rules, recent sign-in locations, MFA changes, mailbox forwarding rules, suspicious app consents. Always the first call when a user reports a phishing-related compromise — before disabling the account, while session telemetry is still live.

### Full offboarding

```
cipp_offboard_user(tenantFilter, userId,
                   convertToShared?, removeLicenses?,
                   removeFromGroups?, forwardingAddress?,
                   outOfOfficeMessage?, ...)
```

This single call wraps the canonical CIPP offboarding sequence: disable, revoke sessions, optional license reclaim, optional shared-mailbox conversion, optional forwarding, optional OOO message, group removal. Prefer this over chaining `disable_user` + `revoke_sessions` manually unless you need step-by-step control (in which case use the `user-offboarding-runner` agent).

## Workflow patterns

### Suspected BEC compromise

1. `cipp_bec_check` — capture the forensic snapshot before changing anything
2. `cipp_revoke_sessions` — kick the attacker out of all active sessions
3. `cipp_reset_password` — generate a strong password, share via secure channel
4. `cipp_reset_mfa` — clear attacker-registered methods; user re-enrolls
5. Review the BEC report for inbox forwarding rules and remove them

### Standard offboarding

Use `cipp_offboard_user` with the org's policy defaults. For high-trust environments, do a dry-run review first:

1. `cipp_list_user_groups` — note group memberships (audit trail)
2. `cipp_list_user_devices` — flag company-owned devices for retrieval
3. Check `cipp_list_mailbox_permissions` on the user's mailbox (delegates may exist)
4. `cipp_offboard_user` with `convertToShared=true`, `removeLicenses=true`, `forwardingAddress=manager-upn`

### MFA gap report

```
mfa_users = cipp_list_mfa_users(tenantFilter='allTenants')
gaps = [u for u in mfa_users if not u.get('mfaRegistered')]
```

Use this monthly across the portfolio to drive MFA enforcement campaigns.

## Identifying a user

`userId` accepts either the Azure AD object GUID or the userPrincipalName. UPN is more readable; GUID is more stable across UPN changes. CIPP returns both — pick one and stay consistent within a workflow.