entra-id-administration

name	Entra ID Administration
description	Deep expertise in Microsoft Entra ID (Azure AD) tenant administration via Microsoft Graph API v1.0 and beta — user lifecycle (create, update, disable, bulk import, restore), group management (M365/Security/Dynamic), directory role assignments, Privileged Identity Management (PIM eligible and active assignments, role activation, approval workflows), authentication methods admin (MFA, FIDO2, passwordless, SSPR), admin unit scoped delegation, B2B guest invitations and external collaboration settings, license assignment (direct and group-based), named locations, entitlement management (access packages and catalogs), and access reviews.
allowed-tools	["Read","Write","Edit","Glob","Grep","Bash"]
triggers	["entra id admin","azure ad admin","create user","disable user","bulk import users","user provisioning","user deprovisioning","group management","create group","dynamic group","add group member","directory role","assign role","PIM","privileged identity management","eligible role assignment","activate role","role activation","authentication methods","MFA admin","FIDO2 key","passwordless auth","SSPR configuration","admin unit","scoped delegation","guest invite","B2B invitation","external collaboration","license assign","group-based licensing","named location","IP range","access package","entitlement management","access review","recertification","az ad user","az ad group","az ad app","az ad sp","az role assignment","az rest graph","app registration","service principal","federated credential","client secret rotation"]

Entra ID Administration

Authentication & Scopes

All operations target the Microsoft Graph API. Authentication uses delegated or application credentials via Azure Identity (DefaultAzureCredential or InteractiveBrowserCredential).

Common required scopes:

Scope	Purpose
User.ReadWrite.All	Create, update, delete users
Group.ReadWrite.All	Create, update, manage groups and membership
Directory.ReadWrite.All	Directory role assignments, admin units
RoleManagement.ReadWrite.Directory	Assign Entra directory roles, PIM
UserAuthenticationMethod.ReadWrite.All	Manage authentication methods
EntitlementManagement.ReadWrite.All	Access packages, catalogs, reviews
Organization.ReadWrite.All	Tenant settings, external collab
LicenseAssignment.ReadWrite.All	Assign and remove licenses

Base URL: https://graph.microsoft.com/v1.0 Beta URL: https://graph.microsoft.com/beta (PIM v2, some auth method operations)

---

User Management

Create User

POST /users
Content-Type: application/json

{
  "displayName": "Jane Smith",
  "userPrincipalName": "[e-mail]",
  "mailNickname": "jane.smith",
  "accountEnabled": true,
  "passwordProfile": {
    "password": "<generated-strong-password>",
    "forceChangePasswordNextSignIn": true
  },
  "department": "Engineering",
  "jobTitle": "Software Engineer",
  "officeLocation": "Seattle",
  "usageLocation": "US",
  "mobilePhone": "[phone]",
  "businessPhones": ["[phone]"],
  "preferredLanguage": "en-US"
}

Required fields: displayName, userPrincipalName, mailNickname, accountEnabled, passwordProfile. usageLocation is required before assigning licenses (ISO 3166-1 alpha-2 country code).

Update User

PATCH /users/{userIdOrUPN}

Only include fields being changed. All fields are optional for PATCH.

Disable / Enable User

PATCH /users/{userId}
{ "accountEnabled": false }

Re-enable: { "accountEnabled": true }.

Soft Delete and Restore

DELETE /users/{userId}        → soft delete (30-day recovery window)
GET    /directory/deletedItems/microsoft.graph.user   → list deleted users
POST   /directory/deletedItems/{userId}/restore       → restore within 30 days
DELETE /directory/deletedItems/{userId}               → permanent delete

Bulk Import

Use $batch endpoint for up to 20 requests per batch:

POST /$batch
Content-Type: application/json

{
  "requests": [
    { "id": "1", "method": "POST", "url": "/users", "headers": {"Content-Type": "application/json"}, "body": { ... } },
    { "id": "2", "method": "POST", "url": "/users", "headers": {"Content-Type": "application/json"}, "body": { ... } }
  ]
}

For large imports (>20 users), split into batches and honor 429 throttling.

See references/user-management.md for delta queries, manager assignment, photo upload, and extension attributes.

---

Group Management

Create Group

Microsoft 365 Group (has mailbox, Teams-capable):

{
  "displayName": "Project Phoenix",
  "mailEnabled": true,
  "mailNickname": "project-phoenix",
  "securityEnabled": false,
  "groupTypes": ["Unified"],
  "description": "Cross-functional project team"
}

