Part 5: API Permissions and Consent

The Admin Consent That Saved Hours

I once spent a full afternoon debugging why my app couldn't read user profiles from Microsoft Graph. The code was perfect. The scopes were configured. The token was valid. Yet every call returned "Insufficient privileges."

The fix? One click: "Grant admin consent." Two seconds to fix what I'd spent hours troubleshooting.

Understanding permissions and consent is critical—not just for making things work, but for making them work securely.

Delegated vs Application Permissions

This is THE fundamental concept in MS Entra permissions.

Delegated Permissions

Scenario: Acting on behalf of a signed-in user Who: User gives permission to app Scope: Limited to what the user can do

// User Bob signs into your app
// App requests: User.Read (delegated)
// Result: App can read Bob's profile
//         But ONLY Bob's profile, not Alice's

{
  "scp": "User.Read",           // Scope (delegated permission)
  "sub": "bob-user-id",          // Bob's ID
  "aud": "your-app-id"
}

Real-world example:

// React SPA reading signed-in user's email
const response = await msalInstance.acquireTokenSilent({
  scopes: ["User.Read"]  // Delegated permission
});

// Call Graph API as the user
const graphResponse = await fetch("https://graph.microsoft.com/v1.0/me", {
  headers: { "Authorization": `Bearer ${response.accessToken}` }
});

const user = await graphResponse.json();
console.log(user.mail);  // Bob's email (because Bob signed in)

Application Permissions

Scenario: App acts with its own identity Who: Admin gives permission to app Scope: App can access anything the permission allows

// No user signed in
// App uses client credentials
// App has: User.Read.All (application permission)
// Result: App can read ANY user's profile

{
  "roles": ["User.Read.All"],    // Role (application permission)
  "sub": "service-principal-id",  // App's ID, not a user
  "aud": "https://graph.microsoft.com"
}

Real-world example:

// Scheduled job syncing all users
import { ClientSecretCredential } from "@azure/identity";
import { Client } from "@microsoft/microsoft-graph-client";

const credential = new ClientSecretCredential(
  process.env.TENANT_ID!,
  process.env.CLIENT_ID!,
  process.env.CLIENT_SECRET!
);

const token = await credential.getToken("https://graph.microsoft.com/.default");

const client = Client.init({
  authProvider: (done) => done(null, token.token)
});

// Read ALL users (no signed-in user context)
const users = await client.api("/users").get();
console.log(`Found ${users.value.length} users`);

Comparison Table

interface PermissionComparison {
  aspect: string;
  delegated: string;
  application: string;
}

const comparison: PermissionComparison[] = [
  {
    aspect: "User Context",
    delegated: "✅ Yes - acts as signed-in user",
    application: "❌ No - acts as the app"
  },
  {
    aspect: "Consent",
    delegated: "User can consent (usually)",
    application: "Admin must consent (always)"
  },
  {
    aspect: "Token Claim",
    delegated: "scp (scopes)",
    application: "roles (app roles)"
  },
  {
    aspect: "Use Case",
    delegated: "Interactive apps (SPAs, mobile)",
    application: "Daemons, background jobs"
  },
  {
    aspect: "Access Scope",
    delegated: "Limited to user's permissions",
    application: "Full access per permission"
  }
];

Microsoft Graph Permissions

Microsoft Graph is the unified API for Microsoft 365 services. Let's explore common permissions.

User Permissions

// Delegated Permissions
interface UserDelegatedPermissions {
  "User.Read": "Read user's profile";              // Most common
  "User.ReadWrite": "Read and update user profile";
  "User.ReadBasic.All": "Read basic info of all users";
  "User.Read.All": "Read full profiles of all users";
  "User.ReadWrite.All": "Read and update all user profiles";
}

// Application Permissions
interface UserApplicationPermissions {
  "User.Read.All": "Read all users in directory";
  "User.ReadWrite.All": "Read and write all users";
  "User.Export.All": "Export user data";
}

Example: Reading user profile

// Frontend (delegated: User.Read)
const scopes = ["User.Read"];
const token = await msalInstance.acquireTokenSilent({ scopes, account });

const response = await fetch("https://graph.microsoft.com/v1.0/me", {
  headers: { "Authorization": `Bearer ${token.accessToken}` }
});

const user = await response.json();
// {
//   "id": "user-id",
//   "displayName": "John Doe",
//   "mail": "[email protected]",
//   "jobTitle": "Developer"
// }

