OAuth 2.0 Authentication

Overview

OAuth 2.0 authentication enables secure, user-delegated access to MCP servers. DeepIntShield handles:

• Automatic token refresh - Tokens are refreshed before expiration
• PKCE support - For public clients without client secrets
• Dynamic registration - Automatic client registration (RFC 7591)
• OAuth discovery - Discover endpoints from server URLs
• Token management - Store and revoke OAuth tokens

This is ideal for integrations that need user-based access, require periodic re-authorization, or must comply with OAuth 2.0 standards.

What you do to connect with OAuth

DeepIntShield uses the standard Authorization Code flow. You configure and authorize an OAuth-protected MCP server entirely from the Web UI:

1. Create the client with Auth Type set to OAuth 2.0 and your OAuth settings.
2. Click Authorize - DeepIntShield opens the provider’s consent screen so the user can grant access.
3. Approve - after consent the user is redirected back, the client connects, and its tools become available.

After that, DeepIntShield keeps the token fresh on its own - see Automatic Token Refresh.

Configuration

Basic OAuth Setup

Configure OAuth authentication when creating an MCP client:

1. Navigate to MCP Gateway and click New MCP Server
2. Select HTTP or SSE as connection type
3. Set Auth Type to OAuth 2.0
4. Provide OAuth configuration:
   • Client ID: Your OAuth application’s client ID
   • Client Secret: (Optional for PKCE) Your OAuth application’s secret
   • Authorize URL: OAuth provider’s authorization endpoint
   • Token URL: OAuth provider’s token endpoint
   • Scopes: Comma-separated list of requested scopes
5. Click Authorize to start the OAuth flow
6. Complete the authorization in the browser
7. The MCP client is created with the OAuth token

Advanced OAuth Configuration

PKCE for Public Clients

For applications without a client secret, use PKCE (Proof Key for Code Exchange). When you leave Client Secret blank in the OAuth configuration, DeepIntShield automatically generates and manages PKCE code verifiers.

Dynamic Client Registration

If your OAuth server supports RFC 7591, DeepIntShield can automatically register a client for you. Instead of a Client ID, provide the Registration URL and Server URL in the OAuth configuration. DeepIntShield will:

1. Discover OAuth endpoints from the server URL
2. Register a new client using the registration URL
3. Use the registered client ID for authorization

OAuth Discovery

DeepIntShield can automatically discover OAuth endpoints from your MCP server’s metadata. Provide the Server URL and your Client ID in the OAuth configuration, and leave the authorize/token URLs blank.

If OAuth endpoints aren’t provided, DeepIntShield will check:

1. /.well-known/oauth-authorization-server (RFC 8414)
2. /.well-known/openid-configuration
3. Server MCP metadata

Token Management

View OAuth Token Status

You can check the status of an OAuth configuration from the MCP Gateway in the Web UI - open the client and review its OAuth status in the configuration panel.

Status values:

• pending: User hasn’t authorized yet
• authorized: Token is valid and active
• failed: Authorization failed or token is invalid

Automatic Token Refresh

DeepIntShield automatically refreshes OAuth tokens before expiration. No action required - tokens are refreshed transparently during tool execution.

Revoke OAuth Token

To revoke an OAuth token when you want to disconnect, open the client in the MCP Gateway and remove its OAuth authorization (or delete the client).

This:

• Revokes the token with the OAuth provider
• Deletes the token from DeepIntShield
• Removes the OAuth configuration
• The MCP client can still be used if the auth type is changed

Common OAuth Providers

For each provider, register an OAuth application at the provider, then enter the resulting values in the OAuth 2.0 auth-type fields when you create the MCP client in the MCP Gateway.

GitHub

Provider setup:

1. Go to Settings → Developer settings → OAuth Apps
2. Click “New OAuth App”
3. Fill in:
   • Application name: DeepIntShield MCP
   • Homepage URL: https://app.deepintshield.com
   • Authorization callback URL: https://app.deepintshield.com/api/oauth/callback