Security Group (no mailbox, for RBAC/CA):

{
  "displayName": "SG-DevTeam-Prod",
  "mailEnabled": false,
  "mailNickname": "sg-devteam-prod",
  "securityEnabled": true,
  "groupTypes": []
}

Dynamic Security Group (membership auto-computed from user attributes):

{
  "displayName": "SG-Dept-Engineering",
  "mailEnabled": false,
  "mailNickname": "sg-dept-engineering",
  "securityEnabled": true,
  "groupTypes": ["DynamicMembership"],
  "membershipRule": "(user.department -eq \"Engineering\")",
  "membershipRuleProcessingState": "On"
}

Manage Membership

POST /groups/{groupId}/members/$ref
{ "@odata.id": "https://graph.microsoft.com/v1.0/directoryObjects/{userId}" }

DELETE /groups/{groupId}/members/{userId}/$ref

See references/group-management.md for group-based licensing, transitive membership, and owner management.

---

Directory Roles

List all built-in and custom roles:

GET /directoryRoles          → currently activated roles in tenant
GET /roleManagement/directory/roleDefinitions   → all role definitions

Assign a role:

POST /roleManagement/directory/roleAssignments
{
  "principalId": "<user-or-sp-id>",
  "roleDefinitionId": "<role-definition-id>",
  "directoryScopeId": "/"
}

Use directoryScopeId of /administrativeUnits/<id> to scope to an admin unit.

See references/role-assignments.md for role definition IDs, custom roles, and scoped assignments.

---

Privileged Identity Management (PIM)

PIM requires Azure AD P2 or Microsoft Entra ID Governance license.

PIM operations use roleManagement/directory/roleEligibilityScheduleRequests (beta).

Create Eligible Assignment

POST /beta/roleManagement/directory/roleEligibilityScheduleRequests
{
  "action": "adminAssign",
  "principalId": "<user-id>",
  "roleDefinitionId": "<role-definition-id>",
  "directoryScopeId": "/",
  "scheduleInfo": {
    "startDateTime": "2026-03-01T00:00:00Z",
    "expiration": { "type": "afterDuration", "duration": "P180D" }
  },
  "justification": "Project lead requires temporary admin access"
}

Activate Eligible Role (Self-Service)

POST /beta/roleManagement/directory/roleAssignmentScheduleRequests
{
  "action": "selfActivate",
  "principalId": "<my-user-id>",
  "roleDefinitionId": "<role-definition-id>",
  "directoryScopeId": "/",
  "justification": "Performing emergency patch deployment",
  "scheduleInfo": {
    "startDateTime": "2026-03-01T10:00:00Z",
    "expiration": { "type": "afterDuration", "duration": "PT4H" }
  }
}

See references/pim.md for approval workflows, PIM for groups, and role settings management.

---

Authentication Methods

Authentication methods are managed per-user via:

GET  /users/{userId}/authentication/methods
GET  /users/{userId}/authentication/microsoftAuthenticatorMethods
GET  /users/{userId}/authentication/fido2Methods
POST /users/{userId}/authentication/fido2Methods
DELETE /users/{userId}/authentication/fido2Methods/{methodId}

Require re-registration of MFA:

POST /users/{userId}/authentication/requireMfaRegistration

List users with MFA registered:

GET /reports/credentialUserRegistrationDetails

See references/auth-methods.md for SSPR configuration, authentication strength policies, and temporary access passes.

---

Admin Units

Admin units enable scoped delegation — an admin role scoped to a subset of users/groups.

POST /administrativeUnits
{ "displayName": "APAC Region", "description": "All users and groups in APAC" }

POST /administrativeUnits/{auId}/members/$ref
{ "@odata.id": "https://graph.microsoft.com/v1.0/users/{userId}" }

POST /administrativeUnits/{auId}/scopedRoleMembers
{
  "roleId": "<directory-role-id>",
  "roleMemberInfo": { "id": "<admin-user-id>" }
}

See references/admin-units.md for restricted management AUs and dynamic membership rules.

---

External Identities / B2B

Invite Guest User

POST /invitations
{
  "invitedUserEmailAddress": "[e-mail]",
  "inviteRedirectUrl": "https://myapps.microsoft.com",
  "invitedUserDisplayName": "Alice Fabrikam",
  "sendInvitationMessage": true,
  "invitedUserMessageInfo": {
    "customizedMessageBody": "Welcome to Contoso! Click below to access your resources."
  }
}

