Usage of Custom RBAC roles in Azure API Management

This article is contributed. See the original author and article here.

Overview of Built-In RBAC roles in Azure API Management

Azure API Management relies on Azure Role-Based Access Control (RBAC) to enable fine-grained access management for API Management services and entities (for example, APIs and policies).

Reference Article: https://docs.microsoft.com/en-us/azure/api-management/api-management-role-based-access-control

As highlighted in the above article, Azure APIM provides a set of built-in RBAC roles for managing access to APIM services. These roles can be assigned at different scopes, which includes

Subscription Level
Resource Group Level
Individual APIM service level

The following table provides a brief description of the built-in roles currently offered by Azure APIM. These roles can be assigned via Azure portal or other tools, including Azure PowerShell, Azure CLI, and REST API

Custom RBAC roles in Azure APIM

If the default built-in roles do not meet specific user requirements, you can create custom RBAC roles for providing a more granular access to either APIM services or any of their sub-components.

Custom Roles in Azure RBAC: https://docs.microsoft.com/en-us/azure/role-based-access-control/custom-roles

While creating a custom RBAC role, it is easier to follow the below approach in order to avoid complexities or discrepancies:

Start with one of the built-in roles.
Edit the attributes to add Actions, NotActions, or AssignableScopes.
Save the changes as a new role.
Assign the new role to the APIM services or APIM components (such as APIs, policies, et cetera).

The ARM (Azure Resource Manager) Resource Provider Operations article contains the list of permissions that can be granted on APIM level.

https://docs.microsoft.com/en-us/azure/role-based-access-control/resource-provider-operations#microsoftapimanagement

Let us consider a few scenarios where we envision the usage of custom RBAC roles to enable fine-tuned access to APIM services or their components.

Scenario 1: Deny users from deleting APIM services

RBAC roles that enable having complete write access to APIM services (such as API Management Service Contributor role) have provision for performing all management operations on an APIM service.

To avoid intentional/unintentional deletion of APIM services by any user having write access other than the APIM Administrator, you can create the below custom RBAC role for denying the operation Microsoft.ApiManagement/service/delete to users.

In this example, let us use the Azure Portal for modifying the built-in RBAC role Contributor and create a custom role for denying APIM service deletion action for all services under a particular Azure subscription. This custom role would allow users to perform all default owner operations except deleting APIM services in the subscription.

Step 1:

Maneuver to the Access Control (IAM) blade of a sample APIM service on the Azure Portal and click on the Roles tab. This would display the list of roles that are available for assignment.

Step 2:

Search for the role you wish to clone (APIM Service Contributor in this case). At the end of the row, click the ellipsis (…) and then click Clone

Step 3: Configure the Basics section as follows

Step 4: Configure the Permissions section.

Retain the default permissions listed for this role.

Click on +Exclude Permissions and search for Microsoft API Management

Under Not Actions, select the permission ‘Delete: Delete API Management Service instance’ under Microsoft.ApiManagement/service on the succeeding Permissions page and click the Add button.

Step 5: Configure the Assignable Scopes section.

Delete the existing resource level scope. Click on +Add Assignable Scopes and set the scope to Subscription level. Click Add.

NOTE:

Each Azure Active Directory can only have a maximum of 5000 custom roles.

Hence, for a custom role where the assignable scope is configured to be at resource level, you could consider replacing it with a subscription or resource group level scope to prevent exhausting your custom role limit.

Constraints associated with custom roles can be found documented in the below article:

https://docs.microsoft.com/en-us/azure/role-based-access-control/custom-roles#custom-role-limits

Step 6: In the JSON section, you could also Download your custom RBAC role in JSON format for future usage or reference.

Step 7: Review the custom RBAC role details in the Review + Create section and click on Create.

It may take a few minutes for the custom role to be created and displayed under the list of available roles.

In this scenario, the newly created custom role would be available for assignment under the Roles section on the subscription’s Access Control (IAM) blade since the assignable scope was set at subscription level during creation.

NOTE:

Post creation, custom roles appear on the Azure portal with an orange resource icon (Built-in roles appear with blue icons).
Custom Roles would be available for assignment at the respective subscription, resource group or resource access control blade based on the assignable scope that has been configured during creation of the role.

Step 8: Assign this custom role to a user. Any user having this role would be able to perform all the operations that are offered by default by the APIM Service Contributor role except deleting APIM services in the subscription.

Scenario 2: Deny users having Reader access from reading Product subscription keys

Let us consider the built-in APIM RBAC role ‘API Management Service Reader’ role for this scenario.

Users often have a misconception that only the APIM Administrators would be able to view the Product subscription keys on the Azure Portal. However, that is not the case.