4. Copy the Client ID and Client Secret

DeepIntShield fields (in the New MCP Server form, with Auth Type = OAuth 2.0):

• Client ID / Client Secret: from the GitHub OAuth App above
• Authorize URL: https://github.com/login/oauth/authorize
• Token URL: https://github.com/login/oauth/access_token
• Scopes: repo, user

Google

Provider setup:

1. Go to Google Cloud Console
2. Create a new project
3. Enable OAuth 2.0 consent screen
4. Create OAuth 2.0 Client ID (Web application)
5. Add Authorized redirect URIs:
   • https://app.deepintshield.com/api/oauth/callback
6. Copy the Client ID and Client Secret

DeepIntShield fields (in the New MCP Server form, with Auth Type = OAuth 2.0):

• Client ID / Client Secret: from the Google OAuth Client above
• Authorize URL: https://accounts.google.com/o/oauth2/v2/auth
• Token URL: https://oauth2.googleapis.com/token
• Scopes: openid, email, profile

Custom OAuth Server

For your own OAuth server, enter your endpoints in the OAuth fields:

• Client ID / Client Secret: your DeepIntShield client credentials
• Authorize URL: https://auth.yourcompany.com/authorize
• Token URL: https://auth.yourcompany.com/token
• Registration URL (optional): https://auth.yourcompany.com/register
• Server URL (optional, for discovery): https://mcp.yourcompany.com
• Scopes: mcp:full

Troubleshooting

OAuth Flow Doesn’t Start

Problem: authorize_url not returned when creating MCP client

Solutions:

• Ensure auth_type is set to "oauth"
• Check that oauth_config is provided in the request
• Verify authorize_url is specified or server_url is provided for discovery

Token Refresh Fails

Problem: Tools fail with “OAuth token expired” or “OAuth token invalid”

Solutions:

• Check if the refresh token is still valid
• Revoke and re-authorize the client from the MCP Gateway, then re-run the OAuth flow
• Verify the OAuth provider hasn’t revoked the token
• Check that scopes are still sufficient

Authorization Callback Hangs

Problem: Redirect back from the provider doesn’t complete

Solutions:

• Ensure the callback URL registered at your OAuth provider matches https://app.deepintshield.com/api/oauth/callback
• Check network connectivity between DeepIntShield and the OAuth provider
• Verify the state parameter matches (for CSRF protection)
• Re-run the Authorize flow from the MCP Gateway

MCP Client Won’t Connect with OAuth

Problem: MCP client shows “error” state with OAuth configured

Solutions:

• Verify the OAuth token is still valid (check the client’s OAuth status in the MCP Gateway)
• Check that the OAuth token has required scopes
• Ensure the MCP server accepts the Authorization: Bearer {token} header
• Test HTTP connectivity to the MCP server

Best Practices

1. Use HTTPS - Always use HTTPS for OAuth flows. OAuth providers won’t accept HTTP callback URLs in production.

2. Secure Client Secrets - Store client secrets in environment variables or secure vaults, not in version control.

3. Rotate Tokens - Periodically revoke and re-authorize OAuth tokens for enhanced security.

4. Monitor Token Status - Check token status regularly, especially before critical operations.

5. Handle Refresh Failures - If token refresh fails, prompt user to re-authorize rather than silently failing.

6. Limit Scopes - Request only the scopes your MCP tools actually need.

7. Log OAuth Operations - Keep audit logs of OAuth authorizations and token usage.

Security Considerations

• Token Storage - DeepIntShield stores OAuth tokens in the database encrypted. Never log or expose tokens.
• PKCE Requirement - For public clients, PKCE is automatically enabled and verified.
• State Parameter - CSRF protection via state parameter is enforced in OAuth flows.
• Token Expiration - Tokens are automatically refreshed, reducing the window of vulnerability.
• Revocation Support - Tokens can be revoked immediately if compromised.

---

Next Steps

• Connect to MCP Servers →
• Tool Execution →
• Agent Mode →