Response includes inviteRedeemUrl for manual sharing.

Configure External Collaboration

GET  /policies/authorizationPolicy
PATCH /policies/authorizationPolicy
{
  "allowInvitesFrom": "adminsAndGuestInviters",
  "guestUserRoleId": "10dae51f-b6af-4016-8d66-8c2a99b929b3"
}

See references/external-identities.md for cross-tenant access policies, B2B direct connect, and guest lifecycle management.

---

License Assignment

Licenses require usageLocation to be set on the user first.

POST /users/{userId}/assignLicense
{
  "addLicenses": [
    {
      "skuId": "<sku-guid>",
      "disabledPlans": []
    }
  ],
  "removeLicenses": []
}

Common SKU GUIDs:

Product	SKU GUID
Microsoft 365 E3	05e9a617-0261-4cee-bb44-138d3ef5d965
Microsoft 365 E5	06ebc4ee-1bb5-47dd-8120-11324bc54e06
Microsoft Entra ID P2	eec0eb4f-6444-4f95-aba0-50c24d67f998
Microsoft 365 Business Premium	cbdc14ab-d96c-4c30-b9f4-6ada7cdc1d46

Get available SKUs: GET /subscribedSkus

See references/licenses.md for group-based licensing, license error resolution, and SKU service plan IDs.

---

Entitlement Management

Entitlement management requires Azure AD P2 or Microsoft Entra ID Governance.

POST /identityGovernance/entitlementManagement/catalogs
{ "displayName": "IT Resources", "description": "Standard IT software and tools", "isExternallyVisible": false }

POST /identityGovernance/entitlementManagement/accessPackages
{
  "displayName": "Developer Tools",
  "description": "GitHub, Dev Box, Azure Portal access",
  "catalog": { "id": "<catalog-id>" }
}

See references/entitlement-management.md for assignment policies, approval flows, access reviews, and auto-assignment policies.

---

Azure CLI Reference

All operations above can also be performed using Azure CLI (az ad, az role, az rest). CLI commands are useful for scripting, CI/CD pipelines, and environments without Graph SDK access.

Prerequisites: az login with sufficient Entra ID role. Install extensions if prompted.

User Management (CLI)

# Create user
az ad user create --display-name "Jane Smith" \
  --user-principal-name [e-mail] \
  --password "<strong-password>" \
  --force-change-password-next-sign-in true

# List users (tabular)
az ad user list \
  --query "[].{UPN:userPrincipalName, DisplayName:displayName, ID:id}" \
  --output table

# Show single user
az ad user show --id [e-mail]

# Update user properties
az ad user update --id [e-mail] \
  --display-name "Jane M. Smith" --job-title "Senior Engineer"

# Delete user (soft delete — 30-day recovery)
az ad user delete --id [e-mail]

# Get groups and roles the user belongs to
az ad user get-member-objects --id [e-mail] \
  --security-enabled-only false

Group Management (CLI)

# Create security group
az ad group create --display-name "SG-DevTeam-Prod" \
  --mail-nickname "sg-devteam-prod" \
  --description "Production dev team security group"

# Create M365 group (Teams-capable)
az ad group create --display-name "Project Phoenix" \
  --mail-nickname "project-phoenix" \
  --group-types Unified --mail-enabled true

# List groups
az ad group list \
  --query "[].{Name:displayName, ID:id, Type:groupTypes}" \
  --output table

# Show / delete group
az ad group show --group "SG-DevTeam-Prod"
az ad group delete --group "SG-DevTeam-Prod"

# Member management
az ad group member add --group "SG-DevTeam-Prod" --member-id <user-object-id>
az ad group member remove --group "SG-DevTeam-Prod" --member-id <user-object-id>
az ad group member list --group "SG-DevTeam-Prod" \
  --query "[].{Name:displayName, UPN:userPrincipalName}" --output table
az ad group member check --group "SG-DevTeam-Prod" --member-id <user-object-id>

# Owner management
az ad group owner add --group "SG-DevTeam-Prod" --owner-object-id <owner-id>
az ad group owner list --group "SG-DevTeam-Prod"

App Registrations (CLI)

# Create app registration
az ad app create --display-name "My API App" --sign-in-audience AzureADMyOrg

# List / show / delete
az ad app list --display-name "My API App" --output table
az ad app show --id <app-id>
az ad app delete --id <app-id>

# Update app
az ad app update --id <app-id> --set displayName="My API App v2"