Mail Permissions

// Delegated
interface MailDelegatedPermissions {
  "Mail.Read": "Read user's mail";
  "Mail.ReadWrite": "Read and write user's mail";
  "Mail.Send": "Send mail as user";
}

// Example: Sending email as signed-in user
const scopes = ["Mail.Send"];
const token = await getToken(scopes);

await fetch("https://graph.microsoft.com/v1.0/me/sendMail", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    message: {
      subject: "Payment Confirmation",
      body: {
        contentType: "HTML",
        content: "<p>Your payment was successful</p>"
      },
      toRecipients: [
        { emailAddress: { address: "[email protected]" } }
      ]
    }
  })
});

Calendar Permissions

// Delegated
interface CalendarDelegatedPermissions {
  "Calendars.Read": "Read user's calendars";
  "Calendars.ReadWrite": "Read and write user's calendars";
}

// Example: Reading user's calendar
const scopes = ["Calendars.Read"];
const token = await getToken(scopes);

const response = await fetch(
  "https://graph.microsoft.com/v1.0/me/calendar/events",
  {
    headers: { "Authorization": `Bearer ${token}` }
  }
);

const events = await response.json();

Files Permissions

// SharePoint/OneDrive
interface FilesDelegatedPermissions {
  "Files.Read": "Read user's files";
  "Files.ReadWrite": "Read and write user's files";
  "Files.Read.All": "Read all files user can access";
  "Files.ReadWrite.All": "Read and write all files user can access";
}

Teams Permissions

// Microsoft Teams
interface TeamsDelegatedPermissions {
  "Team.ReadBasic.All": "Read team names and descriptions";
  "Channel.ReadBasic.All": "Read channel names and descriptions";
  "ChatMessage.Read": "Read user's chat messages";
  "ChatMessage.Send": "Send chat messages as user";
}

API Permission Configuration

Let's configure permissions for a real application.

Scenario: POS System with Multiple Services

Frontend SPA needs:

• Read signed-in user's profile

• Read payment transactions

• Create new payments

Backend Payment API needs:

• Read user details (delegated - on behalf of signed-in user)

• Send email notifications (application - background job)

Frontend SPA Configuration

# Azure Portal → App registrations → payment-spaAPI Permissions:
  Microsoft Graph (Delegated):
    - User.Read
    
  payment-api (Delegated):
    - Payments.Read
    - Payments.Write

Frontend code:

const loginRequest = {
  scopes: [
    "User.Read",                           // Microsoft Graph
    "api://payment-api/Payments.Read",     // Custom API
    "api://payment-api/Payments.Write"
  ]
};

const response = await msalInstance.loginPopup(loginRequest);

Backend API Configuration

# Azure Portal → App registrations → payment-api

API Permissions:
  Microsoft Graph (Delegated):
    - User.Read           # Read user when they're signed in
    
  Microsoft Graph (Application):
    - Mail.Send           # Send emails in background
    - User.Read.All       # Read user details for any user

Expose an API:
  Application ID URI: api://payment-api
  
  Scopes:
    - Payments.Read
      Description: "Read payment transactions"
      Who can consent: Admins and users
      
    - Payments.Write
      Description: "Create payment transactions"
      Who can consent: Admins and users

Consent Framework

Consent is how users/admins grant permissions to applications.

User Consent

When a user first signs in, they see consent screen:

Payment App wants to:
  ☑ Read your profile
  ☑ Read your payment history
  ☑ Create payments on your behalf

[Accept] [Cancel]

Implementation:

try {
  const response = await msalInstance.loginPopup({
    scopes: ["User.Read", "api://payment-api/Payments.Read"],
    prompt: "consent"  // Force consent screen even if previously consented
  });
} catch (error) {
  if (error.errorCode === "consent_required") {
    // User declined consent
  }
}

Admin Consent

Some permissions require admin approval:

Requires admin consent:

• Any Application permission (e.g., User.Read.All)

• High-privilege delegated permissions (e.g., Mail.ReadWrite.All)

• Organization-wide permissions

Granting admin consent:

Option 1: Azure Portal

App registration → API permissions → Grant admin consent for {tenant}

Option 2: Admin Consent URL

https://login.microsoftonline.com/{tenant}/adminconsent
  ?client_id={client-id}
  &redirect_uri={redirect-uri}

Example: Admin consent flow

