Add Keycloak OIDC client configuration automation with comprehensive documentation

[sharpninja]

Overview

This pull request establishes complete automation for Keycloak OIDC client configuration in McpServer, including setup scripts for three distinct authentication clients, helper utilities for secret management, and comprehensive operational documentation.

🍜 Tonkotsu did 5 tasks for this pull request.

Changes Made

1. Keycloak Setup Scripts

Created automated setup scripts that configure the complete Keycloak realm and all three OIDC clients:

PowerShell Script (scripts/Setup-McpKeycloak.ps1):

• Creates mcpserver realm with optimized token lifespans
• Configures three OIDC clients: mcp-server-api, mcp-director, and mcp-web
• Sets up realm roles (admin, agent-manager, viewer)
• Displays comprehensive setup summary with all client secrets

Bash Script (scripts/setup-mcp-keycloak.sh):

• Cross-platform equivalent with identical functionality
• Works on Linux, macOS, and Windows (WSL/Git Bash)
• Includes idempotent operations and error handling

2. Client Secret Sync Helper Scripts

Created helper utilities to retrieve and update client secrets in application configuration:

PowerShell Script (scripts/Update-McpWebClientSecret.ps1):

• Retrieves mcp-web client secret from Keycloak via REST API
• Updates appsettings.Development.json using native JSON parsing
• Preserves JSON structure with ConvertFrom-Json/ConvertTo-Json

Bash Script (scripts/update-mcp-web-client-secret.sh):

• Cross-platform equivalent with smart JSON handling
• Primary: Uses jq for JSON manipulation
• Fallback: Uses Python 3's json module if jq unavailable
• Comprehensive argument parsing and colored output

3. Three-Client OIDC Architecture

mcp-server-api (Confidential Client):

• Purpose: JWT Bearer token validation on API server
• Flow: Service Accounts enabled
• Configuration: Client secret displayed in setup summary

mcp-director (Public Client):

• Purpose: CLI authentication via Device Authorization Flow
• Flow: OAuth 2.0 Device Flow enabled
• Configuration: No client secret (public client)

mcp-web (Confidential Client):

• Purpose: Web UI authentication via Authorization Code Flow
• Flow: Standard Flow enabled
• Redirect URIs: http://localhost:*, $McpServerUrl/*
• Web Origins: http://localhost:*, $McpServerUrl
• Configuration: Client secret retrieved and displayed

All clients include protocol mappers for:

• Audience mapping to mcp-server-api
• Realm roles mapping for authorization

4. Comprehensive Documentation

Created complete operational documentation in docs/Operations/:

ClientArchitecture.md:

• Detailed explanation of each client's purpose and configuration
• OAuth 2.0 flow descriptions (Device Flow and Authorization Code Flow)
• Code references showing client usage in codebase
• Security considerations for each client type

SetupScripts.md:

• Step-by-step guide for running setup scripts
• Parameter reference for both PowerShell and Bash versions
• Example outputs showing the 10-step setup process
• Post-setup instructions for user creation and role assignment
• Troubleshooting section for common issues

HelperScripts.md:

• Usage guide for client secret synchronization scripts
• When to run scripts (setup, regeneration, CI/CD)
• Security best practices for production environments
• Manual alternatives for secret configuration

README.md:

• Quick start guide with architecture diagram
• Token flow explanation
• Links to detailed documentation
• Additional OAuth 2.0 and Keycloak resources

Technical Details

Script Features

• Parameterized configuration with sensible defaults
• Idempotent operations (skip if resources already exist)
• Comprehensive error handling with clear error messages
• Colored console output for visual feedback
• Step-by-step progress indicators for all operations
• Detailed setup summaries with next steps

JSON Manipulation

• PowerShell: Uses native ConvertFrom-Json/ConvertTo-Json
• Bash: Smart fallback from jq to Python 3's json module
• Structure preservation: All JSON updates maintain formatting and structure

Security Considerations

• Client secrets retrieved via secure API calls
• Documentation includes production best practices
• Guidance on using user secrets, environment variables, and Key Vault
• Clear warnings about storing secrets in development files

Usage Examples

Setup Keycloak (PowerShell):

.\scripts\Setup-McpKeycloak.ps1
.\scripts\Setup-McpKeycloak.ps1 -KeycloakUrl "http://keycloak:8080" -McpServerUrl "https://mcp.example.com"

Setup Keycloak (Bash):

./scripts/setup-mcp-keycloak.sh
KEYCLOAK_URL=http://keycloak:8080 MCP_SERVER_URL=https://mcp.example.com ./scripts/setup-mcp-keycloak.sh

Update Client Secret (PowerShell):

.\scripts\Update-McpWebClientSecret.ps1

Update Client Secret (Bash):

./scripts/update-mcp-web-client-secret.sh

Benefits

1. Zero-touch Keycloak setup: Complete realm and client configuration in one command
2. Cross-platform support: Identical functionality on Windows, Linux, and macOS
3. Developer-friendly: Automated secret synchronization eliminates manual configuration
4. Production-ready: Includes security best practices and deployment guidance
5. Well-documented: Comprehensive documentation for all aspects of the authentication system