API Permissions

Delegated Permissions (User Context)

What: Application acts on behalf of a signed-in user

When to use:

• User is present and can consent
• App needs to access resources as the user
• Interactive authentication flows

Examples:

• Read user’s email
• Update user’s calendar
• Access user’s OneDrive files

Scope format: User must consent (or admin pre-consents)

Application Permissions (App Context)

What: Application acts with its own identity (no user)

When to use:

• Background services, daemons
• Scheduled jobs
• API-to-API calls without user

Examples:

• Read all users in organization
• Send mail as any user
• Access all SharePoint sites

Requirement: Always requires admin consent

Permission Scopes

Understanding Scopes

Scope: A string that defines what access is granted

Format:

.default Scope

Special scope that includes all configured permissions:

When to use:

• Client credentials flow (always)
• Want all pre-configured permissions
• Migrating from v1.0 endpoint

Microsoft Graph Permissions

Common Delegated Permissions

Common Application Permissions

Adding Permissions

Azure Portal Method

1. Navigate to your app registration

2. Click “API permissions” in left menu

3. Click “+ Add a permission”

4. Choose API source:

   • Microsoft APIs (Graph, Office 365, etc.)
   • APIs my organization uses (custom APIs)
   • My APIs (your own APIs)

5. Select permission type:

   • Delegated permissions (user context)
   • Application permissions (app context)

6. Search and select permissions

7. Click “Add permissions”

See cli-commands.md for az cli commands to add API permissions programmatically.

Finding Permission IDs

Method 1: Azure Portal

1. Go to Microsoft Entra ID → Enterprise applications
2. Search for “Microsoft Graph”
3. Click on it → Permissions
4. Browse available permissions and copy IDs

Method 2: Microsoft Graph Explorer

1. Visit https://developer.microsoft.com/graph/graph-explorer (opens in a new tab)
2. Click “Modify permissions”
3. Browse and view permission details

Method 3: Microsoft Documentation

Visit: https://learn.microsoft.com/en-us/graph/permissions-reference (opens in a new tab)

Method 4: Azure CLI Query

Granting Admin Consent

When Admin Consent is Required

Always required for:

• All application permissions
• High-privilege delegated permissions
• When organization disables user consent

Examples requiring admin consent:

• User.Read.All (read all users)
• Directory.Read.All (read directory)
• Mail.Read (application permission)
• Sites.Read.All (read all SharePoint sites)

How to Grant Admin Consent

Portal Method:

1. Go to API permissions
2. Click “Grant admin consent for [Your Org]”
3. Confirm the action
4. Check for green checkmarks next to permissions

CLI Method:

Verifying Consent Status

Portal: Look for green checkmarks in “Status” column

CLI:

Look for consentType: "AllPrincipals" (admin consented)

Custom API Permissions

Exposing Your API

If you’re building an API that other apps will call:

1. In your API’s app registration, go to “Expose an API”
2. Set Application ID URI: api://your-api-id
3. Click “+ Add a scope”
4. Configure scope:
   • Scope name: access_as_user
   • Who can consent: Admins and users
   • Display name: “Access MyAPI as user”
   • Description: Clear description of what this allows
5. Click “Add scope”

Effective Permissions

User + App Permissions

Delegated permissions: Intersection of user’s permissions and app’s permissions

Example:

• User can: Read all users

• App granted: User.Read.All

• Effective: Read all users ✅

• User can: Only read their own profile

• App granted: User.Read.All

• Effective: Only read own profile (limited by user’s rights)

Application permissions: Only app’s permissions matter (no user context)

Troubleshooting Permissions

“Insufficient privileges” Error

Causes:

• Permission not added to app registration
• Admin consent not granted
• User lacks permission in directory
• Accessing resource outside permission scope

Solutions:

1. Check API permissions in portal
2. Grant admin consent if needed
3. Verify user has access to resource
4. Use correct permission scope

“Consent required” Error

Causes:

• User hasn’t consented to permissions
• Admin consent required but not granted
• Token obtained before permission added

Solutions:

1. Request user consent (interactive flow)
2. Admin grants consent (portal or CLI)
3. Acquire new token after adding permissions

Permission Appears Granted but Doesn’t Work

Possible issues:

• Using old cached token (get new one)
• Permission is delegated but user lacks rights
• API requires additional configuration
• Permission deprecated (use new one)

Debug steps:

1. Decode access token: https://jwt.ms (opens in a new tab)
2. Check scp claim (delegated) or roles claim (application)
3. Verify permission is present in token
4. Check if permission is correct type (delegated vs application)

Permission Best Practices

Development

✅ Do:

• Start with minimal permissions
• Add incrementally as features require
• Test with non-admin accounts
• Document why each permission is needed

❌ Don’t:

• Request all permissions “just in case”
• Use admin account for testing only
• Forget to grant admin consent for app permissions

Production

✅ Do:

• Review permissions quarterly
• Remove unused permissions
• Use least privilege principle
• Monitor permission usage
• Document all permissions in README

❌ Don’t:

• Grant excessive permissions for convenience
• Use application permissions when delegated would work
• Forget to rotate admin consent approvals

Security

✅ Do:

• Prefer delegated over application permissions
• Implement proper scope validation
• Log permission usage
• Handle consent errors gracefully

❌ Don’t:

• Hardcode permission scopes in multiple places
• Skip token validation
• Ignore scope mismatches
• Cache permissions indefinitely

Reference Tables

Microsoft Graph Permission IDs

Delegated Permissions:

Application Permissions:

Note: Permission IDs may change. Always verify against the official Microsoft Graph Permissions Reference (opens in a new tab) for the most current values.

Additional Resources

• Microsoft Graph Permissions Reference (opens in a new tab)
• Permission Types (opens in a new tab)
• Admin Consent Workflow (opens in a new tab)
• Consent Framework (opens in a new tab)

Nearby

• NextReference Auth Best Practices