// Generate admin consent URL
function getAdminConsentUrl(tenantId: string, clientId: string, redirectUri: string): string {
  return `https://login.microsoftonline.com/${tenantId}/adminconsent?client_id=${clientId}&redirect_uri=${encodeURIComponent(redirectUri)}`;
}

// Admin clicks link, grants consent
const consentUrl = getAdminConsentUrl(
  "my-tenant-id",
  "my-client-id",
  "https://myapp.com/admin-consent-callback"
);

// After consent, admin redirected to:
// https://myapp.com/admin-consent-callback?tenant=...&state=...&admin_consent=True

Incremental Consent

Don't ask for all permissions upfront. Request them as needed.

// Step 1: Login with minimal scope
await msalInstance.loginPopup({
  scopes: ["User.Read"]  // Just basic profile
});

// Step 2: Later, when user wants to send email
try {
  await msalInstance.acquireTokenSilent({
    scopes: ["Mail.Send"]  // Request additional scope
  });
} catch (error) {
  // Silent acquisition failed, need user consent
  await msalInstance.acquireTokenPopup({
    scopes: ["Mail.Send"]
  });
}

Custom API Permissions

Let's expose permissions in your own API.

Payment API Example

Step 1: Define scopes

# Azure Portal → App registration → Expose an API

Application ID URI: api://payment-api

Scopes:
  1. Payments.Read
     Admin consent display name: "Read payment transactions"
     Admin consent description: "Allows the app to read payment transactions"
     User consent display name: "Access your payment history"
     User consent description: "Allows the app to read your payment transactions"
     State: Enabled
     
  2. Payments.Write
     Admin consent display name: "Create payment transactions"
     Admin consent description: "Allows the app to create payment transactions"
     User consent display name: "Create payments"
     User consent description: "Allows the app to create payments on your behalf"
     State: Enabled
     
  3. Payments.Admin
     Admin consent display name: "Full payment administration"
     Admin consent description: "Allows the app to manage all payment operations"
     Who can consent: Admins only
     State: Enabled

Step 2: Validate scopes in API

// payment-api/src/middleware/auth.ts
import { expressjwt as jwt } from "express-jwt";
import jwksRsa from "jwks-rsa";

// Validate JWT
const jwtCheck = jwt({
  secret: jwksRsa.expressJwtSecret({
    cache: true,
    rateLimit: true,
    jwksUri: `https://login.microsoftonline.com/${process.env.TENANT_ID}/discovery/v2.0/keys`
  }),
  audience: process.env.CLIENT_ID,
  issuer: `https://login.microsoftonline.com/${process.env.TENANT_ID}/v2.0`,
  algorithms: ["RS256"]
});

// Check scopes
function requireScope(...requiredScopes: string[]) {
  return (req: any, res: any, next: any) => {
    const tokenScopes = req.auth.scp?.split(" ") || [];
    
    const hasRequiredScope = requiredScopes.some(scope =>
      tokenScopes.includes(scope)
    );
    
    if (!hasRequiredScope) {
      return res.status(403).json({
        error: "insufficient_scope",
        error_description: `Required scopes: ${requiredScopes.join(", ")}`
      });
    }
    
    next();
  };
}

// Usage
app.get("/api/payments",
  jwtCheck,
  requireScope("Payments.Read"),
  async (req, res) => {
    const payments = await getPayments();
    res.json(payments);
  }
);

app.post("/api/payments",
  jwtCheck,
  requireScope("Payments.Write"),
  async (req, res) => {
    const payment = await createPayment(req.body);
    res.json(payment);
  }
);

app.delete("/api/payments/:id",
  jwtCheck,
  requireScope("Payments.Admin"),  // Admin only
  async (req, res) => {
    await deletePayment(req.params.id);
    res.json({ success: true });
  }
);

Pre-Authorization

Pre-authorize client apps to skip consent for specific permissions.

# Azure Portal → payment-api → Expose an API → Authorized client applications

Add a client application:
  Client ID: frontend-spa-client-id
  Authorized scopes:
    ☑ Payments.Read
    ☑ Payments.Write

Result: Users don't see consent screen for these permissions.

Code example:

// Frontend requests pre-authorized permissions
// No consent prompt shown
const response = await msalInstance.loginPopup({
  scopes: [
    "api://payment-api/Payments.Read",
    "api://payment-api/Payments.Write"
  ]
});
// User signed in without seeing consent screen

App Roles (Role-Based Access Control)

App roles are different from scopes. They represent user roles within your application.

Defining App Roles

