OAuth Configuration

OAuth enables secure authentication with third-party MCP servers without sharing credentials directly.

📊 DIAGRAM: oauth-flow.mmd

OAuth authentication flow

Overview

OAuth in Cyberstrike:

Secure token-based authentication
Browser-based authorization
Automatic token refresh
Scope-based permissions
Support for OAuth 2.0 and OIDC

OAuth 2.0 Configuration

Basic Setup

{
  "mcp": {
    "servers": {
      "oauth-service": {
        "url": "https://mcp.service.com/sse",
        "oauth": {
          "clientId": "{env:OAUTH_CLIENT_ID}",
          "authorizationUrl": "https://auth.service.com/authorize",
          "tokenUrl": "https://auth.service.com/token"
        }
      }
    }
  }
}

With Scopes

{
  "mcp": {
    "servers": {
      "github-mcp": {
        "url": "https://mcp.github.com/sse",
        "oauth": {
          "clientId": "{env:GH_CLIENT_ID}",
          "authorizationUrl": "https://github.com/login/oauth/authorize",
          "tokenUrl": "https://github.com/login/oauth/access_token",
          "scope": "repo read:user read:org"
        }
      }
    }
  }
}

With Client Secret

{
  "mcp": {
    "servers": {
      "private-service": {
        "url": "https://mcp.private.com/sse",
        "oauth": {
          "clientId": "{env:OAUTH_CLIENT_ID}",
          "clientSecret": "{env:OAUTH_CLIENT_SECRET}",
          "authorizationUrl": "https://auth.private.com/authorize",
          "tokenUrl": "https://auth.private.com/token"
        }
      }
    }
  }
}

Authorization Flow

When connecting to an OAuth-protected server:

Cyberstrike opens browser to authorization URL
User logs in and grants permissions
Browser redirects with authorization code
Cyberstrike exchanges code for tokens
Tokens are stored securely

Command Line Trigger

cyberstrike mcp auth github-mcp

In-Session

> Connect to the GitHub MCP server

Cyberstrike will prompt for authorization if needed.

Token Management

Token Storage

Tokens are stored in:

~/.cyberstrike/auth/
  mcp-github-tokens.json
  mcp-private-tokens.json

Token Refresh

Automatic refresh when:

Access token expires
Refresh token is available
Server returns 401

Manual Refresh

cyberstrike mcp refresh github-mcp

Token Revocation

cyberstrike mcp logout github-mcp

PKCE Support

For public clients (recommended):

{
  "mcp": {
    "servers": {
      "pkce-service": {
        "url": "https://mcp.service.com/sse",
        "oauth": {
          "clientId": "{env:CLIENT_ID}",
          "authorizationUrl": "https://auth.service.com/authorize",
          "tokenUrl": "https://auth.service.com/token",
          "pkce": true
        }
      }
    }
  }
}

PKCE (Proof Key for Code Exchange) adds security for public clients.

Device Authorization

For headless environments:

{
  "mcp": {
    "servers": {
      "device-service": {
        "url": "https://mcp.service.com/sse",
        "oauth": {
          "clientId": "{env:CLIENT_ID}",
          "deviceAuthorizationUrl": "https://auth.service.com/device",
          "tokenUrl": "https://auth.service.com/token",
          "grantType": "device_code"
        }
      }
    }
  }
}

Device Flow

Cyberstrike requests device code
User visits URL and enters code
Cyberstrike polls for token
Connection established

Common Providers

GitHub

{
  "mcp": {
    "servers": {
      "github": {
        "url": "https://mcp.github.com/sse",
        "oauth": {
          "clientId": "{env:GH_CLIENT_ID}",
          "authorizationUrl": "https://github.com/login/oauth/authorize",
          "tokenUrl": "https://github.com/login/oauth/access_token",
          "scope": "repo read:user"
        }
      }
    }
  }
}

Google

{
  "mcp": {
    "servers": {
      "google": {
        "url": "https://mcp.google.com/sse",
        "oauth": {
          "clientId": "{env:GOOGLE_CLIENT_ID}",
          "clientSecret": "{env:GOOGLE_CLIENT_SECRET}",
          "authorizationUrl": "https://accounts.google.com/o/oauth2/v2/auth",
          "tokenUrl": "https://oauth2.googleapis.com/token",
          "scope": "openid profile email"
        }
      }
    }
  }
}

Microsoft/Azure

{
  "mcp": {
    "servers": {
      "azure": {
        "url": "https://mcp.azure.com/sse",
        "oauth": {
          "clientId": "{env:AZURE_CLIENT_ID}",
          "clientSecret": "{env:AZURE_CLIENT_SECRET}",
          "authorizationUrl": "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize",
          "tokenUrl": "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token",
          "scope": "https://graph.microsoft.com/.default"
        }
      }
    }
  }
}

Okta

{
  "mcp": {
    "servers": {
      "okta": {
        "url": "https://mcp.company.com/sse",
        "oauth": {
          "clientId": "{env:OKTA_CLIENT_ID}",
          "authorizationUrl": "https://company.okta.com/oauth2/v1/authorize",
          "tokenUrl": "https://company.okta.com/oauth2/v1/token",
          "scope": "openid profile"
        }
      }
    }
  }
}

Custom Callback Server

Local Callback

Default callback server:

http://localhost:8765/callback

Custom Port

{
  "oauth": {
    "callbackPort": 9000
  }
}

Custom Path

{
  "oauth": {
    "callbackPath": "/oauth/callback"
  }
}

Security Best Practices

Client Secret Protection

Never commit secrets to version control
Use environment variables
Rotate secrets periodically
Use PKCE for public clients

Token Security

Tokens are encrypted at rest
Use short-lived access tokens
Implement token rotation
Revoke tokens on logout

Scope Minimization

Request minimum required scopes
Review scope permissions
Avoid wildcard scopes
Audit scope usage

Troubleshooting

Authorization Failed

Error: OAuth authorization failed

Check:

Client ID is correct
Authorization URL is accessible
Redirect URI is registered

Token Exchange Failed

Error: Token exchange failed

Verify:

Client secret is correct (if required)
Token URL is accessible
Grant type is supported

Token Refresh Failed

Error: Token refresh failed

Solutions:

Re-authenticate manually
Check refresh token validity
Verify token URL

Callback Not Received

Error: Callback timeout