Quick Tip: RBAC for individual APIs in APIM

Azure API Management is a service that allows you to managed your APIs centrally in one place, manage products and subscriptions to your APIs, apply policies to requests, and integrate many different Azure Services like AKS, Azure Functions, Azure EventHub and many more. Usually Teams own one or more of these APIs. As an administrator you want your teams to manage their own APIs (e.g., add and update operations, create revisions, etc.), but not manage the service itself. In this quick tip we’re going to create a custom role for that.

This guide assumes you already have your APIM service set up. You should also have the PowerShell module installed. There are already some built-in roles in Azure API Management. At the time of writing they are as follows:

Role	Read Access¹	Write Access²	Service management³	Description
API Management Service Contributor	✔	✔	✔	Super user. Has full CRUD access to API Management services and entities (for example, APIs and policies). Has access to the legacy publisher portal.
API Management Service Reader	✔	❌	❌	Has read-only access to API Management services and entities.
API Management Service Operator	✔	❌	✔	Can manage API Management services, but not entities.

There is one role missing though: The one that has both read and write access, but can’t do any service management. This is probably somewhat on purpose: Everyone should create their custom roles for their individual dev teams and figure out which permissions they actually need. Let’s try to create this custom role, then!

> # At first, we start with the reader role
> $role = Get-AzRoleDefinition "API Management Service Reader Role"
> $role.Id = $null
> $role.Name = 'API Contributor'
> $role.Description = 'Has read access to the APIM instance and 
      write access to any assigned API.'

> # Then we add new permissions to the role
> $role.Actions.Add('Microsoft.ApiManagement/service/apis/write')
> $role.Actions.Add('Microsoft.ApiManagement/service/apis/*/write')

# Next we define the assignable scopes of the API
> $role.AssignableScopes.Clear()
> $role.AssignableScopes.Add('/subscriptions/<Azure subscription ID>/resourceGroups
    /<resource group name>/providers/Microsoft.ApiManagement
    /service/<APIM service instance name>')

Let’s talk about scopes for a bit. If you create roles, you specify what the maximum scope is in which they can be assigned. Usually the top scope is a subscription (or a management group). The next scope would be a resource group, then a service (like APIM or AKS) and finally subresources like in APIM’s case APIs. Roles can be assigned in a smaller scope, but never in a bigger one. This means if a role can be assigned at subscription scope, it can also be applied at resource group scope.

Gotcha!

Please note that you need Azure AD P1 or P2 to create roles at subscription scope. Yeah, I don’t make the rules…

We are going to created a role in APIM Service Scope.The Role Bindings are in API scope, though:

> New-AzRoleDefinition 
  -Role $role 
  -Scope '/subscriptions/<subscription ID>/resourceGroups/<resource group name>
          /providers/Microsoft.ApiManagement/service/<APIM service instance name>'
> New-AzRoleAssignment 
  -ObjectId <object ID of the user account> 
  -RoleDefinitionName 'API Contributor' 
  -Scope '/subscriptions/<subscription ID>/resourceGroups/<resource group name>
          /providers/Microsoft.ApiManagement/service/<APIM service instance name>
          /apis/<API name>'

To summarize: We have a role at APIM service scope, however all our role bindings are at API scope. Use can now edit the APIs for which they have the role bindings.

If you want to use this role for your entire subscription, you just need to change the scope in which to create the role.

Finally, this role might not necessarily suffice for you: Users are not allowed to delete operations, for example. Please consult the official list of permissions to check which permissions the role should include.

Edit 21/OCT/2022: A reader made me aware of some typos that I promptly fixed.

Read access to API Management services and entities (for example, APIs and policies). ↩
Write access to API Management services and entities except the following operations: instance creation, deletion, and scaling; VPN configuration; and custom domain setup. ↩
Service creation, deletion, scaling, VPN, and custom domain configuration. ↩

Quick Tip: RBAC for individual APIs in APIM

Footnotes