This article guides you through creating and configuring an Azure Service Principal with Contributor access for policy deployment to a specified subscription scope. A properly configured Azure Service Principal is required to integrate the Cequence Unified API Protection (UAP) platform with the Azure APIM service.

Understanding Contributor Access

The Contributor role provides comprehensive management access to Azure resources with the following privileges and restrictions.

Privileges

• Create, update, and delete resources such as virtual machines, storage accounts, or API management services.
• Deploy resources using ARM templates or Bicep.
• Manage configuration and settings of Azure services.
• Start, stop, and restart services.
• View billing and resource usage information.

Restrictions

• Cannot manage access permissions, including RBAC assignment operations.
• Cannot grant or revoke access to other users or service principals.

Prerequisites

• Access to Azure Portal
• Appropriate permissions in Microsoft Entra ID (formerly Azure Active Directory)
• Bulk subscription assignment requires access to the Azure CLI tool

Note: The procecures in this article require access to Microsoft Entra ID. If your user account does not have access to Microsoft Entra ID, ask your administrator to create the service principal.

Registering a new application in Azure

An Azure Service Principal is a type of Azure application. Register a new application to use as the Azure Service Principal.

1. Log in to the Azure Portal.
2. In Azure Services, click Microsoft Entra ID. (formerly Azure Active Directory).
   If you cannot see this option, contact your administrator to create the Service Principal for you.
   
3. From the left side of the top navigation bar, click + Add > App registration.
   
   The application registry dialog box appears.
   
4. Fill in the required fields.
   • In Name, type a descriptive name for your Service Principal.
   • From the Supported account types list, select Single tenant.
   • Optionally, in Redirect URI, select a platform from the drop-down and type a redirect URI.
5. Click Register.
   A confirmation message indicates the Service Principal has been created.

The portal shows the details page for the new Service Principal.

Adding a Client Secret

The new Service Principal needs a client secret for authentication.

1. In the Essentials panel of the Service Prinicipal app, click the Certificates & secrets link.
   
   The Client Secrets page appears.
   
2. Click + New client secret.
   The New client secret panel appears.
   
3. Configure the secret.
   • Optionally, type a description in Description.
   • Type an expiration date in Expires.
4. Click Add.

Important: Copy the client secret value immediately and store it securely. For security reasons, the Azure portal cannot display this value again.

Note the following information in a secure location. These values are used in your config.jsonc file during several other procedures.

• Client ID (Application ID).
• Client Secret.
• Tenant ID.

Assigning Permissions to Subscriptions

Service Principals support one-to-many relationships, meaning a single Service Principal can access multiple subscriptions. You can assign permissions for subscriptions using several methods.

Method 1: Bulk Assignment using the Azure CLI

Use this method to assign permissions to multiple subscriptions simultaneously. You must have access to all the subscriptions for which you are assigning permissions, and you must have authenticated access to the Azure CLI.

From the Azure CLI, run the following command.

SP_APP_ID="your-service-principal-app-id"; \
ROLE="Contributor"; \
SP_OBJECT_ID=$(az ad sp show --id $SP_APP_ID --query "id" -o tsv); \
for SUB_ID in $(az account list --query "[].id" -o tsv); \
do echo "Assigning $ROLE to $SP_APP_ID in $SUB_ID..."; \
az role assignment create \
--assignee-object-id $SP_OBJECT_ID \
--assignee-principal-type ServicePrincipal \
--role "$ROLE" \
--scope "/subscriptions/$SUB_ID" done

Method 2: Manual Assignment using the Azure Portal

Use this method to assign permissions to individual subscriptions.

1. Log in to the Azure Portal.
2. In Azure Services, click Subscriptions.
   A list of subscriptions appears in the left navigation bar.
   
3. Click a subscription.
   The Subscription details pane appears.
4. In the left navigation bar of the Subscription details pane, click Access control (IAM).
   
   The Subscription details pane displays the Access Control pane.
5. From the + Add drop-down, select Add role assignment.
   
6. Click the Privileged administrator roles tab.
   
7. Click Contributor, then click Next.
   
8. Click the Members tab.
9. In the Members tab, click + Select members.
   The Select Members pane appears on the right side.
   
10. In the search field, type the name of a Service Principal, then select that Service Principal and click Select.
11. At the bottom left, click Review + assign.
12. Review the configuration and click Review + assign again.

Repeat this process for each subscription requiring access.

Verifying access

After obtaining the Service Principal credentials, verify access using the following steps:

1. Run the following commands to set environment variables.

   service_principal_id="your-client-id"
   service_principal_secret="your-client-secret" tenant_id="your-tenant-id"

2. Optionally, run the following commands to test authentication.

   az login --service-principal \
   -u "$service_principal_id" \
   -p "$service_principal_secret" \
   --tenant "$tenant_id"

3. Run the following command to list accessible subscriptions.

   az account list --query "[].{Name:name, ID:id}" -o table

Troubleshooting

• If you cannot access Microsoft Entra ID, contact your Azure administrator.
• Ensure the Service Principal has been assigned to the correct subscription scope.
• Verify that client credentials are correctly configured in your config.jsonc.
• Check Azure Activity Logs for authentication and authorization issues.