coder/.claude/docs/OAUTH2.md

OAuth2 Development Guide

RFC Compliance Development

Implementing Standard Protocols

When implementing standard protocols (OAuth2, OpenID Connect, etc.):

1. Fetch and Analyze Official RFCs:

   • Always read the actual RFC specifications before implementation
   • Use WebFetch tool to get current RFC content for compliance verification
   • Document RFC requirements in code comments

2. Default Values Matter:

   • Pay close attention to RFC-specified default values
   • Example: RFC 7591 specifies client_secret_basic as default, not client_secret_post
   • Ensure consistency between database migrations and application code

3. Security Requirements:

   • Follow RFC security considerations precisely
   • Example: RFC 7592 prohibits returning registration access tokens in GET responses
   • Implement proper error responses per protocol specifications

4. Validation Compliance:

   • Implement comprehensive validation per RFC requirements
   • Support protocol-specific features (e.g., custom schemes for native OAuth2 apps)
   • Test edge cases defined in specifications

OAuth2 Provider Implementation

OAuth2 Spec Compliance

1. Follow RFC 6749 for token responses

   • Use expires_in (seconds) not expiry (timestamp) in token responses
   • Return proper OAuth2 error format: {"error": "code", "error_description": "details"}

2. Error Response Format

   • Create OAuth2-compliant error responses for token endpoint
   • Use standard error codes: invalid_client, invalid_grant, invalid_request
   • Avoid generic error responses for OAuth2 endpoints

PKCE Implementation

• Support both with and without PKCE for backward compatibility
• Use S256 method for code challenge
• Properly validate code_verifier against stored code_challenge

UI Authorization Flow

• Use POST requests for consent, not GET with links
• Avoid dependency on referer headers for security decisions
• Support proper state parameter validation

RFC 8707 Resource Indicators

• Store resource parameters in database for server-side validation (opaque tokens)
• Validate resource consistency between authorization and token requests
• Support audience validation in refresh token flows
• Resource parameter is optional but must be consistent when provided

OAuth2 Error Handling Pattern

// Define specific OAuth2 errors
var (
    errInvalidPKCE = xerrors.New("invalid code_verifier")
)

// Use OAuth2-compliant error responses
type OAuth2Error struct {
    Error            string `json:"error"`
    ErrorDescription string `json:"error_description,omitempty"`
}

// Return proper OAuth2 errors
if errors.Is(err, errInvalidPKCE) {
    writeOAuth2Error(ctx, rw, http.StatusBadRequest, "invalid_grant", "The PKCE code verifier is invalid")
    return
}

Testing OAuth2 Features

Test Scripts

Located in ./scripts/oauth2/:

• test-mcp-oauth2.sh - Full automated test suite
• setup-test-app.sh - Create test OAuth2 app
• cleanup-test-app.sh - Remove test app
• generate-pkce.sh - Generate PKCE parameters
• test-manual-flow.sh - Manual browser testing

Always run the full test suite after OAuth2 changes:

./scripts/oauth2/test-mcp-oauth2.sh

RFC Protocol Testing

1. Compliance Test Coverage:

   • Test all RFC-defined error codes and responses
   • Validate proper HTTP status codes for different scenarios
   • Test protocol-specific edge cases (URI formats, token formats, etc.)

2. Security Boundary Testing:

   • Test client isolation and privilege separation
   • Verify information disclosure protections
   • Test token security and proper invalidation

Common OAuth2 Issues

1. OAuth2 endpoints returning wrong error format - Ensure OAuth2 endpoints return RFC 6749 compliant errors
2. Resource indicator validation failing - Ensure database stores and retrieves resource parameters correctly
3. PKCE tests failing - Verify both authorization code storage and token exchange handle PKCE fields
4. RFC compliance failures - Verify against actual RFC specifications, not assumptions
5. Authorization context errors in public endpoints - Use dbauthz.AsSystemRestricted(ctx) pattern
6. Default value mismatches - Ensure database migrations match application code defaults
7. Bearer token authentication issues - Check token extraction precedence and format validation
8. URI validation failures - Support both standard schemes and custom schemes per protocol requirements

Authorization Context Patterns

// Public endpoints needing system access (OAuth2 registration)
app, err := api.Database.GetOAuth2ProviderAppByClientID(dbauthz.AsSystemRestricted(ctx), clientID)

// Authenticated endpoints with user context
app, err := api.Database.GetOAuth2ProviderAppByClientID(ctx, clientID)

// System operations in middleware
roles, err := db.GetAuthorizationUserRoles(dbauthz.AsSystemRestricted(ctx), userID)

OAuth2/Authentication Work Patterns

• Types go in codersdk/oauth2.go or similar
• Handlers go in coderd/oauth2.go or coderd/identityprovider/
• Database fields need migration + audit table updates
• Always support backward compatibility

Protocol Implementation Checklist

Before completing OAuth2 or authentication feature work:

• Verify RFC compliance by reading actual specifications
• Implement proper error response formats per protocol
• Add comprehensive validation for all protocol fields
• Test security boundaries and token handling
• Update RBAC permissions for new resources
• Add audit logging support if applicable
• Create database migrations with proper defaults
• Add comprehensive test coverage including edge cases
• Verify linting compliance
• Test both positive and negative scenarios
• Document protocol-specific patterns and requirements