Section purpose

This section bridges the identity and permission model from Sections 1 and 2 into practical automation. The focus is on how workloads acquire tokens, how to inspect those tokens to diagnose permission problems, and how to call the Microsoft Graph API and other Azure APIs correctly and efficiently. You do not need a developer background. Everything in this section is taught from first principles.

Learning Objectives

• How managed identity authentication works and what the IMDS endpoint does
• Why Azure IMDS request protections matter and why least privilege still matters for SSRF defense
• How to acquire tokens for any Azure service using Az PowerShell, Azure CLI, or direct IMDS calls
• How to decode a JWT in PowerShell and identify the claims relevant to permission diagnosis
• How to write a correct paginated Graph API call that handles @odata.nextLink
• The difference between Graph consent-based authorization and ARM RBAC authorization

Requesting authentication and tokens

Managed identity authentication from Azure automation resources

Managed identities are the preferred authentication method for Azure-hosted automation. The credential is platform-managed and never stored in code. The authentication flow is the same whether you are using an Automation Account, Function App, or Azure VM.

Key PowerShell cmdlets:

# Authenticate Az PowerShell using the managed identity of the current resource
Connect-AzAccount -Identity

# Authenticate the Microsoft Graph PowerShell SDK using managed identity
Connect-MgGraph -Identity

# Azure CLI equivalent
az login --identity

All three of these ultimately call the same underlying mechanism: the Azure Instance Metadata Service (IMDS).

The IMDS endpoint

IMDS is a local HTTP endpoint available only from within Azure:

http://169.254.169.254/metadata/identity/oauth2/token

It returns a bearer token for the requested resource without any stored credential. Because it is a link-local address, it is not reachable from outside the Azure infrastructure.

A direct IMDS call looks like this:

$response = Invoke-RestMethod `
  -Method Get `
  -NoProxy `
  -Uri "http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https://graph.microsoft.com/" `
  -Headers @{ Metadata = "true" }

$token = $response.access_token

Requesting tokens for any Azure service

Managed identity tokens are scoped to a specific resource (audience). You can request tokens for any Azure service:

Service	Resource URI
Microsoft Graph	https://graph.microsoft.com/
Azure Resource Manager	https://management.azure.com/
Azure Key Vault	https://vault.azure.net/
Log Analytics	https://api.loganalytics.io/

Using Az PowerShell:

# Get a token for Microsoft Graph
$graphToken = Get-AzAccessToken -ResourceUrl "https://graph.microsoft.com/"

# Get a token for Azure Resource Manager
$armToken = Get-AzAccessToken -ResourceUrl "https://management.azure.com/"

Using Azure CLI:

az account get-access-token --resource "https://graph.microsoft.com/"

Decoding a JWT access token

You can decode a JWT in PowerShell to inspect its claims. This is useful for diagnosing permission errors.

$tokenParts = $token.Split(".")
$payload = $tokenParts[1].Replace("-", "+").Replace("_", "/")
switch ($payload.Length % 4) {
  2 { $payload += "==" }
  3 { $payload += "=" }
}

$claims = [Text.Encoding]::UTF8.GetString(
  [Convert]::FromBase64String($payload)
) | ConvertFrom-Json

$claims | Select-Object aud, oid, scp, roles, exp

Claims to look for when diagnosing a 403 error:

