OAuth Integrations for Edge Environments

Implement GitHub and Microsoft OAuth in Cloudflare Workers and other edge runtimes.

GitHub OAuth

Required Headers

GitHub API has strict requirements that differ from other providers.

Header

Requirement

User-Agent

REQUIRED - Returns 403 without it

Accept

application/vnd.github+json recommended

const resp = await fetch('https://api.github.com/user', {

  headers: {

    Authorization: `Bearer ${accessToken}`,

    'User-Agent': 'MyApp/1.0',  // Required!

    'Accept': 'application/vnd.github+json',

  },

});

Private Email Handling

GitHub users can set email to private (/user returns email: null).

if (!userData.email) {

  const emails = await fetch('https://api.github.com/user/emails', { headers })

    .then(r => r.json());

  userData.email = emails.find(e => e.primary && e.verified)?.email;

}

Requires user:email scope.

Token Exchange

Token exchange returns form-encoded by default. Add Accept header for JSON:

const tokenResponse = await fetch('https://github.com/login/oauth/access_token', {

  method: 'POST',

  headers: {

    'Content-Type': 'application/x-www-form-urlencoded',

    'Accept': 'application/json',  // Get JSON response

  },

  body: new URLSearchParams({ code, client_id, client_secret, redirect_uri }),

});

GitHub OAuth Notes

Issue

Solution

Callback URL

Must be EXACT - no wildcards, no subdirectory matching

Token exchange returns form-encoded

Add 'Accept': 'application/json' header

Tokens don't expire

No refresh flow needed, but revoked = full re-auth

Microsoft Entra (Azure AD) OAuth

Why MSAL Doesn't Work in Workers

MSAL.js depends on:

• Browser APIs (localStorage, sessionStorage, DOM)

• Node.js crypto module

Cloudflare's V8 isolate runtime has neither. Use manual OAuth instead:

• Manual OAuth URL construction

• Direct token exchange via fetch

• JWT validation with jose library

Required Scopes

// For user identity (email, name, profile picture)

const scope = 'openid email profile User.Read';

// For refresh tokens (long-lived sessions)

const scope = 'openid email profile User.Read offline_access';

Critical: User.Read is required for Microsoft Graph /me endpoint. Without it, token exchange succeeds but user info fetch returns 403.

User Info Endpoint

// Microsoft Graph /me endpoint

const resp = await fetch('https://graph.microsoft.com/v1.0/me', {

  headers: { Authorization: `Bearer ${accessToken}` },

});

// Email may be in different fields

const email = data.mail || data.userPrincipalName;

Tenant Configuration

Tenant Value

Who Can Sign In

common

Any Microsoft account (personal + work)

organizations

Work/school accounts only

consumers

Personal Microsoft accounts only

{tenant-id}

Specific organization only

Azure Portal Setup

• App Registration → New registration

• Platform: Web (not SPA) for server-side OAuth

• Redirect URIs: Add both /callback and /admin/callback

• Certificates & secrets → New client secret

Token Lifetimes

Token Type

Default Lifetime

Notes

Access token

60-90 minutes

Configurable via token lifetime policies

Refresh token

90 days

Revoked on password change

ID token

60 minutes

Same as access token

Best Practice: Always request offline_access scope and implement refresh token flow for sessions longer than 1 hour.

Common Corrections

If Claude suggests...

Use instead...

GitHub fetch without User-Agent

Add 'User-Agent': 'AppName/1.0' (REQUIRED)

Using MSAL.js in Workers

Manual OAuth + jose for JWT validation

Microsoft scope without User.Read

Add User.Read scope

Fetching email from token claims only

Use Graph /me endpoint

Error Reference

GitHub Errors

Error

Cause

Fix

403 Forbidden

Missing User-Agent header

Add User-Agent header

email: null

User has private email

Fetch /user/emails with user:email scope

Microsoft Errors

Error

Cause

Fix

AADSTS50058

Silent auth failed

Use interactive flow

AADSTS700084

Refresh token expired

Re-authenticate user

403 on Graph /me

Missing User.Read scope

Add User.Read to scopes

Reference

• GitHub API: https://docs.github.com/en/rest

• GitHub OAuth: https://docs.github.com/en/apps/oauth-apps

• Microsoft Graph permissions: https://learn.microsoft.com/en-us/graph/permissions-reference

• AADSTS error codes: https://learn.microsoft.com/en-us/entra/identity-platform/reference-error-codes