|
| 1 | +--- |
| 2 | +title: Eligible and time-bound role assignments in Azure RBAC |
| 3 | +description: Learn about the integration of Azure role-based access control (Azure RBAC) and Microsoft Entra Privileged Identity Management (PIM) to create eligible and time-bound role assignments. |
| 4 | +author: rolyon |
| 5 | +ms.service: role-based-access-control |
| 6 | +ms.topic: conceptual |
| 7 | +ms.date: 11/11/2024 |
| 8 | +ms.author: rolyon |
| 9 | +--- |
| 10 | + |
| 11 | +# Eligible and time-bound role assignments in Azure RBAC |
| 12 | + |
| 13 | +If you have a Microsoft Entra ID P2 or Microsoft Entra ID Governance license, [Microsoft Entra Privileged Identity Management (PIM)](/entra/id-governance/privileged-identity-management/pim-configure) is integrated into role assignment steps. For example, you can assign roles to users for a limited period of time. You can also make users eligible for role assignments so that they must activate to use the role, such as request approval. Eligible role assignments provide just-in-time access to a role for a limited period of time. |
| 14 | + |
| 15 | +This article describes the integration of Azure role-based access control (Azure RBAC) and Microsoft Entra Privileged Identity Management (PIM) to create eligible and time-bound role assignments. |
| 16 | + |
| 17 | +## PIM functionality |
| 18 | + |
| 19 | +If you have PIM, you can create eligible and time-bound role assignments using the **Access control (IAM)** page in the Azure portal. You can create eligible role assignments for users, but you can't create eligible role assignments for applications, service principals, or managed identities because they can't perform the activation steps. You can create eligible role assignments at management group, subscription, and resource group scope, but not at resource scope. |
| 20 | + |
| 21 | +Here's an example of the **Assignment type** tab when you add a role assignment using the **Access control (IAM)** page. This capability is being deployed in stages, so it might not be available yet in your tenant or your interface might look different. |
| 22 | + |
| 23 | +:::image type="content" source="./media/shared/assignment-type-eligible.png" alt-text="Screenshot of Add role assignment with Assignment type options displayed." lightbox="./media/shared/assignment-type-eligible.png"::: |
| 24 | + |
| 25 | +The assignment type options available to you might vary depending or your PIM policy. For example, PIM policy defines whether permanent assignments can be created, maximum duration for time-bound assignments, roles activations requirements (approval, multifactor authentication, or Conditional Access authentication context), and other settings. For more information, see [Configure Azure resource role settings in Privileged Identity Management](/entra/id-governance/privileged-identity-management/pim-resource-roles-configure-role-settings). |
| 26 | + |
| 27 | +Users with eligible and/or time-bound assignments must have a valid license. If you don't want to use the PIM functionality, select the **Active** assignment type and **Permanent** assignment duration options. These settings create a role assignment where the principal always has permissions in the role. |
| 28 | + |
| 29 | +To better understand PIM, you should review the following terms. |
| 30 | + |
| 31 | +| Term or concept | Role assignment category | Description | |
| 32 | +| --- | --- | --- | |
| 33 | +| eligible | Type | A role assignment that requires a user to perform one or more actions to use the role. If a user has been made eligible for a role, that means they can activate the role when they need to perform privileged tasks. There's no difference in the access given to someone with a permanent versus an eligible role assignment. The only difference is that some people don't need that access all the time. | |
| 34 | +| active | Type | A role assignment that doesn't require a user to perform any action to use the role. Users assigned as active have the privileges assigned to the role. | |
| 35 | +| activate | | The process of performing one or more actions to use a role that a user is eligible for. Actions might include performing a multifactor authentication (MFA) check, providing a business justification, or requesting approval from designated approvers. | |
| 36 | +| permanent eligible | Duration | A role assignment where a user is always eligible to activate the role. | |
| 37 | +| permanent active | Duration | A role assignment where a user can always use the role without performing any actions. | |
| 38 | +| time-bound eligible | Duration | A role assignment where a user is eligible to activate the role only within start and end dates. | |
| 39 | +| time-bound active | Duration | A role assignment where a user can use the role only within start and end dates. | |
| 40 | +| just-in-time (JIT) access | | A model in which users receive temporary permissions to perform privileged tasks, which prevents malicious or unauthorized users from gaining access after the permissions have expired. Access is granted only when users need it. | |
| 41 | +| principle of least privilege access | | A recommended security practice in which every user is provided with only the minimum privileges needed to accomplish the tasks they're authorized to perform. This practice minimizes the number of Global Administrators and instead uses specific administrator roles for certain scenarios. | |
| 42 | + |
| 43 | +For more information, see [What is Microsoft Entra Privileged Identity Management?](/entra/id-governance/privileged-identity-management/pim-configure). |
| 44 | + |
| 45 | +## How to list eligible and time-bound role assignments |
| 46 | + |
| 47 | +If you want to see which users are using the PIM functionality, here are options for how to list eligible and time-bound role assignments. |
| 48 | + |
| 49 | +### Option 1: List using the Azure portal |
| 50 | + |
| 51 | +1. Sign in to the Azure portal, open the **Access control (IAM)** page, and select the **Role assignments** tab. |
| 52 | + |
| 53 | +1. Filter the eligible and time-bound role assignments. |
| 54 | + |
| 55 | + You can group and sort by **State**, and look for role assignments that aren't the **Active permanent** type. |
| 56 | + |
| 57 | + :::image type="content" source="./media/shared/sub-access-control-role-assignments-eligible.png" alt-text="Screenshot of Access control and Active assignments and Eligible assignments tabs." lightbox="./media/shared/sub-access-control-role-assignments-eligible.png"::: |
| 58 | + |
| 59 | +### Option 2: List using PowerShell |
| 60 | + |
| 61 | +There isn't a single PowerShell command that can list both the eligible and active time-bound role assignments. To list your eligible role assignments, use the [Get-AzRoleEligibilitySchedule](/powershell/module/az.resources/get-azroleeligibilityschedule) command. To list your active role assignments, use the [Get-AzRoleAssignmentSchedule](/powershell/module/az.resources/get-azroleassignmentschedule) command. |
| 62 | + |
| 63 | +This example shows how to list eligible and time-bound role assignments in a subscription, which includes these role assignment types: |
| 64 | + |
| 65 | +- Eligible permanent |
| 66 | +- Eligible time-bound |
| 67 | +- Active time-bound |
| 68 | + |
| 69 | +The `Where-Object` command filters out active permanent role assignments that are available with Azure RBAC functionality without PIM. |
| 70 | + |
| 71 | +```powershell |
| 72 | +Get-AzRoleEligibilitySchedule -Scope /subscriptions/<subscriptionId> |
| 73 | +Get-AzRoleAssignmentSchedule -Scope /subscriptions/<subscriptionId> | Where-Object {$_.EndDateTime -ne $null } |
| 74 | +``` |
| 75 | + |
| 76 | +For information about how scopes are constructed, see [Understand scope for Azure RBAC](/azure/role-based-access-control/scope-overview). |
| 77 | + |
| 78 | +## How to convert eligible and time-bound role assignments to active permanent |
| 79 | + |
| 80 | +If your organization has process or compliance reasons to limit the use of PIM, here are options for how to convert these role assignments to active permanent. |
| 81 | + |
| 82 | +### Option 1: Convert using the Azure portal |
| 83 | + |
| 84 | +1. In the Azure portal, on the **Role assignments** tab and **State** column, select the **Eligible permanent**, **Eligible time-bound**, and **Active time-bound** links for each role assignment you want to convert. |
| 85 | + |
| 86 | +1. In the **Edit assignment** pane, select **Active** for the assignment type and **Permanent** for the assignment duration. |
| 87 | + |
| 88 | + For more information, see [Edit assignment](role-assignments-portal.yml#edit-assignment). |
| 89 | + |
| 90 | + :::image type="content" source="./media/shared/assignment-type-edit.png" alt-text="Screenshot of Edit assignment pane with Assignment type options displayed." lightbox="./media/shared/assignment-type-edit.png"::: |
| 91 | + |
| 92 | +1. When finished, select **Save**. |
| 93 | + |
| 94 | + Your updates might take a while to be processed and reflected in the portal. |
| 95 | + |
| 96 | +1. Repeat these steps for all role assignments at management group, subscription, and resource group scopes that you want to convert. |
| 97 | + |
| 98 | + If you have role assignments at resource scope that you want to convert, you have to make changes directly in PIM. |
| 99 | + |
| 100 | +### Option 2: Convert using PowerShell |
| 101 | + |
| 102 | +There isn't a command or API to directly convert role assignments to a different state or type, so instead you can follow these steps. |
| 103 | + |
| 104 | +> [!IMPORTANT] |
| 105 | +> Removing role assignments can potentially cause disruptions in your environment. Be sure that you understand the impact before you perform these steps. |
| 106 | +
|
| 107 | +1. Retrieve and save the list of all of your eligible and time-bound role assignment in a secure location to prevent data loss. |
| 108 | + |
| 109 | + > [!IMPORTANT] |
| 110 | + > It is important that you save the list of eligible and time-bound role assignments because these steps require you to remove these role assignments before you create the same role assignments as active permanent. |
| 111 | +
|
| 112 | +2. Use the [New-AzRoleEligibilityScheduleRequest](/powershell/module/az.resources/new-azroleeligibilityschedulerequest) command to remove your eligible role assignments. |
| 113 | + |
| 114 | + This example shows how to remove an eligible role assignment. |
| 115 | + |
| 116 | + ```powershell |
| 117 | + $guid = New-Guid |
| 118 | + New-AzRoleEligibilityScheduleRequest -Name $guid -Scope <Scope> -PrincipalId <PrincipalId> -RoleDefinitionId <RoleDefinitionId> -RequestType AdminRemove |
| 119 | + ``` |
| 120 | + |
| 121 | +3. Use the [New-AzRoleAssignmentScheduleRequest](/powershell/module/az.resources/new-azroleassignmentschedulerequest) command to remove your active time-bound role assignments. |
| 122 | +
|
| 123 | + This example shows how to remove an active time-bound role assignment. |
| 124 | +
|
| 125 | + ```powershell |
| 126 | + $guid = New-Guid |
| 127 | + New-AzRoleAssignmentScheduleRequest -Name $guid -Scope <Scope> -PrincipalId <PrincipalId> -RoleDefinitionId <RoleDefinitionId> -RequestType AdminRemove |
| 128 | + ``` |
| 129 | +
|
| 130 | +4. Use the [Get-AzRoleAssignment](/powershell/module/az.resources/get-azroleassignment) command to check for an existing role assignment and use the [New-AzRoleAssignment](/powershell/module/az.resources/new-azroleassignment) command to create an active permanent role assignment with Azure RBAC for each eligible and time-bound role assignment. |
| 131 | +
|
| 132 | + This example shows how to check for an existing role assignment and create an active permanent role assignment with Azure RBAC. |
| 133 | +
|
| 134 | + ```powershell |
| 135 | + $result = Get-AzRoleAssignment -ObjectId $RA.PrincipalId -RoleDefinitionName $RA.RoleDefinitionDisplayName -Scope $RA.Scope; |
| 136 | + if($result -eq $null) { |
| 137 | + New-AzRoleAssignment -ObjectId $RA.PrincipalId -RoleDefinitionName $RA.RoleDefinitionDisplayName -Scope $RA.Scope |
| 138 | + } |
| 139 | + ``` |
| 140 | +
|
| 141 | +## How to limit the creation of eligible or time-bound role assignments |
| 142 | +
|
| 143 | +If your organization has process or compliance reasons to limit the use of PIM, you can use Azure Policy to limit the creation of eligible or time-bound role assignments. For more information, see [What is Azure Policy?](/azure/governance/policy/overview). |
| 144 | +
|
| 145 | +Here's an example policy that limits the creation of eligible and time-bound role assignments except for a specific list of identities. Additional parameters and checks can be added for other allow conditions. |
| 146 | +
|
| 147 | +```json |
| 148 | +{ |
| 149 | + "properties": { |
| 150 | + "displayName": "Limit eligible and active time-bound role assignments except for allowed principal IDs", |
| 151 | + "policyType": "Custom", |
| 152 | + "mode": "All", |
| 153 | + "metadata": { |
| 154 | + "createdBy": "aaaaaaaa-bbbb-cccc-1111-222222222222", |
| 155 | + "createdOn": "2024-11-05T02:31:25.1246591Z", |
| 156 | + "updatedBy": "aaaaaaaa-bbbb-cccc-1111-222222222222", |
| 157 | + "updatedOn": "2024-11-06T07:58:17.1699721Z" |
| 158 | + }, |
| 159 | + "version": "1.0.0", |
| 160 | + "parameters": { |
| 161 | + "allowedPrincipalIds": { |
| 162 | + "type": "Array", |
| 163 | + "metadata": { |
| 164 | + "displayName": "Allowed Principal IDs", |
| 165 | + "description": "A list of principal IDs that can receive PIM role assignments." |
| 166 | + }, |
| 167 | + "defaultValue": [] |
| 168 | + } |
| 169 | + }, |
| 170 | + "policyRule": { |
| 171 | + "if": { |
| 172 | + "anyof": [ |
| 173 | + { |
| 174 | + "allOf": [ |
| 175 | + { |
| 176 | + "field": "type", |
| 177 | + "equals": "Microsoft.Authorization/roleEligibilityScheduleRequests" |
| 178 | + }, |
| 179 | + { |
| 180 | + "not": { |
| 181 | + "field": "Microsoft.Authorization/roleEligibilityScheduleRequests/principalId", |
| 182 | + "in": "[parameters('allowedPrincipalIds')]" |
| 183 | + } |
| 184 | + } |
| 185 | + ] |
| 186 | + }, |
| 187 | + { |
| 188 | + "allOf": [ |
| 189 | + { |
| 190 | + "field": "type", |
| 191 | + "equals": "Microsoft.Authorization/roleAssignmentScheduleRequests" |
| 192 | + }, |
| 193 | + { |
| 194 | + "not": { |
| 195 | + "field": "Microsoft.Authorization/roleAssignmentScheduleRequests/principalId", |
| 196 | + "in": "[parameters('allowedPrincipalIds')]" |
| 197 | + } |
| 198 | + } |
| 199 | + ] |
| 200 | + } |
| 201 | + ] |
| 202 | + }, |
| 203 | + "then": { |
| 204 | + "effect": "deny" |
| 205 | + } |
| 206 | + }, |
| 207 | + "versions": [ |
| 208 | + "1.0.0" |
| 209 | + ] |
| 210 | + }, |
| 211 | + "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4ef/providers/Microsoft.Authorization/policyDefinitions/1aaaaaa1-2bb2-3cc3-4dd4-5eeeeeeeeee5", |
| 212 | + "type": "Microsoft.Authorization/policyDefinitions", |
| 213 | + "name": "1aaaaaa1-2bb2-3cc3-4dd4-5eeeeeeeeee5", |
| 214 | + "systemData": { |
| 215 | + |
| 216 | + "createdByType": "User", |
| 217 | + "createdAt": "2024-11-05T02:31:25.0836273Z", |
| 218 | + "lastModifiedBy": "[email protected]", |
| 219 | + "lastModifiedByType": "User", |
| 220 | + "lastModifiedAt": "2024-11-06T07:58:17.1651655Z" |
| 221 | + } |
| 222 | +} |
| 223 | +``` |
| 224 | + |
| 225 | +For information about PIM resource properties, see these REST API docs: |
| 226 | + |
| 227 | +- [RoleEligibilityScheduleRequest](/rest/api/authorization/role-eligibility-schedule-requests/get) |
| 228 | +- [RoleAssignmentScheduleRequest](/rest/api/authorization/role-assignment-schedule-requests/get) |
| 229 | + |
| 230 | +For information about how to assign an Azure Policy with parameters, see [Tutorial: Create and manage policies to enforce compliance](/azure/governance/policy/tutorials/create-and-manage#assign-a-policy). |
| 231 | + |
| 232 | +## Next steps |
| 233 | + |
| 234 | +- [Assign Azure roles using the Azure portal](role-assignments-portal.yml) |
| 235 | +- [What is Microsoft Entra Privileged Identity Management?](/entra/id-governance/privileged-identity-management/pim-configure) |
0 commit comments