OAuth 2.1: Phase 3 - GitHub Actions and CI/CD Support

[richardwooding]

Overview

Add OAuth 2.1 support for GitHub Actions and CI/CD environments where interactive browser-based authentication is not possible.

Prerequisites

• Phase 1 (Core OAuth) completed ✅
• Phase 2 (Discovery & Refresh) preferred but not required

Phase 3 Goals

Enable OAuth authentication in non-interactive environments like GitHub Actions, Jenkins, GitLab CI, etc.

Tasks

Client Credentials Flow

• Implement OAuth 2.1 client credentials grant type
• Add --oauth-grant-type flag (authorization_code, client_credentials)
• Support for service account authentication
• Non-interactive token acquisition
• Validate MCP server support for client credentials

GitHub Actions Integration

• Update action.yml with OAuth input parameters:
  • oauth-client-id
  • oauth-client-secret (from GitHub Secrets)
  • oauth-grant-type
  • oauth-scopes
  • oauth-no-cache
• Document GitHub Secrets usage
• Add workflow examples for OAuth-protected servers
• Support for token caching in GitHub Actions cache
• Environment variable configuration

Device Authorization Flow (Optional)

• Implement RFC 8628 device authorization grant
• User visits URL and enters device code
• Polling for authorization completion
• Suitable for headless environments with user access
• Better UX than manual token injection

CI/CD Documentation

• GitHub Actions workflow examples
• Jenkins pipeline examples
• GitLab CI configuration examples
• Environment variable reference
• Secrets management best practices

Testing

• Test client credentials flow with mock OAuth server
• Verify GitHub Actions integration
• Test token caching in CI environment
• Validate error handling in non-interactive mode

Configuration Examples

GitHub Actions Workflow

- name: Generate MCP Documentation
  uses: spandigital/mcp-server-dump@v1
  with:
    transport: streamable
    endpoint: https://mcp.example.com/stream
    oauth-client-id: ${{ vars.OAUTH_CLIENT_ID }}
    oauth-client-secret: ${{ secrets.OAUTH_CLIENT_SECRET }}
    oauth-grant-type: client_credentials
    format: html
    output-file: docs.html

CLI Usage

# Client credentials flow (non-interactive)
mcp-server-dump --transport=streamable \
  --endpoint="https://mcp.example.com/stream" \
  --oauth-client-id="${OAUTH_CLIENT_ID}" \
  --oauth-client-secret="${OAUTH_CLIENT_SECRET}" \
  --oauth-grant-type=client_credentials

# Device flow (interactive but works in SSH/containers)
mcp-server-dump --transport=streamable \
  --endpoint="https://mcp.example.com/stream" \
  --oauth-client-id="${OAUTH_CLIENT_ID}" \
  --oauth-grant-type=device

Success Criteria

• GitHub Actions can authenticate to OAuth MCP servers
• Client credentials flow works in CI/CD
• Feature parity between CLI and GitHub Action
• Comprehensive CI/CD documentation
• Zero secrets exposed in logs

Estimated Timeline

1.5 weeks of development + testing

Security Considerations

• Never log client secrets or access tokens
• Use GitHub Secrets for sensitive values
• Support for ephemeral tokens in CI
• Clear warnings about credential exposure risks

References

• RFC 6749: OAuth 2.0 Client Credentials Grant
• RFC 8628: OAuth 2.0 Device Authorization Grant
• GitHub Actions: Using secrets in workflows
• OAuth 2.1 Draft: https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13