Microsoft Graph API Certificate Based Authentication

The Microsoft Graph API provides administrators with extensive management capabilities and scripting options for M365 services. To authenticate, we use an application with application permissions, allowing scripts to run automatically without requiring a user login. Authentication can be done via a password or a JWT token using certificate-based authentication—the latter being the more secure but unfortunately poorly documented option (at least in my experience). I’ve spent hours searching for a clear guide on how to implement it properly.

I’ll assume you’re already familiar with registering an application in Entra ID (formerly Azure AD). If not, there are plenty of tutorials available. For testing purposes, I recommend granting the User.Read.All application permission.

Next, you’ll need to add a certificate to your application—again, many tutorials cover this. Now comes the fun part: actually implementing certificate-based authentication and getting it to work efficiently.

Understanding JWTs in Authentication

A JWT (JSON Web Token) consists of three parts, separated by dots (.):

JSON

Base64(HEADER).Base64(PAYLOAD).SIGNATURE

Each part serves a specific purpose:

Header – Contains metadata about the token, such as the algorithm used for signing.
Payload – Includes the claims (data) that define what the token is authorizing.
Signature – Ensures the token’s integrity and authenticity.

Header (Base64-encoded JSON)

JSON

{
  "alg": "PS256",
  "typ": "JWT",
  "x5t": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u"
}

alg: The signing algorithm (e.g., PS256 for RSASSA-PSS with SHA-256).
typ: Token type (JWT).
x5t: The thumbprint of the certificate used for signing.

Payload (Base64-encoded Json)

JSON

{
  "aud": "https://login.microsoftonline.com/contoso.onmicrosoft.com/oauth2/v2.0/token",
  "exp": 1484593341,
  "iss": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
  "jti": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
  "nbf": 1484592741,
  "sub": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
}

aud: The intended recipient of the token (Azure AD token endpoint).
exp: Expiry time (Unix timestamp).
iss: Issuer (the application’s client ID).
jti: Unique identifier for the token.
nbf: “Not Before” time—when the token becomes valid.
sub: The subject (user or app requesting authentication).

Signature

JSON

A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u...

The signature is generated by hashing the Header + Payload using the specified algorithm and signing key (certificate/private key). This ensures the token’s integrity and prevents tampering.

JWTs are stateless, meaning no database lookup is required for authentication, making them ideal for API authentication.

Here Microsoft provides a solid overview for the needed parameters and the values.

Authenticating to Microsoft Graph API with Certificate-Based JWT in PowerShell

Retrieve the Certificate and Private Key

First, obtain the certificate you uploaded to your Entra ID and extract the private key.

PowerShell

# Retrieve the certificate from the local store
$Certificate = Get-Item "Cert:\{SCOPE}\My\{THUMBPRINT}"

# Extract the private key
$PrivateKey = [System.Security.Cryptography.X509Certificates.RSACertificateExtensions]::GetRSAPrivateKey($Certificate)

# Alternative method (not tested, but should return the same object)
$PrivateKey = $Certificate.PrivateKey

{Scope}: Can be LocalMachine or CurrentUser

Generate Base64 Certificate Hash & JWT Timestamps

Now, convert the certificate hash to a Base64 URL-encoded string and create timestamps for:

Expiration (exp): When the token becomes invalid
NotBefore (nbf): The earliest time the token can be used

PowerShell

# Convert the certificate hash to a Base64 string
$CertificateBase64Hash = [System.Convert]::ToBase64String($Certificate.GetCertHash())

# Define the Unix epoch start time
$StartDate = (Get-Date "1970-01-01T00:00:00Z").ToUniversalTime()

# Set JWT expiration time (2 minutes from now)
$JWTExpirationTimeSpan = (New-TimeSpan -Start $StartDate -End (Get-Date).ToUniversalTime().AddMinutes(2)).TotalSeconds
$JWTExpiration = [math]::Round($JWTExpirationTimeSpan, 0)

# Set JWT "not before" timestamp (immediately valid)
$NotBeforeExpirationTimeSpan = (New-TimeSpan -Start $StartDate -End (Get-Date).ToUniversalTime()).TotalSeconds
$NotBefore = [math]::Round($NotBeforeExpirationTimeSpan, 0)

Construct the JWT Header & Payload

Now, define the JWT Header and Payload.

PowerShell

$JWTHeader = @{
    alg = "RS256"
    typ = "JWT"
    x5t = $CertificateBase64Hash -replace '\+', '-' -replace '/', '_' -replace '='  # Convert to Base64 URL-safe encoding
}

$JWTPayload = @{
    aud = "https://login.microsoftonline.com/{tenantName}/oauth2/token"  # Token endpoint
    exp = $JWTExpiration  # Expiration timestamp
    iss = "{Application ID}"  # Application ID
    jti = [guid]::NewGuid()  # Unique identifier for the JWT
    nbf = $NotBefore  # NotBefore timestamp
    sub = "{Application ID}"  # Subject (same as Application ID)
}

Convert Header & Payload to Base64

Convert both the header and payload to Base64 URL-encoded format.

PowerShell

$JWTHeaderToByte = [System.Text.Encoding]::UTF8.GetBytes(($JWTHeader | ConvertTo-Json -Compress))
$EncodedHeader = [System.Convert]::ToBase64String($JWTHeaderToByte) -replace '\+', '-' -replace '/', '_' -replace '='

$JWTPayloadToByte = [System.Text.Encoding]::UTF8.GetBytes(($JWTPayload | ConvertTo-Json -Compress))
$EncodedPayload = [System.Convert]::ToBase64String($JWTPayloadToByte) -replace '\+', '-' -replace '/', '_' -replace '='

# Create an unsigned JWT
$JWT = $EncodedHeader + "." + $EncodedPayload

Sign the JWT

Now, sign the JWT using RSA-SHA256 and attach the signature.

PowerShell

# Define RSA signature algorithm
$RSAPadding = [Security.Cryptography.RSASignaturePadding]::Pkcs1
$HashAlgorithm = [Security.Cryptography.HashAlgorithmName]::SHA256

# Create a signature of the JWT
$Signature = [Convert]::ToBase64String(
    $PrivateKey.SignData([System.Text.Encoding]::UTF8.GetBytes($JWT), $HashAlgorithm, $RSAPadding)
) -replace '\+', '-' -replace '/', '_' -replace '='

# Append signature to JWT
$JWT = $JWT + "." + $Signature

Authenticate to Microsoft Graph API

Now that we have the signed JWT, we can use it for authentication.

PowerShell

$tenantId = "{Your Tenant ID}"
$tokenEndpoint = "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token"

# Construct authentication request body
$body = @{
    grant_type            = "client_credentials"
    client_id             = "{Application ID}"
    client_assertion      = $JWT
    client_assertion_type = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
    scope                = "https://graph.microsoft.com/.default"
}

# Send request to obtain access token
$Response = Invoke-WebRequest -Uri $tokenEndpoint -Body $body -Method Post -ContentType "application/x-www-form-urlencoded"

# Parse token response
$Token = ($Response.Content | ConvertFrom-Json).access_token

Cheers!

Microsoft Graph API Certificate Based Authentication