AZURE

📢 v1.0.0: This guide shows examples for both mark3labs/mcp-go and official modelcontextprotocol/go-sdk. See examples/README.md for complete setup guide.

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": "[e-mail]",
  "preferred_username": "[e-mail]",
  "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

• Use HTTPS for all endpoints
• Store ClientSecret in Azure Key Vault or environment
• Configure appropriate token lifetimes in Azure AD
• Enable Conditional Access policies
• Set up Azure AD monitoring and alerts
• Configure API permissions with least privilege
• Test token expiration and refresh flows
• Document tenant onboarding for multi-tenant apps

---

References

• Microsoft Identity Platform
• Register an Application
• ID Tokens
• OAuth 2.0 and OpenID Connect