Skip to main content

Microsoft Entra ID - AI Gateway OAuth Proxy Integration

This guide explains how to configure Microsoft Entra ID (formerly Azure Active Directory) for AI Gateway OAuth Proxy integration with Model Context Protocol (MCP) servers. This approach uses a three-tier authentication architecture with public/confidential client setup and On-Behalf-Of (OBO) token flow for secure token delegation.

When to use this approach​

Best for:

  • Desktop/CLI MCP clients requiring server-side token management
  • Enterprise scenarios requiring secure token delegation
  • Complex authentication flows with multiple token exchanges
  • Enhanced security with token proxy and delegation

Architecture: Three-tier authentication (MCP Client → AI Gateway OAuth Proxy → MCP Server → Microsoft Graph)

For simple web-based scenarios with direct user authentication, see the Direct SSO Integration guide instead.

Architecture Overview​

This setup configures a three-tier authentication architecture:

MCP Client → AI Gateway OAuth Proxy → MCP Server → Microsoft Graph

Authentication Flow:

  1. MCP Client authenticates users via AI Gateway OAuth proxy
  2. AI Gateway forwards authenticated requests to MCP Server
  3. MCP Server uses On-Behalf-Of (OBO) flow to access Microsoft Graph
  4. Microsoft Graph returns user data maintaining user context

You will create two applications:

  1. MCP Client App - Desktop/CLI application (public client)
  2. MCP Server API - Web API application (confidential client)

Prerequisites​