// App registration → Manifest
{
  "appRoles": [
    {
      "allowedMemberTypes": ["User"],
      "displayName": "Payment Administrator",
      "id": "guid-1",
      "isEnabled": true,
      "description": "Can manage all payments",
      "value": "Payment.Admin"
    },
    {
      "allowedMemberTypes": ["User"],
      "displayName": "Finance User",
      "id": "guid-2",
      "isEnabled": true,
      "description": "Can view and create payments",
      "value": "Payment.Finance"
    },
    {
      "allowedMemberTypes": ["User"],
      "displayName": "Viewer",
      "id": "guid-3",
      "isEnabled": true,
      "description": "Can only view payments",
      "value": "Payment.Viewer"
    }
  ]
}

Assigning Roles to Users

Azure Portal → Enterprise application → Users and groups → 
Add user/group → Select role

Using Roles in Code

// Tokens include roles
{
  "roles": ["Payment.Admin", "Payment.Finance"]
}

// Middleware to check roles
function requireRole(...allowedRoles: string[]) {
  return (req: any, res: any, next: any) => {
    const userRoles = req.auth.roles || [];
    
    const hasRole = allowedRoles.some(role => userRoles.includes(role));
    
    if (!hasRole) {
      return res.status(403).json({
        error: "insufficient_permissions",
        error_description: `Required roles: ${allowedRoles.join(", ")}`
      });
    }
    
    next();
  };
}

// Usage
app.delete("/api/payments/:id",
  jwtCheck,
  requireRole("Payment.Admin"),  // Only admins
  async (req, res) => {
    await deletePayment(req.params.id);
    res.json({ success: true });
  }
);

app.post("/api/payments",
  jwtCheck,
  requireRole("Payment.Admin", "Payment.Finance"),  // Admins or finance
  async (req, res) => {
    const payment = await createPayment(req.body);
    res.json(payment);
  }
);

app.get("/api/payments",
  jwtCheck,
  requireRole("Payment.Admin", "Payment.Finance", "Payment.Viewer"),  // All roles
  async (req, res) => {
    const payments = await getPayments(req.auth.oid);
    res.json(payments);
  }
);

Least Privilege Principle

Always request the minimum permissions needed.

Bad Example

// ❌ Requesting excessive permissions
const scopes = [
  "User.Read.All",           // Don't need to read all users
  "Mail.ReadWrite.All",      // Don't need to read/write everyone's mail
  "Files.ReadWrite.All",     // Don't need access to all files
  "Mail.Send"                // Actually need this
];

Good Example

// ✅ Request only what's needed
const scopes = [
  "Mail.Send"                // Just sending email
];

// Later, if needed:
if (needsUserProfile) {
  await acquireToken({ scopes: ["User.Read"] });  // Incremental consent
}

Common Pitfalls

Pitfall 1: Confusing Delegated and Application

// ❌ Using application permission in delegated flow
const scopes = ["User.Read.All"];  // This is app permission format
await msalInstance.loginPopup({ scopes });  // Won't work

// ✅ Use correct permission type
const scopes = ["User.Read"];  // Delegated permission
await msalInstance.loginPopup({ scopes });

Pitfall 2: Not Granting Admin Consent

// ❌ Application permission without admin consent
// Configured: Mail.Send (Application)
// Admin consent: Not granted
// Result: "Insufficient privileges" errors

// ✅ Grant admin consent in portal
// Then application permissions work

Pitfall 3: Over-Privileging

// ❌ Granting Calendar.ReadWrite when you only read
const scopes = ["Calendars.ReadWrite"];

// ✅ Request minimal permission
const scopes = ["Calendars.Read"];

Key Takeaways

1. Delegated = On Behalf of User: App acts as signed-in user

2. Application = App's Own Identity: App acts independently

3. Admin Consent Required: For application permissions

4. Incremental Consent: Request permissions as needed

5. Least Privilege: Always request minimum necessary

6. Scopes vs Roles: Scopes for APIs, roles for users

7. Pre-Authorize: Skip consent for trusted apps

What's Next

In Part 6: Protecting APIs with MS Entra, we'll implement:

• Complete API authentication setup

• Token validation middleware

• Multi-tenant API configurations

• Error handling best practices

• Performance optimization

• Real production examples

Now that you understand permissions, let's see how to enforce them properly in your APIs.

---

Previous: Part 4: Tokens and Token Management Next: Part 6: Protecting APIs with MS Entra Back to Series Overview