Creating Custom Microsoft Entra Roles

Creating Custom Microsoft Entra Roles

Managing identity and access is the cornerstone of a modern security strategy. In the past, many organizations relied on a handful of "all-or-nothing" administrative roles. If a team member needed to manage user passwords, they might have been granted a broad Helpdesk Administrator role, or worse, a Global Administrator role. This approach violates the Principle of Least Privilege (PoLP), which dictates that users should only have the minimum level of access necessary to perform their specific job functions.

Microsoft Entra ID (formerly Azure Active Directory) provides dozens of built-in roles designed to cover common administrative scenarios. However, as organizations grow in complexity, these built-in roles often prove to be either too restrictive or too permissive. This is where custom roles become essential. By creating custom roles, you can cherry-pick specific permissions—such as the ability to update user attributes without the ability to delete users—and package them into a unique role definition tailored to your organization's specific operational requirements.

In this lesson, we will explore the architecture of Entra ID roles, understand the anatomy of a custom role definition, and walk through the processes of creating, managing, and assigning these roles using both the graphical interface and automation tools like PowerShell and Microsoft Graph.

Understanding Entra ID Role-Based Access Control (RBAC)

Before we dive into creating custom roles, we must distinguish between the two primary RBAC systems within the Microsoft Cloud ecosystem. It is a common point of confusion for those new to the platform.

1. Azure RBAC: This system is used to manage access to Azure resources like Virtual Machines, Storage Accounts, and Virtual Networks. These roles (like Owner, Contributor, or Reader) are defined at the subscription or resource group level.
2. Microsoft Entra RBAC: This system is used to manage access to identity-related objects within the directory itself. This includes users, groups, applications, and licenses. When we talk about "Custom Entra Roles," we are specifically referring to this directory-level access.

Callout: Directory Roles vs. Resource Roles It is helpful to think of Entra Roles as "Identity Governance" and Azure RBAC as "Infrastructure Governance." Even if you are a Global Administrator in Entra ID, you do not automatically have permissions to manage a Virtual Machine in an Azure Subscription unless you specifically grant yourself access or use a feature like Access Management for Azure Resources. Custom Entra roles allow you to fine-tune who can manage the "who" (identities), while Azure RBAC manages the "what" (resources).

The Anatomy of a Custom Role

A custom role in Microsoft Entra ID consists of three primary components that define what it can do and where it can do it:

• Role Definition: This is the blueprint. It includes the display name, a description, and a collection of allowed permissions (actions). For example, a role definition might include the permission microsoft.directory/users/password/update.
• Role Assignment: This is the link between the role definition and a security principal (a user, group, or service principal). Assigning a role is what actually grants the permissions to a person or application.
• Scope: This defines the boundary within which the permissions apply. You can assign a role at the Directory level (affecting all objects in the tenant) or at an Administrative Unit level (affecting only a subset of users or groups).

When to Create a Custom Role

You should not start by creating custom roles for every task. Microsoft recommends using built-in roles whenever possible because they are maintained by Microsoft and automatically updated when new features are added to the platform. However, custom roles become necessary in the following scenarios:

• Granular Permission Requirements: You have a support team that needs to update user "Job Title" and "Department" attributes for HR synchronization troubleshooting, but they should not be allowed to change passwords or delete accounts.
• Application Management: You want a team to manage the configuration of specific Enterprise Applications (like SSO settings) but prevent them from creating new applications or managing application secrets.
• Task-Specific Delegation: You need a "License Manager" who can only assign Microsoft 365 licenses to users but cannot modify any other user properties.
• Reducing Risk: You want to move away from using the "User Administrator" role because it allows the management of almost all user properties, and you want to create a "Junior User Admin" role with 50% fewer permissions.

Permission Patterns in Entra ID

Permissions in Entra ID follow a specific naming convention: Microsoft.directory/entity/property/action. Understanding this structure is vital for searching the permission gallery effectively.

• Namespace: Usually microsoft.directory.
• Entity: The object type, such as users, groups, applications, or devices.
• Property: The specific part of the object, like password or standard.
• Action: What can be done, such as read, create, update, or delete.

For example, microsoft.directory/users/allProperties/read allows a user to see every attribute of a user object, while microsoft.directory/users/create allows for the creation of new user accounts.

Note: Not all permissions are available for custom roles. Microsoft is constantly expanding the list of "assignable" permissions, but some high-level directory actions remain restricted to built-in roles for security and architectural reasons.

Creating a Custom Role: Step-by-Step (Admin Center)

The most common way to create a custom role is through the Microsoft Entra Admin Center. This provides a searchable interface for permissions and a guided workflow.

Step 1: Navigate to Roles and Administrators

Log in to the Microsoft Entra Admin Center (formerly Azure AD Portal). Navigate to Identity > Roles & admins > Roles & admins. Here you will see a list of all built-in roles.

Step 2: Initiate New Custom Role

At the top of the page, click on + New custom role. This will open the creation wizard.

Step 3: Basics Tab

Enter a meaningful Name and Description.

