OAuth Configuration

Secure OAuth 2.0 integration with automatic token management

MCPify provides comprehensive OAuth 2.0 support with secure credential storage, automatic token refresh, and complete isolation between tenants. Configure once, and let MCPify handle the complexity of OAuth flows.

Supported OAuth 2.0 Flows

Client Credentials Flow

Machine-to-machine authentication for server applications

{
  "auth": {
    "type": "oauth2",
    "flow": "client_credentials",
    "tokenUrl": "https://api.example.com/oauth/token",
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret",
    "scopes": ["read:data", "write:data"],
    "additionalParams": {
      "audience": "https://api.example.com"
    }
  }
}

Use for: Service accounts, backend integrations, automated workflows

Authorization Code Flow

User authorization with secure code exchange

{
  "auth": {
    "type": "oauth2",
    "flow": "authorization_code",
    "authorizationUrl": "https://auth.example.com/authorize",
    "tokenUrl": "https://auth.example.com/token",
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret",
    "redirectUri": "https://gateway.mcpify.org/oauth/callback",
    "scopes": ["profile", "email", "api.access"],
    "pkce": true  // Enable PKCE for additional security
  }
}

Use for: User-specific access, delegated authorization, web applications

Refresh Token Management

Automatic token refresh with zero downtime

{
  "auth": {
    "refreshToken": {
      "enabled": true,
      "bufferTime": 300,     // Refresh 5 minutes before expiry
      "maxRetries": 3,
      "retryDelay": 1000,
      "fallbackBehavior": "queue"  // queue, fail, or use-expired
    }
  }
}

Automatic refresh before expiration
Concurrent request handling during refresh
Exponential backoff on failures

Secure Credential Management

Credential Vault Architecture

All OAuth credentials are stored in MCPify's encrypted vault with multiple layers of security:

Encryption at Rest

AES-256-GCM encryption with HSM-managed keys

Key Rotation

Automatic key rotation every 90 days

Access Control

Role-based access with audit logging

Multi-Tenant Isolation

Complete isolation between tenant credentials

Credential Operations

# Store credentials
mcpify auth set \
  --service crm \
  --client-id $CLIENT_ID \
  --client-secret $CLIENT_SECRET

# Rotate credentials
mcpify auth rotate --service crm

# List stored credentials
mcpify auth list

# Remove credentials
mcpify auth remove --service crm

Environment Variables

# Use environment variables
export MCPIFY_CRM_CLIENT_ID=xxx
export MCPIFY_CRM_CLIENT_SECRET=yyy

# Reference in config
{
  "auth": {
    "clientId": "${MCPIFY_CRM_CLIENT_ID}",
    "clientSecret": "${MCPIFY_CRM_CLIENT_SECRET}"
  }
}

Provider-Specific Configuration

Microsoft / Azure AD

{
  "auth": {
    "type": "oauth2",
    "provider": "microsoft",
    "tenantId": "your-tenant-id",
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret",
    "scopes": ["https://graph.microsoft.com/.default"],
    "tokenUrl": "https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token"
  }
}

Google

{
  "auth": {
    "type": "oauth2",
    "provider": "google",
    "clientId": "your-client-id.apps.googleusercontent.com",
    "clientSecret": "your-client-secret",
    "scopes": [
      "https://www.googleapis.com/auth/userinfo.email",
      "https://www.googleapis.com/auth/drive.readonly"
    ],
    "authorizationUrl": "https://accounts.google.com/o/oauth2/v2/auth",
    "tokenUrl": "https://oauth2.googleapis.com/token"
  }
}

Salesforce

{
  "auth": {
    "type": "oauth2",
    "provider": "salesforce",
    "clientId": "your-consumer-key",
    "clientSecret": "your-consumer-secret",
    "instanceUrl": "https://yourinstance.salesforce.com",
    "scopes": ["api", "refresh_token", "offline_access"],
    "tokenUrl": "{instanceUrl}/services/oauth2/token"
  }
}

Token Lifecycle Management

Token Acquisition

Initial token request with configured credentials and scopes

Token Storage

Encrypted storage with expiration tracking and metadata

Token Usage

Automatic injection into API requests with proper headers

Token Refresh

Proactive refresh before expiration with retry logic

Token Revocation

Clean revocation on logout or credential rotation

Security Best Practices

✅ Recommended

• Use PKCE for public clients
• Implement token rotation
• Use minimal required scopes
• Enable refresh token rotation
• Monitor token usage patterns
• Implement token binding
• Use short-lived access tokens

⚠️ Avoid

• Storing tokens in logs
• Using implicit flow
• Hardcoding credentials
• Sharing tokens between services
• Ignoring token expiration
• Disabling certificate validation
• Using long-lived tokens

Common Issues & Solutions

Invalid Grant Error

The provided authorization grant is invalid, expired, or revoked

Solution: Check refresh token validity, ensure correct redirect URI, verify client credentials, and confirm authorization code hasn't been used

Insufficient Scope

The access token doesn't have required permissions

Solution: Review required scopes, request additional permissions, check admin consent requirements, verify scope configuration

Token Expiration

Access token has expired during request

Solution: Enable automatic refresh, increase buffer time, implement retry logic, check clock synchronization