• aud: should match the target API (https://graph.microsoft.com/ for Graph calls)
• roles: should list the application permissions granted to the managed identity
• scp: should be absent for managed identity (app-only) calls
• exp: should be in the future (Unix timestamp); managed identity token lifetimes can vary, so do not assume a fixed one-hour expiry

If a runbook returns 403 Forbidden when calling Graph, the most common cause is that roles is empty or does not include the required permission. The managed identity needs the Graph application permission granted via admin consent.

MSAL and the Microsoft Authentication Library

MSAL is the recommended authentication library for custom code. It handles:

• token caching: reuses existing valid tokens instead of requesting new ones on every call
• silent refresh: obtains a new token automatically before the current one expires
• the full OAuth flow: authorization code, client credentials, device code, and others

The Microsoft Graph PowerShell SDK and Az PowerShell both use MSAL internally. For Python, .NET, or Node.js automation, MSAL abstracts away token acquisition complexity. Retry behavior for throttling depends on the SDK or client pipeline, so raw REST automation still needs to honor Retry-After itself.

Microsoft Graph API

Versioned endpoints

Microsoft Graph has two endpoint tracks:

• /v1.0: stable, production-ready features. Prefer this as the starting point for all automation.
• /beta: contains features not yet available in /v1.0, but Microsoft states the beta version is not supported for production use. See the beta version support policy.
• If you must depend on /beta, document the dependency, test it carefully, and monitor the Graph changelog for announced changes.
• Mixing /v1.0 and /beta in a single runbook can cause object type mismatches. If a key feature is only in /beta, consider using /beta for all calls in that runbook to ensure type consistency.

A production Graph call looks like:

GET https://graph.microsoft.com/v1.0/users

OData query parameters

Graph API uses OData query parameters to filter, shape, and sort responses:

Parameter	Purpose	Example
$select	Return only specified fields	$select=displayName,userPrincipalName
$filter	Filter results	$filter=accountEnabled eq false
$top	Limit page size	$top=100
$orderby	Sort results	$orderby=displayName
$expand	Expand related entities	$expand=manager
$count	Return total count	$count=true

Use $select whenever possible to reduce response payload size and API call latency.

Graph Explorer

Graph Explorer is the interactive tool for testing Graph API calls with real tenant data before writing code:

https://developer.microsoft.com/en-us/graph/graph-explorer

Use it to:

• test a query before building automation around it
• understand what a response looks like before writing code to parse it
• verify which permissions a call requires
• experiment with $filter, $select, and $expand syntax

Pagination with @odata.nextLink

Graph API returns paginated results for large collections. When more results exist beyond the current page, the response includes an @odata.nextLink property containing the URL for the next page.

$uri = "https://graph.microsoft.com/v1.0/users?`$top=5"
$headers = @{ Authorization = "Bearer $token" }
$allUsers = @()

do {
    $response = Invoke-RestMethod -Uri $uri -Headers $headers
    $allUsers += $response.value
    $uri = $response.'@odata.nextLink'
} while ($uri)

Write-Output "Total users retrieved: $($allUsers.Count)"

Without pagination handling, a runbook silently returns only the first page. This is a common bug in Graph automation that produces incomplete compliance reports or inaccurate user inventories.

Throttling

Graph API enforces per-app, per-tenant rate limits. When you exceed the limit, you receive an HTTP 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait.

Correct handling:

$uri = "https://graph.microsoft.com/v1.0/users"
$headers = @{ Authorization = "Bearer $token" }

do {
    try {
        $response = Invoke-RestMethod -Uri $uri -Headers $headers
        break
    } catch {
        if ($_.Exception.Response.StatusCode -eq 429) {
            $retryAfter = $_.Exception.Response.Headers["Retry-After"]
            Start-Sleep -Seconds ([int]$retryAfter + 1)
        } else {
            throw
        }
    }
} while ($true)

For bulk data extraction such as full sign-in logs, prefer Microsoft Graph Data Connect over repeated REST calls. Graph Data Connect is a bulk extraction alternative designed for large-scale analytics pipelines.

Azure Resource Manager

Azure Resource Manager (ARM) is the management and deployment layer for Azure resources. Azure portal, Azure CLI, Az PowerShell, Bicep, and ARM templates all rely on it for control-plane operations against https://management.azure.com/.

The key difference from Microsoft Graph:

• Microsoft Graph uses consent-based OAuth scopes to authorize access
• ARM uses subscription-scoped Azure RBAC role assignments to authorize access
• there is no consent grant to issue for ARM access; you need an RBAC role assignment on the scope you want to manage

A direct ARM REST call:

$armToken = Get-AzAccessToken -ResourceUrl "https://management.azure.com/"
$armBearerToken = if ($armToken.Token -is [securestring]) {
  [System.Net.NetworkCredential]::new('', $armToken.Token).Password
} else {
  $armToken.Token
}
$subscriptionId = "<subscription-id>"

$response = Invoke-RestMethod `
  -Uri "https://management.azure.com/subscriptions/$subscriptionId/resourceGroups?api-version=2021-04-01" `
  -Headers @{ Authorization = "Bearer $armBearerToken" }

$response.value | Select-Object name, location

Understanding ARM as the underlying layer explains why tokens scoped to https://management.azure.com/ are needed for infrastructure automation and why Azure RBAC governs that access rather than consent.

Internal and undocumented APIs

Many Microsoft first-party services such as Teams, SharePoint, and the Outlook web application use internal REST APIs that are not documented on Microsoft Learn. These are discoverable through browser developer tools network inspection.

These APIs:

• are unsupported
• can change without notice
• have no documented authentication requirements
• should never be relied upon in production automation

The correct approach is to wait for Microsoft Graph coverage of the functionality you need, or use supported libraries such as PnP PowerShell for SharePoint and Teams scenarios. Internal APIs are useful for prototyping and reverse engineering your own tenant's behavior, but they are not a stable foundation for operational automation.

Lab readiness notes

Guided lab

Lab goal

Connect to Microsoft Graph from an Automation Account runbook using managed identity, verify the app-only permission in the token, compare Graph PowerShell to raw REST, and implement pagination and $select correctly.

Lab prerequisites

• Automation Account with system-assigned managed identity enabled
• The Automation Account has Az.Accounts and Microsoft.Graph.Authentication imported
• An admin terminal that can grant User.Read.All application permission to the Automation Account identity

Step 0: Grant the managed identity the Graph permission the lab expects

Use the Automation Account principal ID as the target for the app role assignment. The later runbook steps assume the managed identity already has User.Read.All.

Azure Portal:

Confirm the managed identity principal ID

1. Open the Automation Account.
2. Go to Identity and confirm System assigned is On.
3. Copy the Object (principal) ID so you can verify the same service principal in Entra after the grant.

Native PowerShell:

Grant User.Read.All through Microsoft Graph

$resourceGroupName = "<resource-group>"
$automationAccountName = "<automation-account>"

$managedIdentitySpObjectId = az automation account show `
  --automation-account-name $automationAccountName `
  --resource-group $resourceGroupName `
  --query identity.principalId `
  -o tsv

$adminAccessToken = az account get-access-token `
  --resource-type ms-graph `
  --query accessToken `
  -o tsv

$graphSp = Invoke-RestMethod `
  -Method Get `
  -Uri "https://graph.microsoft.com/v1.0/servicePrincipals?`$filter=appId eq '00000003-0000-0000-c000-000000000000'&`$select=id,appRoles" `
  -Headers @{ Authorization = "Bearer $adminAccessToken" }

$graphSpId = $graphSp.value[0].id
$userReadAllRoleId = ($graphSp.value[0].appRoles | Where-Object {
  $_.value -eq "User.Read.All" -and $_.allowedMemberTypes -contains "Application"
} | Select-Object -First 1).id

$existingAssignments = Invoke-RestMethod `
  -Method Get `
  -Uri "https://graph.microsoft.com/v1.0/servicePrincipals/$managedIdentitySpObjectId/appRoleAssignments" `
  -Headers @{ Authorization = "Bearer $adminAccessToken" }

if (-not ($existingAssignments.value | Where-Object {
  $_.resourceId -eq $graphSpId -and $_.appRoleId -eq $userReadAllRoleId
})) {
  Invoke-RestMethod `
    -Method Post `
    -Uri "https://graph.microsoft.com/v1.0/servicePrincipals/$managedIdentitySpObjectId/appRoleAssignments" `
    -Headers @{ Authorization = "Bearer $adminAccessToken"; "Content-Type" = "application/json" } `
    -Body (@{
        principalId = $managedIdentitySpObjectId
        resourceId  = $graphSpId
        appRoleId   = $userReadAllRoleId
    } | ConvertTo-Json)
}

Graph PowerShell:

Grant the same app role with Invoke-MgGraphRequest

Connect-MgGraph -Scopes "AppRoleAssignment.ReadWrite.All","Application.Read.All"

$resourceGroupName = "<resource-group>"
$automationAccountName = "<automation-account>"
$managedIdentitySpObjectId = az automation account show `
  --automation-account-name $automationAccountName `
  --resource-group $resourceGroupName `
  --query identity.principalId `
  -o tsv

$graphSp = Invoke-MgGraphRequest `
  -Method GET `
  -Uri "https://graph.microsoft.com/v1.0/servicePrincipals?`$filter=appId eq '00000003-0000-0000-c000-000000000000'&`$select=id,appRoles"

$graphSpId = $graphSp.value[0].id
$userReadAllRoleId = ($graphSp.value[0].appRoles | Where-Object {
  $_.value -eq "User.Read.All" -and $_.allowedMemberTypes -contains "Application"
} | Select-Object -First 1).id

$existingAssignments = Invoke-MgGraphRequest `
  -Method GET `
  -Uri "https://graph.microsoft.com/v1.0/servicePrincipals/$managedIdentitySpObjectId/appRoleAssignments"

if (-not ($existingAssignments.value | Where-Object {
  $_.resourceId -eq $graphSpId -and $_.appRoleId -eq $userReadAllRoleId
})) {
  Invoke-MgGraphRequest `
    -Method POST `
    -Uri "https://graph.microsoft.com/v1.0/servicePrincipals/$managedIdentitySpObjectId/appRoleAssignments" `
    -Body @{
      principalId = $managedIdentitySpObjectId
      resourceId  = $graphSpId
      appRoleId   = $userReadAllRoleId
    }
}