The ability to read subscription keys from products (an action which is defined as Microsoft.ApiManagement/service/products/subscriptions/read) is allowed by default for users having the ‘API Management Service Reader Role’. Same is the case for navigating to the keys via APIs/subscriptions.

Hence, as a workaround, you can create a custom RBAC role in order to block the subscription keys – read action.

NOTE:

The action Microsoft.ApiManagement/service/users/keys/read does not correspond to reading subscription keys. The 2 actions are completely different.

Every user has two “secrets”, a primary and a secondary. These secrets are used to generate an encrypted SSO token that users can use to access the developer portal. These keys are not related to the subscription keys that users use to call the APIs. The /service/users/keys/read permission corresponds to the ability to read the user secrets, whereas the /service/products/subscriptions/read permission corresponds to reading subscription keys under products, which is allowed by default under the ‘API Management Service Reader’ role.

Additionally, the Microsoft.ApiManagement/service/users/subscriptions/read permission corresponds to the ability to read subscriptions associated with users via the “Users” blade on the Portal, which is also allowed by default under this role.

Here, we are creating and assigning a custom RBAC role using PowerShell for denying users having Read access over the APIM service from reading the subscription keys. Basically, this role denies users from performing the operation Microsoft.ApiManagement/service/products/subscriptions/read

The sample PowerShell script is as below:

$role = Get-AzRoleDefinition "API Management Service Reader Role"
$role.Id = $null
$role.Name = 'Deny reading subscription keys'
$role.Description = 'Denies users from reading product subscription keys'
$role.NotActions.Clear()
$role.NotActions.Add('Microsoft.ApiManagement/service/products/subscriptions/read')
$role.AssignableScopes.Clear()
$role.AssignableScopes.Add('/subscriptions/<subscription ID>/resourceGroups/<resource group name>/providers/Microsoft.ApiManagement/service/<service name>')
New-AzRoleDefinition -Role $role
New-AzRoleAssignment -ObjectId <object ID of the user account> -RoleDefinitionName 'Deny reading subscription keys' -Scope '/subscriptions/<subscription ID>/resourceGroups/<resource group name>/providers/Microsoft.ApiManagement/service/<service name>'

Known Limitations

Current design does not allow RBAC permissions to be controlled at Product level for API creation/deletion.

For example, consider a scenario where users on the Azure Portal should have read and write access only over APIs that are associated with a particular Product. For this, you can configure an RBAC role where the assignable scope has been set at “Product” level and add the desired Actions and NotActions.

Now, even if you add the permission “Microsoft.ApiManagement/service/apis/*” at product scope, when the user who is assigned this role attempts creating a new API inside this Product, the operation would still fail.

If a user needs to create a new API in the service (irrespective of whether it is inside the same Product), they should be able to read all APIs in the service and have write permissions granted at the APIM service scope instead of Product scope.

This is because, when a user attempts to create a new API or add a new version/revision for an existing API, there is a validation check that happens in the background to verify if there is any other API in the service which is using the same path that the user is attempting to create. If the user performing this operation does not have permissions to read all APIs in the service, the operation would fail.

Hence, you would have to grant the user the permission to read all APIs in the service (granted at the service scope).

Permissions to view APIM Diagnostics Logs cannot be configured at APIM scope.

For example, if user has configured streaming of APIM Diagnostic Logs to a Log Analytics Workspace and wishes to create a custom RBAC role only for viewing these diagnostic logs, it wouldn’t be possible to configure this role at the APIM scope. Since the log destination is Log Analytics, the permission has to be configured at the Log Analytics scope.

The APIM ARM operation “Microsoft.ApiManagement/service/apis/diagnostics/read” only controls access to the diagnostic configuration for the APIM service and not to the diagnostic telemetry that APIM streams to external resources such as Log Analytics/Application Insights, et cetera.

Preventing users from accessing the Test Console for APIs on the Azure Portal cannot be achieved with a straight-forward approach.

This is because there are no APIM ARM operations that support actions corresponding to “Microsoft.ApiManagement/service/apis/operations/test”.

However, this limitation can be overcome if the API is protected by a subscription key. When the permission “Microsoft.ApiManagement/service/subscriptions/read” is denied to a user, the user cannot test an API protected by a subscription key since they wouldn’t be able to retrieve the subscription key required for testing the API operation.

A JSON sample for creating this custom role can be found attached below:

{
  "properties": {
    "roleName": "Deny Testing APIs",
    "description": "Deny Testing APIs",
    "assignableScopes": [
      "/subscriptions/<subscription ID>/resourceGroups/<resource group name>/providers/Microsoft.ApiManagement/service/<service name>"
    ],
    "permissions": [
      {
        "actions": [],
        "notActions": [
          "Microsoft.ApiManagement/service/subscriptions/read"
        ],
        "dataActions": [],
        "notDataActions": []
      }
    ]
  }
}

APPENDIX