Entra ID role definitions - an introduction

Microsoft's Entra ID has a ever-growing list of built-in role definitions and you can even create your own. But how do they actually work?

When building my Entra Role Reaper application, I needed to understand more about how they are configured and how it all fits together.

What is an Entra ID role?

An Entra ID role is an instance of a unifiedRoleDefinition resource object. This is a type that specifies, for the most part, which permissions - or resource actions - the assigned user can perform on a given target resource.

It also specifies which types of principals (user, servicePrincipal, group) that can be assigned to the specific role.

While the definition does have a resourceScope property, this is not in use (scope belongs to the role assignment or unifiedRoleAssignment).

You can inspect these role definitions yourself in Entra ID ➡ Manage ➡ Roles and Administrators or via the Graph API if you want all the gritty details.

Or read on 😄

Resource actions - your permit slips

Given any target resource, there is a set of actions that can be performed - thus they are named resource actions.

For an apple - perhaps a Granny Smith - these resource actions could be defined:

• Pick up
• Wash
• Eat
  • This one could be privileged because it is reserved for fine dining guests
• All of the above (privileged action for the owner)

Depending on how friendly the owner of the apple is, you may be restricted to only pick it up, wash it and hand it over to someone else who is then privileged enough to eat it.

Entra ID has hundreds of these resource actions defined spread across different types of namespaces and entities. All resource actions for Entra ID entities are listed in the microsoft.directory namespace.

Of course, they are not defined as pretty as in this table, but instead are written as:

microsoft.directory/users/basic/update
microsoft.directory/users/create
microsoft.directory/users/delete
microsoft.directory/users/photo/update

The actions listed as part of the name follow standard CRUD operations for the most part:

• Create - allows the creation of the specified entity
• CreateAsOwner - allows the creation of the specified entity and sets the user as owner
• Read - allows reading the property set specified
• Update - allows updating the property set specified
• Delete - allows the deletion of the specified entity
• AllTasks - contains all of the above

A collection of these will make up the role definition and describe what you are allowed to do - these collections are called permission sets.

Permission sets

A role definition will always have at least one permission set. These are a collection of resource actions tied to a condition.

If there is no condition, the resource actions are considered to be available tenant-wide.

There is a hidden role definition that all regular users have - namely the User role. This is a prime example of a role definition that has more than one permission set and perfectly exemplifies the concept of conditional permission sets.

It is displayed in the Entra Role Reaper as a Privileged role and this means that it has some privileged resource actions attached to it.

As shown in the image below, the role definition shows 3 different permission sets:

• Set 1 which has no condition and also no privileged resource actions; this is the tenant-wide set that shows the User role having limited access overall.
• Set 2 specifies $SubjectIsOwner as condition which signifies that the privileged resource actions in the set are only available if the user is the owner of the target resource they are trying to perform a resource action on.
• Set 3 is similar, however here the condition specifies $ResourceIsSelf which intuitively says you are allowed to perform certain privileged actions on yourself - like resetting your own password.

Guest vs Restricted Guest

While on the subject of different permission sets - if you change the Guest settings in Entra (shown in the image below) you effectively decide which role guest-users will have.

The two more restrictive settings map your guests to either the Guest or the Restricted Guest role - which are hidden in the normal Entra role listing.

The difference can be viewed in the tenant-wide permission set; the restrictive one missing the following resource actions:

microsoft.directory/groups/appRoleAssignments/limitedRead
microsoft.directory/groups/memberOf/limitedRead
microsoft.directory/groups/members/limitedRead
microsoft.directory/groups/owners/limitedRead
microsoft.directory/groups/settings/limitedRead
microsoft.directory/groups/standard/limitedRead
microsoft.directory/multiTenantOrganization/standard/read
microsoft.directory/multiTenantOrganization/tenants/standard/read
microsoft.directory/users/guestBasicProfile/limitedRead
microsoft.directory/users/inviteGuest

Custom roles

Built-in roles cannot be modified, but some times they just don't give you what you need.

This is where custom roles come into play. These are role definitions that you create where you can mix and match any of the resource actions we have talked about.

While you cannot specify more than one permission set on custom roles, when you assign them you specify the scope to which they are eligible such as:

• Tenant-wide
• Administrative Unit
• Entra ID Resource
  • Resource group(s)
  • Application registration(s)
  • Enterprise application(s)

This is not unique to custom roles - scopes can be applied to most built-in roles.