Az CLI:

Use a file-backed JSON body to avoid PowerShell quoting issues

$resourceGroupName = "<resource-group>"
$automationAccountName = "<automation-account>"

$managedIdentitySpObjectId = az automation account show `
  --automation-account-name $automationAccountName `
  --resource-group $resourceGroupName `
  --query identity.principalId `
  -o tsv

$graphSpId = az ad sp list `
  --filter "appId eq '00000003-0000-0000-c000-000000000000'" `
  --query "[0].id" `
  -o tsv

$userReadAllRoleId = az rest `
  --method get `
  --uri "https://graph.microsoft.com/v1.0/servicePrincipals/$graphSpId/appRoles?`$select=id,value,allowedMemberTypes" `
  --query "value[?value=='User.Read.All' && contains(allowedMemberTypes, 'Application')].id | [0]" `
  --output tsv

$assignmentBodyPath = Join-Path $env:TEMP "section3-user-read-all.json"
(@{
    principalId = $managedIdentitySpObjectId
    resourceId  = $graphSpId
    appRoleId   = $userReadAllRoleId
} | ConvertTo-Json -Compress) | Set-Content -Path $assignmentBodyPath -Encoding ascii

$existingAssignment = az rest `
  --method get `
  --uri "https://graph.microsoft.com/v1.0/servicePrincipals/$managedIdentitySpObjectId/appRoleAssignments" `
  --query "value[?resourceId=='$graphSpId' && appRoleId=='$userReadAllRoleId'] | [0]" `
  --output json

if ($existingAssignment -eq "null") {
  az rest `
    --method post `
    --uri "https://graph.microsoft.com/v1.0/servicePrincipals/$managedIdentitySpObjectId/appRoleAssignments" `
    --headers "Content-Type=application/json" `
    --body "@$assignmentBodyPath"
}

Step 1: Connect using managed identity and call Graph through Graph PowerShell

Keep this and the later steps in the same PowerShell 7.4 runbook so you can reuse the token and headers as you progress.

Azure Automation runbook:

Connect with managed identity and query Graph

Disable-AzContextAutosave -Scope Process | Out-Null
Connect-AzAccount -Identity | Out-Null
Connect-MgGraph -Identity -NoWelcome | Out-Null

$users = Invoke-MgGraphRequest `
  -Method GET `
  -Uri "https://graph.microsoft.com/v1.0/users?`$top=5&`$select=id,displayName,userPrincipalName"

$users.value | Select-Object displayName, userPrincipalName | Format-Table

Expected outcome: a short table of users from the tenant. If you receive a 403, return to Step 0 and inspect the managed identity's roles claim in Step 3.

Step 2: Acquire a raw token and call Graph via REST

Azure Automation runbook:

Get the Graph token explicitly and call /users

$tokenObject = Get-AzAccessToken -ResourceTypeName MSGraph
$token = if ($tokenObject.Token -is [securestring]) {
  [System.Net.NetworkCredential]::new('', $tokenObject.Token).Password
} else {
  $tokenObject.Token
}

$headers = @{ Authorization = "Bearer $token" }
$response = Invoke-RestMethod `
  -Method Get `
  -Uri "https://graph.microsoft.com/v1.0/users?`$top=5&`$select=id,displayName,userPrincipalName" `
  -Headers $headers