Tip: Use a naming convention that distinguishes custom roles from built-in ones. For example, prefixing your roles with your company initials (e.g., "CONTOSO - User Attribute Editor") makes them easy to find and filter.

Step 4: Permissions Tab

This is the most critical step. Use the search box to find the specific permissions you need.

1. Search for "users" if you want to modify user objects.
2. Check the boxes for the specific actions (e.g., microsoft.directory/users/basic/update).
3. Be careful not to select "delete" permissions unless absolutely necessary.

Step 5: Review and Create

Review your selected permissions. Once satisfied, click Create. The role will now appear in the list of roles, usually with a "Custom" label in the "Type" column.

Creating Custom Roles using PowerShell

For organizations that practice "Infrastructure as Code" or need to deploy roles across multiple tenants, PowerShell is the preferred method. We use the Microsoft Graph PowerShell SDK for this task.

Prerequisites

You must have the Microsoft.Graph module installed and be connected with the necessary permissions (RoleManagement.ReadWrite.Directory and Directory.ReadWrite.All).

# Connect to Microsoft Graph
Connect-MgGraph -Scopes "RoleManagement.ReadWrite.Directory"

Defining the Role Permissions

In PowerShell, permissions are defined within a JSON-like object structure. You first define the "Actions" and then create the role definition.

# Define the permissions (actions)
$allowedCustomPermissions = @(
    "microsoft.directory/users/basic/update",
    "microsoft.directory/users/password/update"
)

# Create the Role Permission object
$rolePermissions = @{
    AllowedResourceActions = $allowedCustomPermissions
}

# Create the Custom Role Definition
$newRole = New-MgRoleManagementDirectoryRoleDefinition `
    -DisplayName "Contoso Password and Basic Info Editor" `
    -Description "Can reset passwords and update basic profile info." `
    -RolePermissions $rolePermissions `
    -IsEnabled $true

Explaining the Code

• New-MgRoleManagementDirectoryRoleDefinition: This is the primary cmdlet for creating Entra ID roles.
• -RolePermissions: This parameter takes an array of permission objects. Even if you only have one set of permissions, it must be structured correctly.
• -IsEnabled: Set this to $true so the role can be assigned immediately.

Managing Custom Roles via Microsoft Graph API

If you are building custom internal tools or automation scripts, you might want to interact directly with the Microsoft Graph API. The endpoint for role definitions is POST /roleManagement/directory/roleDefinitions.

Example JSON Request Body:

{
    "description": "Allows managing specific app registrations.",
    "displayName": "App Config Manager",
    "isEnabled": true,
    "rolePermissions": [
        {
            "allowedResourceActions": [
                "microsoft.directory/applications/basic/update",
                "microsoft.directory/applications/credentials/update"
            ]
        }
    ],
    "templateId": "62e90394-69f5-4237-9190-012177145e10"
}

Warning: When using the API, ensure you do not confuse templateId with the id of the role. The id is the unique identifier for your specific custom role instance, while the templateId is often used to group versions of roles. For a new custom role, you can generate a new GUID for the id.

Scoping Custom Roles with Administrative Units

One of the most powerful features of custom roles is the ability to limit their scope. If you assign a "User Editor" role at the directory level, the assignee can edit any user in the entire tenant. In large organizations, this is often too much power.

Administrative Units (AUs) allow you to group users, groups, or devices into a logical container (e.g., "North America Sales" or "London Office"). You can then assign a custom role specifically to that AU.

How to Assign at Scope:

1. Create an Administrative Unit and add specific users to it.
2. Go to the AU in the Entra Admin Center.
3. Select Roles and administrators within the AU context.
4. Assign your custom role to a user here.

Now, that user can only exercise their "User Editor" permissions on the users located inside that specific Administrative Unit. This provides a second layer of security: Granular Permissions + Granular Scope.

Comparison: Built-in vs. Custom Roles

Best Practices for Custom Roles

Creating custom roles is a powerful capability, but it requires discipline to avoid creating a "permission soup" that is impossible to audit.

1. Follow a Naming Convention

As mentioned earlier, always prefix your roles. Use a format like [Org] - [Target] - [Action].

• Bad Name: User Admin 2
• Good Name: ABC-Marketing-UserAttribute-Editor

2. Document the "Why"

The "Description" field in a role definition is not just for show. Use it to document the specific business case or ticket number that necessitated the role. This helps during security audits two years down the line when people wonder why a specific role exists.

3. Start with Read-Only

When designing a new role, start by granting only the read permissions. Have the user test the role to see if they can view what they need. Then, incrementally add update or create permissions. This prevents "over-permissioning" from the start.

4. Use Groups for Assignment

Avoid assigning roles directly to individual users. Instead, create a security group (e.g., "Role - Marketing User Editors"), assign the custom role to that group, and then add users to the group. This makes it much easier to track who has what access and facilitates easier onboarding/offboarding.

5. Regular Audits and Reviews