# Credential management (client secrets)
az ad app credential reset --id <app-id> --append \
  --display-name "CLI credential" --years 1
az ad app credential list --id <app-id> --output table
az ad app credential delete --id <app-id> --key-id <key-id>

# Federated credentials (OIDC for GitHub Actions, etc.)
az ad app federated-credential create --id <app-id> --parameters @credential.json
az ad app federated-credential list --id <app-id>

# API permissions
az ad app permission add --id <app-id> \
  --api 00000003-0000-0000-c000-000000000000 \
  --api-permissions e1fe6dd8-ba31-4d61-89e7-88639da4683d=Scope
az ad app permission admin-consent --id <app-id>
az ad app permission list --id <app-id> --output table

Service Principals (CLI)

# Create SP from existing app registration
az ad sp create --id <app-id>

# Create SP with RBAC role assignment in one step
az ad sp create-for-rbac --name "deploy-sp" \
  --role Contributor --scopes /subscriptions/<sub-id>

# List / show / delete
az ad sp list --display-name "deploy-sp" --output table
az ad sp show --id <sp-id>
az ad sp delete --id <sp-id>

# Credential rotation
az ad sp credential reset --id <sp-id> --append \
  --display-name "Rotation" --years 1
az ad sp credential list --id <sp-id>

Azure RBAC Role Assignments (CLI)

# Assign role at subscription scope
az role assignment create --assignee [e-mail] \
  --role "Reader" --scope /subscriptions/<sub-id>

# Assign role at resource group scope
az role assignment create --assignee [e-mail] \
  --role "Contributor" --resource-group <rg-name>

# List assignments for a principal
az role assignment list --assignee [e-mail] --output table

# List assignments at a scope
az role assignment list --scope /subscriptions/<sub-id> --output table

# Remove assignment
az role assignment delete --assignee [e-mail] \
  --role "Reader" --scope /subscriptions/<sub-id>

# Search role definitions
az role definition list \
  --query "[?contains(roleName,'Contributor')]" --output table
az role definition list --custom-role-only true --output table

Entra ID Directory Roles (CLI via az rest)

# List activated directory roles
az rest --method GET \
  --url "https://graph.microsoft.com/v1.0/directoryRoles" \
  --query "value[].{Role:displayName, ID:id}" --output table

# Activate a role template (first-time activation)
az rest --method POST \
  --url "https://graph.microsoft.com/v1.0/directoryRoles" \
  --body '{"roleTemplateId":"<template-id>"}'

# Assign user to a directory role
az rest --method POST \
  --url "https://graph.microsoft.com/v1.0/directoryRoles/<role-id>/members/\$ref" \
  --body '{"@odata.id":"https://graph.microsoft.com/v1.0/users/<user-id>"}'

Note: az ad commands cover Entra ID (Azure AD) objects. For Azure resource RBAC, use az role assignment. For Entra directory roles not exposed by az ad, use az rest with the Graph API URL.

---

Error Reference

Code	Meaning	Resolution
400 BadRequest	Missing required field or invalid value	Check field requirements; verify usageLocation is set before license
403 Forbidden	Missing scope or insufficient role	Add required Graph scope; check role assignment
404 NotFound	Resource not found	Verify GUID; resource may be soft-deleted
409 Conflict	Resource already exists (e.g., duplicate UPN)	Use a different UPN or update the existing resource
429 TooManyRequests	Graph throttled	Back off per Retry-After header; use batch API for bulk operations
502/503	Graph service transient	Retry with exponential backoff (max 3 retries)

Progressive Disclosure — Reference Files

Topic	File
User CRUD, delta queries, manager chain, photo, extension attributes	references/user-management.md
Group types, dynamic membership rules, group owners, group-based licensing	references/group-management.md
Role definitions, role assignment, custom roles, scoped assignments	references/role-assignments.md
PIM eligible/active assignments, approval policies, PIM for Groups, role settings	references/pim.md
Auth methods per user, SSPR, auth strength policies, TAP	references/auth-methods.md
Admin units, restricted management AUs, dynamic AU membership	references/admin-units.md
B2B invitations, cross-tenant access, guest lifecycle, XTAP per-org settings	references/external-identities.md
License SKUs, plan IDs, group-based licensing, error resolution	references/licenses.md
Named locations (IP ranges, countries), trusted IPs, GPS location	references/named-locations.md
Access packages, catalogs, assignment policies, access reviews	references/entitlement-management.md