OAuth Integration

MCP-Cloud supports OAuth 2.0 authentication for seamless and secure user sign-in through popular identity providers. This document explains how to configure and use OAuth authentication with MCP-Cloud.

Supported OAuth Providers

MCP-Cloud currently supports the following OAuth providers:

Provider	Identity Type	Implementation
Google	Personal & Workspace accounts	OpenID Connect
GitHub	Developer accounts	OAuth 2.0
Microsoft	Personal & Azure AD accounts	OpenID Connect
Apple	Apple ID	OpenID Connect

OAuth Authentication Flow

MCP-Cloud implements the standard OAuth 2.0 authorization code flow:

┌──────────┐                 ┌────────────┐               ┌───────────────┐
│          │                 │            │               │               │
│  Client  │──────────1─────▶│  MCP-Cloud │─────2────────▶│ OAuth Provider│
│ (Browser)│                 │            │               │               │
│          │                 │            │               │               │
│          │◀─────────3──────│            │◀────4─────────│               │
│          │                 │            │               │               │
│          │──────────5─────▶│            │─────6────────▶│               │
│          │                 │            │               │               │
│          │◀─────────7──────│            │◀────8─────────│               │
└──────────┘                 └────────────┘               └───────────────┘

1. User clicks "Sign in with [Provider]"
2. MCP-Cloud redirects to OAuth provider with client ID and scopes
3. User completes authentication with the provider
4. Provider redirects back to MCP-Cloud with authorization code
5. Client sends code to MCP-Cloud backend
6. MCP-Cloud backend exchanges code for access/ID tokens
7. MCP-Cloud creates a user session and sends it to the client
8. Optional: MCP-Cloud retrieves additional user info from provider

Configuring OAuth in Your Application

To enable OAuth authentication in your MCP-Cloud integration:

Prerequisites

• An MCP-Cloud account with administrator privileges
• Developer accounts with the OAuth providers you want to support
• Registered OAuth applications with each provider

Configuration Steps

1. Register OAuth Applications with Providers

   For each provider, register your application in their developer console:

   • Google: Google Cloud Console
   • GitHub: GitHub Developer Settings
   • Microsoft: Azure Portal
   • Apple: Apple Developer Portal

   When registering, set the following redirect URIs:

   https://your-mcp-cloud-domain.com/api/auth/callback/google
   https://your-mcp-cloud-domain.com/api/auth/callback/github
   https://your-mcp-cloud-domain.com/api/auth/callback/microsoft
   https://your-mcp-cloud-domain.com/api/auth/callback/apple
   

2. Configure OAuth Providers in MCP-Cloud

   In your MCP-Cloud dashboard:

   • Navigate to Settings → Authentication → OAuth Providers
   • For each provider, enter:
     • Client ID
     • Client Secret
     • Additional provider-specific settings

   Example configuration for Google OAuth:

   {
     "provider": "google",
     "clientId": "your-google-client-id.apps.googleusercontent.com",
     "clientSecret": "your-google-client-secret",
     "scopes": ["profile", "email"],
     "allowedDomains": ["yourcompany.com"] // Optional: restrict to specific domains
   }
   

Implementing OAuth in Your Client Application

Adding OAuth Sign-In Buttons

Include OAuth sign-in buttons in your application:

// React example
import { useAuth } from '@/context/auth-context';

function OAuthSignIn() {
  const { signInWithOAuth } = useAuth();

  return (
    <div className="oauth-providers">
      <button 
        onClick={() => signInWithOAuth('google')}
        className="oauth-button google"
      >
        Sign in with Google
      </button>

      <button 
        onClick={() => signInWithOAuth('github')}
        className="oauth-button github"
      >
        Sign in with GitHub
      </button>
      
      {/* Additional provider buttons */}
    </div>
  );
}

Handling OAuth Callbacks

The MCP-Cloud client SDK handles the OAuth callback process automatically. In most cases, you don't need to implement custom callback handling.

For custom implementations, the callback flow works as follows:

1. OAuth provider redirects to your application with a code
2. Your application exchanges this code for tokens
3. You validate the tokens and create a user session

// Example of handling a callback manually
async function handleOAuthCallback(provider, code) {
  try {
    // Exchange code for tokens
    const response = await fetch('/api/auth/token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ provider, code })
    });
    
    const { accessToken, idToken } = await response.json();
    
    // Use the tokens to authenticate with MCP-Cloud
    await authenticateWithMCPCloud(idToken);
  } catch (error) {
    console.error('OAuth callback error:', error);
  }
}

Advanced OAuth Configuration

Domain Restrictions

You can restrict Google sign-ins to specific domains:

{
  "provider": "google",
  "clientId": "your-google-client-id",
  "clientSecret": "your-google-client-secret",
  "allowedDomains": ["yourcompany.com", "partner.com"]
}

This prevents users from non-authorized domains from signing in.

Custom Scopes

Request additional provider scopes to access more user data:

{
  "provider": "github",
  "clientId": "your-github-client-id",
  "clientSecret": "your-github-client-secret",
  "scopes": ["user:email", "read:user", "read:org"]
}

Available scopes vary by provider:

• Google: profile, email, openid, etc.
• GitHub: user:email, read:user, read:org, etc.
• Microsoft: user.read, user.readbasic.all, etc.

Enforcing Multi-Factor Authentication

For GitHub, you can require users to have 2FA enabled:

{
  "provider": "github",
  "clientId": "your-github-client-id",
  "clientSecret": "your-github-client-secret",
  "requireMFA": true
}

Customizing Provider Display

Customize how providers appear in your UI:

{
  "provider": "google",
  "clientId": "your-google-client-id",
  "clientSecret": "your-google-client-secret",
  "displayName": "Google Workspace",
  "iconUrl": "https://your-custom-icon-url.com/google-icon.svg"
}

User Account Linking

Users can link multiple OAuth providers to a single MCP-Cloud account:

1. User signs in with their primary authentication method
2. In user settings, they select "Link Account" for additional providers
3. They complete the OAuth flow for the new provider
4. The accounts are now linked and either can be used for sign-in

To implement account linking:

// React example for account linking
function LinkAccount({ provider }) {
  const { linkOAuthProvider } = useAuth();
  
  return (
    <button onClick={() => linkOAuthProvider(provider)}>
      Link {provider} Account
    </button>
  );
}

Enterprise SSO Integration

For enterprise customers, MCP-Cloud supports SAML 2.0 and advanced OAuth configurations:

Azure AD Integration

Configure MCP-Cloud as an enterprise application in Azure AD:

1. Register MCP-Cloud in Azure AD
2. Configure the following settings:
   • Identifier (Entity ID): https://your-mcp-cloud-domain.com/api/auth/saml/metadata
   • Reply URL: https://your-mcp-cloud-domain.com/api/auth/saml/callback
   • Sign-on URL: https://your-mcp-cloud-domain.com/login
3. Configure claims mapping to include:
   • Email address
   • User ID
   • Display name
   • Group memberships (optional)

SAML Configuration

For SAML-based SSO, configure your Identity Provider:

{
  "provider": "saml",
  "entityId": "https://your-idp-entity-id",
  "ssoUrl": "https://your-idp-sso-url",
  "x509Cert": "YOUR-IDP-CERTIFICATE",
  "attributeMapping": {
    "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
    "firstName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
    "lastName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
    "groups": "http://schemas.xmlsoap.org/claims/Group"
  }
}

Troubleshooting OAuth Issues

Issue	Possible Cause	Solution
"Redirect URI mismatch"	Incorrect redirect URI in provider config	Verify redirect URIs match exactly between MCP-Cloud and provider
"Invalid client ID"	Client ID is incorrect	Double-check client ID in MCP-Cloud settings
"Access denied"	User denied permission or lacks required privileges	Check required scopes and user permissions
"Email already in use"	Account with same email exists from different provider	Use account linking or contact support
"Domain not allowed"	User's email domain not in allowedDomains	Add domain to allowed list or remove restriction
OAuth popup blocked	Browser blocking popup windows	Disable popup blocker or use redirect flow

Security Considerations

When implementing OAuth with MCP-Cloud:

1. Never store client secrets in frontend code
2. Validate tokens on your backend before trusting them
3. Use state parameters to prevent CSRF attacks
4. Implement PKCE for public clients
5. Limit requested scopes to minimum required
6. Set short-lived tokens and use refresh tokens securely
7. Configure allowlisted redirect URIs to prevent open redirects

API Reference

OAuth Endpoints

Endpoint	Description
GET /api/auth/providers	List available OAuth providers
GET /api/auth/oauth/:provider	Initiate OAuth flow with provider
GET /api/auth/callback/:provider	OAuth provider callback endpoint
POST /api/auth/link/:provider	Link provider to existing account
POST /api/auth/unlink/:provider	Unlink provider from account

Session Management

After successful OAuth authentication, MCP-Cloud creates a session cookie. For client-side detection of successful authentication:

// Check if user is authenticated after OAuth redirect
function checkAuthStatus() {
  // The auth context provider automatically checks for authentication status
  const { user, loading } = useAuth();
  
  useEffect(() => {
    if (user && !loading) {
      // User is authenticated after OAuth flow
      navigate('/dashboard');
    }
  }, [user, loading]);
}