Azure AD Provider Guide

Overview

Azure AD (Microsoft Entra ID) provider uses OIDC/JWKS for JWT validation. Ideal for Microsoft 365 integration and enterprise authentication.

When to Use

✅ Good for:

  • Microsoft 365 / Azure integration

  • Enterprise SSO with Azure AD

  • Applications for corporate Microsoft users

  • Multi-tenant SaaS applications

Setup in Azure Portal

1. Register Application

  1. Go to Azure Portal

  2. Navigate to Microsoft Entra ID (formerly Azure Active Directory)

  3. Select App registrations → New registration

  4. Configure:

    • Name: Your MCP Server

    • Supported account types:

      • Single tenant (your org only)

      • Multi-tenant (any Azure AD)

      • Multi-tenant + personal Microsoft accounts

    • Redirect URI: (for proxy mode)

      • Type: Web

      • URI: https://your-server.com/oauth/callback

  5. Click Register

2. Get Application (client) ID

After registration, copy:

  • Application (client) ID - This is your Client ID

  • Directory (tenant) ID - Used in issuer URL

3. Create Client Secret (Proxy Mode Only)

  1. In your app, go to Certificates & secrets

  2. Click New client secret

  3. Add description: "MCP Server OAuth"

  4. Choose expiration (recommend: 6-12 months)

  5. Click Add

  6. Copy the secret value immediately (shown only once!)

4. Configure API Permissions

  1. Go to API permissions

  2. Click Add a permission

  3. Select Microsoft Graph

  4. Choose Delegated permissions

  5. Add permissions:

    • openid (sign users in)

    • profile (user profile)

    • email (user email)

  6. Click Grant admin consent (if you're admin)

5. Configure Token Claims (Optional)

For custom audience claim:

  1. Go to Token configuration

  2. Click Add optional claim

  3. Select ID token type

  4. Add claims as needed

Configuration (Native Mode)

When: Client handles OAuth with Azure AD directly

oauth.WithOAuth(mux, &oauth.Config{
    Provider: "azure",
    Issuer:   "https://login.microsoftonline.com/{tenant-id}/v2.0",
    Audience: "api://your-app-id",  // Or Application ID
})

Replace {tenant-id} with:

  • Your Directory (tenant) ID, OR

  • common for multi-tenant apps

  • organizations for any Azure AD user

  • consumers for personal Microsoft accounts only

Configuration (Proxy Mode)

When: Server proxies OAuth flow

oauth.WithOAuth(mux, &oauth.Config{
    Provider:     "azure",
    Issuer:       "https://login.microsoftonline.com/{tenant-id}/v2.0",
    Audience:     "api://your-app-id",
    ClientID:     "12345678-1234-1234-1234-123456789012",  // Application ID
    ClientSecret: "secret~from~azure",                      // Client secret
    ServerURL:    "https://your-server.com",
    RedirectURIs: "https://your-server.com/oauth/callback",
})

Audience Options

Azure AD is flexible with audience:

Option 1: Application ID (Simplest)

Audience: "12345678-1234-1234-1234-123456789012"  // Your Application ID

Azure tokens automatically include Application ID in aud claim.

Option 2: Custom App ID URI

  1. In Azure portal, go to App registrations → Your app

  2. Navigate to Expose an API

  3. Set Application ID URI: api://your-server

  4. Click Save

Then configure:

Audience: "api://your-server"  // Matches Application ID URI

Testing

1. Environment Setup

export AZURE_TENANT_ID="your-tenant-id"
export AZURE_CLIENT_ID="your-app-id"
export AZURE_CLIENT_SECRET="your-secret"

# Build issuer URL
export AZURE_ISSUER="https://login.microsoftonline.com/${AZURE_TENANT_ID}/v2.0"

2. Start Server

oauth.WithOAuth(mux, &oauth.Config{
    Provider:     "azure",
    Issuer:       os.Getenv("AZURE_ISSUER"),
    Audience:     os.Getenv("AZURE_CLIENT_ID"),
    ClientID:     os.Getenv("AZURE_CLIENT_ID"),
    ClientSecret: os.Getenv("AZURE_CLIENT_SECRET"),
    ServerURL:    "https://your-server.com",
    RedirectURIs: "https://your-server.com/oauth/callback",
})

3. Test Authentication

# Test OAuth flow
curl https://your-server.com/.well-known/oauth-authorization-server

# Test with token
curl -X POST https://your-server.com/mcp \
  -H "Authorization: Bearer <azure-token>" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"hello","arguments":{}}}'

User Claims

Azure AD ID tokens include:

{
  "sub": "AAAAAAAAAAAAAAAAAAAAAIkzqFVrSaSaFHy782bbtaQ",
  "name": "John Doe",
  "email": "[email protected]",
  "preferred_username": "[email protected]",
  "aud": "api://your-server",
  "iss": "https://login.microsoftonline.com/{tenant}/v2.0",
  "exp": 1234567890,
  "iat": 1234567890,
  "tid": "tenant-id"
}

oauth-mcp-proxy extracts:

  • sub → User.Subject

  • email → User.Email

  • preferred_username or email → User.Username

Multi-Tenant Applications

For SaaS applications serving multiple Azure AD tenants:

oauth.WithOAuth(mux, &oauth.Config{
    Provider: "azure",
    Issuer:   "https://login.microsoftonline.com/common/v2.0",  // Note: "common"
    Audience: "api://your-server",
})

Validates tokens from any Azure AD tenant. Extract tenant from tid claim if needed.

Troubleshooting

"Failed to initialize OIDC provider"

  • Check: Issuer URL format correct (ends with /v2.0)

  • Check: Tenant ID is correct

  • Check: Network can reach login.microsoftonline.com

"Invalid audience"

  • Check: Config.Audience matches token's aud claim

  • Check: Application ID URI configured in Azure if using custom audience

"AADSTS errors" from Azure

  • AADSTS50011: Redirect URI mismatch - check Azure portal configuration

  • AADSTS700016: Application not found - check Client ID

  • AADSTS7000215: Invalid client secret - regenerate secret

Production Checklist

References

PreviousprovidersNextGoogle Provider Guide

Last updated

Was this helpful?