$response.value | Select-Object displayName, userPrincipalName

Expected outcome: the same data appears again, but now you can see the raw response shape and the bearer token boundary directly.

Step 3: Decode the JWT and inspect claims

Azure Automation runbook:

Confirm roles versus scp

$tokenParts = $token.Split(".")
$payload = $tokenParts[1].Replace("-", "+").Replace("_", "/")

switch ($payload.Length % 4) {
  2 { $payload += "==" }
  3 { $payload += "=" }
}

$claims = [Text.Encoding]::UTF8.GetString(
  [Convert]::FromBase64String($payload)
) | ConvertFrom-Json

$claims | Select-Object aud, oid, roles, scp, exp | Format-List

Expected observations:

• aud is https://graph.microsoft.com
• roles contains User.Read.All
• scp is absent or empty because this is app-only access
• oid matches the Automation Account service principal object ID

Paste the token into https://jwt.ms if you want to verify the same claims visually in the browser.

Step 4: Implement paginated Graph calls

Azure Automation runbook:

Follow @odata.nextLink until the collection is complete

$uri = "https://graph.microsoft.com/v1.0/users?`$top=2&`$select=displayName,userPrincipalName"
$allUsers = @()

do {
  $page = Invoke-RestMethod -Method Get -Uri $uri -Headers $headers
  $allUsers += $page.value
  $uri = $page.'@odata.nextLink'
  Write-Output "Retrieved $($allUsers.Count) users so far..."
} while ($uri)

