Securing Your Backend API with Entra ID: Step-by-Step Guide from App Roles to Client API

Managing authentication and authorisation in Azure Active Directory (Entra ID) is critical for securing APIs in modern enterprise applications. Without proper configuration, your backend API cannot reliably verify whether a user or client has the necessary permission to perform specific actions. In this comprehensive guide, we’ll walk you through creating a Backend API, a Client API, defining app roles via the Azure Portal, assigning them to users or applications, and retrieving access tokens containing these roles for secure API access.

Why App Roles Are Essential in Entra ID

Entra ID App Roles allow you to:

  1. Control access for users and apps.
  2. Include roles in access tokens.
  3. Enforce access control in APIs.
  4. Implement role-based access without code changes.

⚠️ Without properly defining and assigning app roles, your backend API cannot differentiate between users or clients with different access levels.

Step 1: Create the Backend API App Registration

  1. Navigate to Azure Portal → App registrations → New registration.
  2. Fill in the registration details:
    • Name: BackendAPI
    • Supported account types: Single tenant (Accounts in this organizational directory only)
    • Redirect URI: Leave blank (optional)
  3. Click Register.
  4. Save the Application (client) ID and Directory (tenant) ID — these will be used later.
  5. Configure your API for access:
    • Go to Expose an API → Set Application ID URI, e.g., api://<Backend-API-App-ID>.
    • Optional: Add a delegated scope for user consent:
      • Scope name: User.Read
      • Who can consent: Admins only or Users
      • Admin consent display name/description

Step 2: Add App Roles via Azure Portal UI

Instead of editing the manifest, use the UI to create app roles for better maintainability:

  1. Navigate to your BackendAPI app registration.
  2. Go to App roles (under “Manage” in the left menu).
  3. Click Create app role and provide:
    • Display name: Customer.Write
    • Value: Customer.Write (this appears in access tokens)
    • Description: Permission to write customer data
    • Allowed member types: User, Application, or both
    • Enable role: Yes
  4. Click Apply.

Step 3: Assign App Roles to Users or Client Applications

Roles must be assigned to take effect in access tokens:

  1. Go to Azure Portal → Enterprise applications → BackendAPI.
  2. Navigate to Users and groups → Add user/group → Assign role.
  3. Select:
    • Role: Customer.Write
    • User or Client App: the entity that should have access
  4. Click Save.

⚠️ Without this assignment, the roles claim will not appear in tokens.

Step 4: Create the Client App Registration

  1. Navigate to App registrations → New registration.
  2. Enter:
    • Name: ClientAPI
    • Supported account types: Single tenant
    • Redirect URI: e.g., https://app.getpostman.com/oauth2/callback
  3. Click Register.
  4. Save the Client ID for token requests.

Step 5: Configure Client App Permissions

  1. Go to ClientAPI → API permissions → Add a permission.
  2. Select My APIs → BackendAPI.
  3. Choose the required permissions:
    • Delegated permissions: scopes like User.Read
    • Application permissions: roles like Customer.Write
  4. Click Add permissions.
  5. Optional: Click Grant admin consent for your tenant to pre-authorise all users.

Step 6: Request Access Tokens from Entra ID

Delegated Flow (User-based)

  1. Direct users to the authorisation endpoint:
GET https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize?
client_id={ClientAPI-ID}&
response_type=code&
redirect_uri={redirect-uri}&
scope=api://{BackendAPI-ID}/.default&
response_mode=query&
state=12345
  1. Exchange the authorisation code for a token:
POST https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id={ClientAPI-ID}&
scope=api://{BackendAPI-ID}/.default&
redirect_uri={redirect-uri}&
grant_type=authorization_code&
code={authorization-code}&
client_secret={client-secret}

Client Credentials Flow (Application-only)

POST https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id={ClientAPI-ID}&
scope=api://{BackendAPI-ID}/.default&
grant_type=client_credentials&
client_secret={client-secret}

✅ The returned token includes the roles claim:
"roles": ["Customer.Write"]

Step 7: Call the Backend API Using the Access Token

Include the token in the Authorisation header:

Authorization: Bearer <access_token>

In your backend API, validate roles before allowing sensitive actions:

if (!user.Claims.Any(c => c.Type == "roles" && c.Value == "Customer.Write"))
{
    return Forbid();
}

Step 8: Integrate Enterprise Apps

For enterprise deployments:

  1. Assign users or client apps in Enterprise applications → ClientAPI → Users and groups.
  2. Use Admin consent to pre-authorise all users, reducing friction during login.

Summary

Securing your APIs with Azure Active Directory ensures that only authorised users and applications can access sensitive resources. By defining App Roles in the Backend API, assigning them to users or client applications, and properly configuring the Client API to request tokens, you can implement robust role-based access control (RBAC).

Whether using the delegated flow for user-based access or the client credentials flow for application-only access, validating the roles claim in your backend API enforces fine-grained permissions efficiently. This approach not only simplifies security management but also prepares your applications for enterprise-scale deployment.

✅ Key takeaway: Use the Entra ID App Roles, assign roles in Enterprise Applications, and validate tokens in your backend API to achieve secure, scalable, and maintainable API access.