How to Assign Permissions to Azure Management APIs with PowerShell

In a world of APIs, Microsoft Azure has you covered. Through it’s Azure API Management platform, it can help those of us that need to build APIs into products and services.

One important task to address when managing APIs in Azure is permissions. You should properly define and address concerns like:

• Who should be able to query an endpoint?
• What methods are permissible at what times?
• How to granularly control access by user, service, etc?
• …and many more

Azure, like many other services, controls access via role-based access control (RBAC). Through defining and allow specific roles, you can define scopes for many different purposes. These scopes then control, at a granular level, what can and can’t be accessed.

There are a few ways to manage API role assignments. One useful way is to use PowerShell. If your organization already has various PowerShell scripts and need to automate this process, using PowerShell is a great choice.

Creating new Azure API Management role assignments consists of a few rough steps:

• Defining all APIs to assign access to
• Finding the scopes of all the APIs you’d like to assign access to
• Creating an Azure role definition only scoped to those APIs
• Assigning that role definition to all of the APIs

Let’s go over how we can make this happen.

Prerequisites

If you intend to follow along with the examples given in this article, be sure you have:

• Windows PowerShell 5.1 or PowerShell Core 6+ installed
• The Az PowerShell modules installed (Install-Module -Name Az)
• Authenticated to your Azure subscription with [Connect-AzAccount](https://adamtheautomator.com/connect-azaccount-powershell/)
• An Azure API Management service created with a single API

Establishing Context

Before you can do much at all with Azure API in PowerShell, you must first create a new context. To create a new context, use the New-AzApiManagementContext command. Run this command specifying the resource group and the name of your API Management service.

$azrContext = New-AzManagementContext -ResourceGroupName $ApiManagementServiceResourceGroup -ServiceName $ApiManagementServiceName

Targeting APIs

Once you have a context object created, the next task is discovering the APIs you intend to apply the new role to. In PowerShell, the way to do that is with Get-AzApiManagementApi.

In the below example, the code is finding all APIs with a naming match a string in $ApiMatchPattern.

$apis = Get-AzureRmApiManagementApi -Context $azrContext).where({ $_.Name -match $ApiMatchPattern })

Creating Scopes

To create a role definition, you need to have one or more scopes defined. These scopes will be what is assigned to the role definitions upon creation.

You can see below an example of code that’s using the API IDs returned above and creating scope strings for each one. Be sure to fill in the values for each of the variables specific to your environment.

$scopes = $apis.ApiId | foreach {
    $strFormat = $AzureSubscriptionId,$ApiManagementServiceResourceGroup,$ApiManagementServiceName,$_
    '/subscriptions/{0}/resourceGroups/{1}/providers/Microsoft.ApiManagement/service/{2}/apis/{3}' -f $strFormat
}

Creating Role Definitions

Once you have the scopes defined, it’s time to create the role definitions. Below you can see an example of one way you can create role definitions for reader roles.

if (-not (Get-AzRoleDefinition -Name $AzureRoleName)) {
    Write-Verbose -Message "No role with name [$($AzureRoleName)] found. Creating..."

    switch ($APIRights) {
        'Read' {
            ## Use the API Management Service Reader Role as a template
            $role = Get-AzRoleDefinition 'API Management Service Reader Role'
            $role.Actions.Add('Microsoft.ApiManagement/service/apis/read')
        }
        default {
            throw "Unrecognized input: [$_]"
        }
    }

    $role.Id = $null
    $role.Name = $AzureRoleName
    $role.Description = $AzureRoleDescription
    $role.AssignableScopes.Clear()

    $scopes | foreach {
        $role.AssignableScopes.Add($_)
    }
    New-AzRoleDefinition -Role $role
}

Adding the Role Assignments

Finally, it’s time to create the role assignments with the Nw-AzRoleAssignment cmdlet. The role assignment first needs the group ID the role is being assigned to. You can find that by looking for the group with Get-AzAdGroup cmdlet.

Once you have the principal ID, you can then create a role assignment for each scope string created earlier.

$principal = Get-AzADGroup -SearchString $PrincipalName
$principalId = $principal.Id.Guid

$scopes | foreach {
    New-AzRoleAssignment -ObjectId $principalId -RoleDefinitionName $AzureRoleName -Scope $_
}

Once the role assignments are created, you’re all done!

Summary

You have learned in this article how to create and assign Azure roles to APIs with PowerShell. If you’d like to download the code provided in this article, you can do so by running Install-Script -Name Grand-AzureApiAccess.

The examples provided only cover one use case though. Using PowerShell, you can build more complex logic into scripts and automate the entire API permission assignment process too.

Explore the API PowerShell cmdlets and see what kind of automation you can come up with!