Write-Output "Total users retrieved: $($allUsers.Count)"

Expected outcome: multiple loop iterations when $top=2 is low enough to force pagination.

Step 5: Add field selection to reduce response size

Azure Automation runbook:

Request only the fields the runbook actually needs

$response = Invoke-RestMethod `
  -Method Get `
  -Uri "https://graph.microsoft.com/v1.0/users?`$select=displayName,userPrincipalName,accountEnabled" `
  -Headers $headers

$response.value | Where-Object { -not $_.accountEnabled } | Select-Object displayName, userPrincipalName

Expected outcome: the response payload is smaller and the runbook only processes the properties it asked for.

Admin takeaways

Quick recap questions

1. Which HTTP endpoint does Connect-AzAccount -Identity call internally to obtain a token?
2. What claim in a JWT tells you an application permission is present? What claim tells you a delegated scope is present?
3. What does a Graph API 429 response mean, and what should your code do when it receives one?
4. If a runbook returns a 403 when calling GET /v1.0/users, which token claim would you inspect first to diagnose the issue?
5. Why should you never rely on an internal, undocumented Microsoft API in production automation?

Key reminders

• IMDS is only reachable from within Azure - it is the secure boundary for managed identity tokens
• Azure IMDS calls require Metadata: true and should bypass proxies with -NoProxy
• roles in the token = application permission; scp = delegated scope; one should be absent depending on the auth model
• Always handle @odata.nextLink in Graph calls or risk silently incomplete results
• ARM uses RBAC, not consent; Graph uses consent, not RBAC
• Never use beta Graph endpoints in production runbooks
• Internal undocumented APIs have no stability guarantee and should never power operational automation

References Appendix

All links below were reviewed on 2026-03-10.

Managed identity and IMDS

• What are managed identities for Azure resources?
• How to use managed identities for Azure resources on an Azure VM to acquire an access token
• Azure Instance Metadata Service - Identity endpoint
• Developer introduction and guidelines for managed identities for Azure resources
• Services that support managed identities for Azure resources
• Connect-AzAccount (Az.Accounts)
• Get-AzAccessToken (Az.Accounts)

MSAL and token handling

• Microsoft Authentication Library (MSAL) overview
• Token cache serialization in MSAL
• Access tokens in the Microsoft identity platform
• Refresh tokens in the Microsoft identity platform

Microsoft Graph API

• Microsoft Graph overview
• Microsoft Graph beta version support policy
• Use query parameters to customize responses
• Paging Microsoft Graph data in your app
• Throttling and limits in Microsoft Graph
• Graph Explorer
• Microsoft Graph Data Connect overview
• Connect-MgGraph (Microsoft Graph PowerShell)

Azure Resource Manager

• Azure Resource Manager overview
• Azure REST API reference - Azure Resource Manager
• Azure built-in roles
• What is Azure role-based access control (Azure RBAC)?

JWT inspection and security

• jwt.ms - JWT decoder
• JSON Web Token (JWT) - RFC 7519
• Server-Side Request Forgery (SSRF) via cloud metadata endpoints (OWASP)

Community and MVP references

• Joosua Santasalo: SSRF and the Azure IMDS endpoint in cloud pentests
• Niall Brady: Using Get-AzAccessToken for manual Graph REST calls from PowerShell