Custom roles can become "stale." Perhaps a new built-in role was released that covers the same needs, or the business process has changed. Review your custom roles at least once a quarter to ensure they are still necessary and that the permissions are still appropriate.

Callout: The "Global Admin" Trap Many admins create custom roles because they feel the built-in roles are too complex, and they eventually give up and just use Global Administrator. This is a massive security risk. If a Global Admin account is compromised, your entire digital estate is at risk. Custom roles are the primary tool to prevent this. Even if it takes more time to configure, a custom role is infinitely more secure than an over-privileged built-in role.

Common Pitfalls and How to Avoid Them

Pitfall 1: Overlapping Permissions

Sometimes admins create multiple custom roles that have overlapping permissions and assign them to the same user. This makes troubleshooting access issues very difficult.

• Solution: Use the "Resultant Set of Policy" mindset. Check the user's "Assigned Roles" tab in Entra ID to see the aggregate of their permissions.

Pitfall 2: Forgetting License Requirements

Custom roles are a premium feature. To create and use custom roles, your tenant must have Microsoft Entra ID P1 or P2 licenses. If your license expires or is downgraded, your custom roles may stop functioning or you may lose the ability to edit them.

• Solution: Ensure your licensing strategy accounts for identity governance features.

Pitfall 3: Ignoring Built-in Roles

Sometimes an admin will spend hours crafting a custom role for "Application Developer" permissions, only to realize that the built-in "Application Developer" role already exists and does exactly what they need.

• Solution: Always search the built-in role gallery thoroughly before clicking "New custom role."

Pitfall 4: Granting "Delete" Permissions Casually

The ability to delete an object (user, group, or app) is a high-impact action. Once an object is deleted, it often results in the loss of associated data or access tokens.

• Solution: Rarely include delete actions in custom roles. Require a higher-level admin to perform deletions, or create a specific "Deleter" role that is only assigned temporarily via Privileged Identity Management (PIM).

Practical Example: The "HR Data Auditor" Role

Let's look at a real-world scenario. The HR department wants an intern to verify that all employees have a "Manager" assigned in Entra ID and that their "Office Location" is correct. The intern should not be able to change anything, and they definitely shouldn't see sensitive info like BitLocker recovery keys.

Permissions to include:

• microsoft.directory/users/standard/read: Allows reading basic properties.
• microsoft.directory/users/manager/read: Allows seeing who the manager is.

Permissions to exclude:

• microsoft.directory/users/password/read: (Not that this is possible, but you get the idea).
• microsoft.directory/users/allProperties/read: This might include sensitive data you want to hide.
• microsoft.directory/bitlockerKeys/key/read: Ensure they can't see recovery keys.

By creating this "HR Data Auditor" role, you fulfill the business requirement without exposing the directory to unnecessary risk.

FAQ: Common Questions about Custom Roles

Q: Can I edit a built-in role? A: No. Built-in roles are read-only. If you like a built-in role but need to change one thing, you must create a new custom role and manually add the permissions you want. You can use the "Clone" feature (if available) to start with a copy of a built-in role's permissions.

Q: Is there a limit to how many custom roles I can create? A: Yes, there is a limit of 5,000 custom roles per Entra ID tenant. Most organizations will never come close to this limit, but it's important for service providers or extremely large conglomerates to be aware of.

Q: Do custom roles work with Privileged Identity Management (PIM)? A: Yes! This is a best practice. You can make a custom role "eligible" for a user in PIM. The user then has to "activate" the role (perhaps with MFA or an approval process) before the permissions are granted. This adds an extra layer of protection to your custom roles.

Q: Can I use custom roles for guest users? A: Yes, you can assign a custom role to a guest user (B2B collaboration user), but exercise extreme caution. Ensure the scope is limited to an Administrative Unit so the guest cannot see directory data they shouldn't have access to.

Summary and Key Takeaways

Creating custom Microsoft Entra roles is an advanced but necessary skill for any identity professional. It allows you to move beyond the constraints of built-in roles and implement a true "Least Privilege" model. Whether you are using the Admin Center for a quick fix or PowerShell for a large-scale deployment, the principles remain the same: define the actions, set the scope, and assign to a group.

Key Takeaways:

• Principle of Least Privilege: Custom roles are the primary mechanism for ensuring users have only the permissions they need, reducing the organization's attack surface.
• Anatomy of a Role: A role consists of a Definition (permissions), an Assignment (the user/group), and a Scope (Directory or Administrative Unit).
• Administrative Units are Essential: Use AUs to limit the impact of a role. A "User Admin" for the "Marketing AU" is much safer than a "User Admin" for the whole company.
• Automation Matters: Use the Microsoft Graph PowerShell SDK to manage roles at scale and ensure consistency across environments.
• Naming and Documentation: Always use clear naming conventions and fill out the description field to make future audits manageable.
• PIM Integration: Whenever possible, make custom roles "Eligible" in Privileged Identity Management rather than "Permanent" to ensure Just-In-Time (JIT) access.
• Licensing: Remember that custom roles require Entra ID P1 or P2 licenses for the users interacting with them.