Before you start, confirm you have:

  • Microsoft Entra ID tenant with admin privileges
  • Access to Microsoft Entra admin center (https://entra.microsoft.com)
  • Application Administrator or Global Administrator role
  • AI Gateway callback URL: https://auth.aigateway.cequence.ai/v1/outbound/oauth/callback

Step 1: Create MCP Client App (Public Client)​

Register the Application​

  1. Navigate to Microsoft Entra admin center → Applications → App registrations
  2. Click New registration
  3. Fill in the details:
    • Name: MCP Client App
    • Supported account types: Accounts in this organizational directory only (Single tenant)
    • Redirect URI: Select Public client/native (mobile & desktop)
      • Primary: http://127.0.0.1:53100/callback
  4. Click Register

Configure Authentication Settings​

  1. In the newly created app, go to Authentication (left menu)
  2. Under Advanced settings:
    • ✅ Allow public client flows: Set to Yes
  3. Click Save

Note the Client App Details​

📝 Copy and save these values:

  • Application (client) ID: [Copy this value]
  • Directory (tenant) ID: [Copy this value]

Step 2: Create MCP Server API (Confidential Client)​

Register the Application​

  1. Go back to App registrations → New registration
  2. Fill in the details:
    • Name: MCP Server API
    • Supported account types: Accounts in this organizational directory only (Single tenant)
    • Redirect URI: Select Web
      • Enter: https://auth.aigateway.cequence.ai/v1/outbound/oauth/callback
  3. Click Register

Configure Authentication Settings​

  1. Go to Authentication (left menu)
  2. Verify Web platform shows: https://auth.aigateway.cequence.ai/v1/outbound/oauth/callback
  3. Under Advanced settings:
    • ❌ Allow public client flows: Set to No
  4. Click Save

Expose an API Scope​

  1. Go to Expose an API (left menu)

  2. Application ID URI:

    • Click Add next to "Application ID URI"
    • Accept default: api://[your-app-id] or customize: api://mcp-server
    • Click Save

  3. Add a Scope:

    • Click Add a scope
    • Scope name: access
    • Who can consent: Admins and users
    • Admin consent display name: Access MCP Server
    • Admin consent description: Allow access to MCP server functionality
    • User consent display name: Access MCP Server
    • User consent description: Allow access to MCP server on your behalf
    • State: Enabled
    • Click Add scope

Create Client Secret​

Option A: Client Secret (Easier)

  1. Go to Certificates & secrets (left menu)
  2. Click New client secret
  3. Description: MCP Server Secret
  4. Expires: 24 months (recommended)
  5. Click Add
  6. 📝 IMPORTANT: Copy the Value immediately (you won't see it again!)

Option B: Certificate (More Secure - Production Recommended)

  1. Go to Certificates & secrets (left menu)
  2. Click Upload certificate
  3. Upload your .cer certificate file
  4. 📝 Note the Thumbprint value

Note the MCP Server Details​

📝 Copy and save these values:

  • Application (client) ID: [Copy this value]
  • Application ID URI: [Your chosen URI, e.g., api://mcp-server]
  • Full Scope: [Application ID URI]/access
  • Client Secret: [The secret value you copied] OR Certificate Thumbprint

Step 3: Configure API Permissions​

Client App → MCP Server API Permission​

  1. Go to MCP Client App → API permissions (left menu)
  2. Click Add a permission
  3. Click My APIs tab
    • If you don't see your MCP Server API, try the "APIs my organization uses" tab
    • Search for your MCP Server API name or Application ID
  4. Select your MCP Server API
  5. Select Delegated permissions
  6. Check the box for access scope
  7. Click Add permissions
  8. Click Grant admin consent for [Tenant Name] (shield icon)
  9. Click Yes to confirm

MCP Server → Microsoft Graph Permissions​

  1. Go to MCP Server API → API permissions (left menu)

  2. Click Add a permission

  3. Select Microsoft Graph

  4. Select Delegated permissions

  5. Add these permissions based on your needs:

    Files.Read - Basic file access (start here) Sites.Read.All - For SharePoint team sites (if needed)

  6. Click Add permissions

  7. Click Grant admin consent for [Tenant Name] (shield icon)

  8. Click Yes to confirm

Step 4: Verification Checklist​

MCP Client App Configuration ✓​

  • App type: Public client
  • Allow public client flows: Yes
  • Redirect URI: http://127.0.0.1:53100/callback
  • API permission: [Your MCP Server scope]/access (with admin consent)

MCP Server API Configuration ✓​

  • App type: Confidential client
  • Allow public client flows: No
  • Redirect URI: https://auth.aigateway.cequence.ai/v1/outbound/oauth/callback
  • Application ID URI: Set (e.g., api://mcp-server)
  • Exposed scope: [Application ID URI]/access
  • Client secret or certificate configured
  • Microsoft Graph permissions with admin consent:
    • Files.Read (minimum)
    • Sites.Read.All (if needed)

Technical Implementation Notes​

Token Flow with AI Gateway​

1. MCP Client → AI Gateway OAuth → User authentication
2. AI Gateway → Forward to MCP Server with user context
3. MCP Server → OBO exchange (user token → Graph token)
4. MCP Server → Microsoft Graph API calls
5. MCP Server → Return data to AI Gateway → MCP Client

Microsoft Graph Permissions Escalation Path​

Start with minimal permissions and escalate as needed:

  1. Files.Read - User's OneDrive files only
  2. Files.Read.All - All files user can access
  3. Sites.Read.All - SharePoint sites and document libraries
  4. Files.ReadWrite.All - Full read/write access

Configuration Summary​

Information for Development Team​

Tenant Information:

Tenant ID: [Your Directory (tenant) ID]
Authority: https://login.microsoftonline.com/[Tenant ID]

MCP Client App:

Client ID: [MCP Client App ID]
Redirect URIs: 
  - http://127.0.0.1:53100/callback
  - http://127.0.0.1:53101/callback
  - http://127.0.0.1:8080/callback
  - (additional backup ports)
Auth Flow: Authorization Code + PKCE
Client Secret: None (public client)
Scopes: [Your MCP Server Scope]/access

MCP Server API:

Client ID: [MCP Server API App ID]
Client Secret: [Secret Value] OR Certificate Thumbprint: [Thumbprint]
Application ID URI: [Your Application ID URI]
Exposed Scope: [Application ID URI]/access
Redirect URI: https://auth.aigateway.cequence.ai/v1/outbound/oauth/callback

AI Gateway Integration:

OAuth Callback: https://auth.aigateway.cequence.ai/v1/outbound/oauth/callback
MCP Server Endpoint: https://ztaip-cn0plbi2-4xp4r634bq-uc.a.run.app

Microsoft Graph Permissions:

Granted Delegated Permissions:
- Files.Read (minimum)
- Sites.Read.All (if SharePoint access needed)
- [Additional permissions as configured]

Testing & Validation​

Test Authentication Flow​

  1. MCP Client should successfully authenticate via AI Gateway
  2. AI Gateway should forward requests to MCP Server
  3. MCP Server should exchange tokens via OBO flow
  4. Microsoft Graph calls should succeed with user context

Verify Permissions​

  • Test file access with user's actual OneDrive/SharePoint permissions
  • Confirm user can only access files they normally have permission to view
  • Validate that different users see different file sets

Monitor Sign-in Logs​

Check Microsoft Entra admin center → Sign-in logs for:

  • Successful client app authentications
  • Successful MCP Server API token exchanges
  • Any authentication errors or permission issues

Troubleshooting Common Issues​

❌ "AADSTS70011: The provided value for the input parameter 'scope' is not valid"

  • Verify the scope name exactly matches your exposed API scope
  • Check Application ID URI is correct

❌ "AADSTS65001: The user or administrator has not consented"

  • Ensure admin consent was granted for all API permissions
  • Check both client app permissions and MCP server permissions

❌ "AADSTS7000215: Invalid client secret is provided"

  • Verify client secret was copied correctly and hasn't expired
  • For certificate auth, ensure thumbprint matches uploaded certificate

❌ OBO token exchange fails

  • Verify MCP Server API has correct Microsoft Graph delegated permissions
  • Ensure "Allow public client flows" is No for the MCP Server API
  • Check that incoming user token has correct audience (your MCP Server)

❌ "MCP Server API not visible in My APIs"

  • Ensure you completed Step 2.3 (Expose an API)
  • Verify Application ID URI is set
  • Check that both apps are in the same tenant
  • Try searching in "APIs my organization uses" tab

❌ Microsoft Graph permission errors

  • Start with Files.Read and escalate permissions as needed
  • For SharePoint access, ensure Sites.Read.All is granted
  • Verify admin consent was granted for Graph permissions

Security Best Practices​

Credential Management​

  • Rotate secrets regularly before expiration
  • Use Azure Key Vault for production secret storage
  • Set up expiration alerts to avoid service disruption
  • Never commit secrets to source control

Access Control​

  • Apply least privilege principles for user assignments
  • Use groups for easier user management
  • Review access assignments regularly
  • Configure Conditional Access policies for enhanced security

Monitoring​

  • Enable sign-in logs in Azure Monitor
  • Set up alerts for suspicious activities
  • Review audit logs regularly
  • Use Identity Protection for risk detection

Configuration completed! 🎉

The MCP Server with AI Gateway OAuth proxy is now configured for secure Microsoft 365 integration with proper user context preservation throughout the authentication chain.