🔐 Recipe · Entra ID & Identity

Assign an Entra ID Directory Role to a User via Microsoft Graph

Grant administrative privileges by assigning a built-in directory role such as Cloud Application Administrator to a user account

Complexity

Intermediate

Impact

security + access-control + privileged-access + identity

Context

Why This Matters

Why this matters

Directory roles in Microsoft Entra ID (formerly Azure AD) grant users administrative privileges over specific parts of your tenant — from managing applications to resetting passwords to full Global Administrator control. Assigning the right role (and no more) is the cornerstone of least-privilege administration.

This recipe walks through assigning a built-in directory role to a user using Microsoft Graph, covering the full workflow: finding the user, locating the role definition, checking for existing assignments, and making the assignment.

When to run this

Onboarding a new admin or delegating specific administrative duties
Granting time-limited elevated access for a project (consider PIM for this)
Automating role provisioning as part of a broader identity lifecycle workflow
Replacing ad-hoc Global Admin grants with scoped roles (e.g., Cloud Application Administrator instead)

Expected Outcomes

What you'll have when you're done

The target user holds the specified directory role, scoped directory-wide (/) by default
A unifiedRoleAssignment object in Entra ID recording the assignment (visible in the audit log)
Effective permissions typically take 5–15 minutes to propagate; the user may need to sign out and back in
The assignment is visible in Entra admin center → Roles and administrators → [Role] → Assignments

Risks & Considerations

Warnings and gotchas

Least privilege first. Do not reach for Global Administrator. Built-in roles like Cloud Application Administrator, User Administrator, or Helpdesk Administrator cover most delegation needs.
Permanent vs. eligible. The roleAssignments endpoint creates a permanent (active) assignment. For sensitive roles, use Privileged Identity Management (PIM) to create eligible assignments that require just-in-time activation, MFA, and approval.
MFA enforcement. Entra ID now requires MFA for admin portal access. Ensure the target user has a strong authentication method registered before they try to use their new privileges.
Audit everything. Role assignments are high-signal events. Confirm your tenant logs these to a SIEM and alerts on unexpected changes.
Do NOT share admin accounts, assign roles to service accounts without a clear justification, or leave standing Global Admin assignments for humans.

Required Permissions

Permission	Why It's Needed
RoleManagement.ReadWrite.Directory	Required to create role assignments via the roleManagement/directory endpoint
User.Read.All	Required to look up the target user by display name or UPN
Directory.Read.All	Required to enumerate role definitions and existing assignments

The fastest way to get this done: just ask Dex. Copy the prompt below and paste it into your Dex conversation.

For IT Admins

Paste into Dex Pro

Assign the {role_name} directory role to {user_upn}. Verify they don't already hold it, create an active assignment at tenant scope, and confirm the assignment was recorded.

Try in Dex Pro

Assign a directory role using the Entra admin center

Sign in to the Microsoft Entra admin center as a Privileged Role Administrator or Global Administrator.
Navigate to: Identity → Roles & admins → Roles & admins
In the roles list, search for the role you want to assign (e.g., Cloud Application Administrator) and click its name.
Click + Add assignments at the top of the role detail page.
Click No member selected, then search for and select the target user (e.g., {user_upn}). Click Select.
On the Setting tab, choose the assignment type:
- Active — standing assignment, privileges always available
- Eligible (PIM P2 required) — user must activate the role just-in-time
Optionally set a start/end date for time-bound assignments and add a justification.
Click Assign.
Verify the assignment appears under [Role] → Assignments and confirm the change appears in Identity → Monitoring & health → Audit logs.

Verification

Ask the user to sign out and back in, then confirm they can access the role's scope (e.g., for Cloud Application Administrator, they should be able to open App registrations and create a new app).

Assign a directory role via Microsoft Graph

The workflow has four API calls: find the user, find the role definition, check for an existing assignment, and create the assignment.

1. Find the target user

GET https://graph.microsoft.com/v1.0/users?$filter=startswith(displayName,'{name}') or startswith(userPrincipalName,'{name}')&$select=id,displayName,userPrincipalName

Response:

{
  "value": [{
    "id": "02246633-8196-4257-a8c9-657b77773a8e",
    "displayName": "Oded Moshe",
    "userPrincipalName": "OdedM@contoso.onmicrosoft.com"
  }]
}

2. Find the role definition

GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleDefinitions?$filter=displayName eq '{role_name}'

For well-known built-in roles you can skip this step and use the templateId directly. Example IDs:

158c047a-c907-4556-b7ef-446551a6b5f7 — Cloud Application Administrator
fe930be7-5e62-47db-91af-98c3a49a38b1 — User Administrator
729827e3-9c14-49f7-bb1b-9608f156bbb8 — Helpdesk Administrator
62e90394-69f5-4237-9190-012177145e10 — Global Administrator (use with extreme caution)

3. Check for an existing assignment (idempotency)

GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments?$filter=roleDefinitionId eq '{role_id}' and principalId eq '{user_id}'

4. Create the role assignment

POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments
Content-Type: application/json

{
  "principalId": "{user_id}",
  "roleDefinitionId": "{role_id}",
  "directoryScopeId": "/"
}

A successful response is HTTP 201 Created with the new assignment object:

{
  "id": "egSMFQfJVkW370RlUaa19zNmJAKWgVdCqMlle3d3Oo4-1",
  "principalId": "02246633-8196-4257-a8c9-657b77773a8e",
  "directoryScopeId": "/",
  "roleDefinitionId": "158c047a-c907-4556-b7ef-446551a6b5f7"
}

Scope options

directoryScopeId controls where the role applies:

/ — tenant-wide (most built-in roles)
/administrativeUnits/{auId} — scoped to an Administrative Unit
/{appObjectId} — scoped to a single application (for app-scoped role assignments)

Assign a directory role with Microsoft Graph PowerShell

The Microsoft.Graph PowerShell SDK wraps the Graph endpoints shown above. Install once:

Install-Module Microsoft.Graph -Scope CurrentUser

Interactive quickstart

# Connect with the required scopes
Connect-MgGraph -Scopes "RoleManagement.ReadWrite.Directory","User.Read.All","Directory.Read.All"

# 1. Find the user
$user = Get-MgUser -UserId "user@contoso.com"

# 2. Find the role definition
$role = Get-MgRoleManagementDirectoryRoleDefinition -Filter "displayName eq 'Cloud Application Administrator'"

# 3. Create the assignment
New-MgRoleManagementDirectoryRoleAssignment -PrincipalId $user.Id -RoleDefinitionId $role.Id -DirectoryScopeId "/"

Walkthrough

Authenticate. Connect-MgGraph prompts for interactive sign-in with delegated scopes. For unattended use, authenticate with a client secret or certificate against an app registration.
Resolve identities. Pass the UPN (user@contoso.com) rather than a display name — it's unique and avoids ambiguity.
Idempotency. The downloadable script below checks for an existing assignment before creating a new one, so it's safe to re-run.
Confirm. Use Get-MgRoleManagementDirectoryRoleAssignment -Filter "principalId eq '$($user.Id)'" to list all active role assignments for the user.

Next steps

More Entra ID & Identity recipes

Browse the rest of this category in the Dex Cookbook.

Automate this with Dex Pro

Let the autonomous IT engineer run this task under your policies.

Start free

Point Dex at a tenant and try it for 30 days, no credit card.