{"id":"303ccfce-f5cd-4934-be97-8a3aa85c17c4","slug":"keycloak-monitoring","kind":"mcp","name":"keycloak-monitoring","summary":"Multi-tenant monitoring dashboard for Keycloak: realms, clients, users, login and risk events, alerts, and Adaptive MFA statistics in one place, with a read-only MCP server for AI clients like Claude","owner":"DefensePoint","repoUrl":"https://github.com/DefensePoint/keycloak-monitoring","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":6,"match":null,"fewStars":false,"format":"mcp","createdAt":"2026-09-28T15:53:43.000Z","addedAt":"2026-10-21T09:47:05.448Z","logoUrl":"https://avatars.githubusercontent.com/u/64780913?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra","data-analytics","developer-tools"],"tags":["adaptive-authentication","dashboard","go","iam","keycloak","mfa","monitoring","observability"],"runtime":"go","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-21T09:47:19.289Z","sample":false,"url":"https://conduits.dev/tools/keycloak-monitoring","language":"Go","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Keycloak Monitoring Tool\n\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)\n\nA comprehensive monitoring and security compliance platform for Keycloak identity and access management systems. Built with Go and React, this platform provides real-time monitoring, automated security configuration scanning, alert management, and integrated notifications for multi-tenant Keycloak deployments.\n\n## Hosted demo\n\nA hosted demo is available so you can try the tool without standing it up from scratch:\n\n- [https://keycloak-monitoring-demo.defensepoint.com/](https://keycloak-monitoring-demo.defensepoint.com/)\n\n## Features\n\n### Core Capabilities\n\n- **Multi-Tenant Monitoring**: Monitor multiple Keycloak instances from a single platform with isolated tenant data\n- **Real-Time Event Tracking**: Comprehensive logging of logins, logouts, registrations, and security events with time-based filtering\n- **Security Configuration Scanning**: Automated detection of misconfigurations and security vulnerabilities across realms, clients, and identity providers\n- **Centralized Alert Management**: Track, acknowledge, resolve, and ignore security alerts with severity-based filtering\n- **Notification Integrations**: Send alerts to Slack, Email, and automatically create GitLab issues with configurable severity thresholds\n- **Dashboard Analytics**: Interactive charts and statistics showing authentication patterns and trends\n- **User & Client Management**: Browse users, clients, and sessions across all realms and tenants\n- **TimescaleDB Integration**: Efficient time-series data storage for high-volume event data\n- **RESTful API**: Full-featured API for integration, automation, and programmatic access\n- **Adaptive MFA (AMFA) Integration**: Optional. Shows each tenant's risk-scored logins and statistics next to Keycloak's own events, and can alert on risky logins and login-error bursts; see [Adaptive MFA (optional)](#adaptive-mfa-optional)\n\n### Security & Compliance Features\n\n- **Realm Security Checks**: SSL requirements, brute force protection, password policies, email verification, audit logging\n- **Client Security Checks**: Redirect URI validation, public client configurations, deprecated OAuth2 flows, HTTP detection\n- **Identity Provider Checks**: SAML metadata validation, certificate expiration monitoring, federation configuration\n- **Alert Lifecycle Management**: Active, Acknowledged, Resolved, and Ignored status tracking with audit trail\n- **Configurable Severity Levels**: Fine-grained control over what gets alerted where (info, warning, error, critical)\n- **Automated Remediation Guidance**: Each alert includes detailed recommendations for fixing the issue\n\n### Technical Features\n\n- **Role-Based Access Control (RBAC)**: Fine-grained permissions with three default roles (Admin, Operator, Viewer) and support for custom roles\n- **Dual Authentication**: Supports both simple username/password and OAuth2/OIDC (Keycloak SSO)\n- **Auto-Detection**: Automatically detects Keycloak version (17+ vs legacy /auth prefix)\n- **Health Monitoring**: Continuous health checks and server status monitoring for all tenants\n- **Configurable Polling**: Customizable intervals for metrics, events, health checks, and configuration scans\n- **Tenant Isolation**: Complete data separation between monitored Keycloak instances with tenant-scoped permissions\n- **Docker Support**: Full containerization with Docker and docker-compose for easy deployment\n- **Production Ready**: Built-in logging, error handling, graceful shutdown, and connection pooling\n- **PostgreSQL Storage**: Reliable data persistence with TimescaleDB extensions for time-series data\n- **Session Management**: Secure session handling with configurable cookies and CSRF protection\n\n## Adaptive MFA (optional)\n\nKMT works on its own. With the optional Adaptive MFA (AMFA) add-on, Keycloak asks a risk engine to score every login and requires a second factor only when a login looks risky. KMT then shows those risk-scored logins and statistics, and can alert on them. AMFA is three projects:\n\n- **[keycloak-adaptive-mfa-engine](https://github.com/DefensePoint/keycloak-adaptive-mfa-engine)**: The risk engine. Scores each login against the user's history with local ML inference and returns a risk level; it runs next to Keycloak and sends no data anywhere\n- **[keycloak-adaptive-mfa](https://github.com/DefensePoint/keycloak-adaptive-mfa)**: The Keycloak plugin that calls the engine at login and steps up to MFA when the risk is high\n- **[keycloak-adaptive-mfa-admin-ui](https://github.com/DefensePoint/keycloak-adaptive-mfa-admin-ui)**: A Keycloak Admin Console extension for configuring AMFA\n\nTo connect AMFA to KMT, see the [AMFA Integration Guide](docs/amfa-integration.md).\n\n## Architecture\n\nThe platform consists of the following main components:\n\n```bash\n┌─────────────────┐      ┌─────────────────┐      ┌──────────────────┐\n│  Web Frontend   │─────▶│   API Server    │─────▶│   PostgreSQL     │\n│   (React/TS)    │      │    (Go API)     │      │  (TimescaleDB)   │\n│   Port 7880     │      │   Port 7888     │      │   Port 5432      │\n└─────────────────┘      └─────────────────┘      └──────────────────┘\n                                  │                         ▲\n                                  │                         │ read-only\n                                  ▼                         │\n                         ┌─────────────────┐      ┌──────────────────┐\n                         │    Keycloak     │      │   MCP Server     │\n                         │  (Monitored)    │      │   Port 7889      │\n                         └─────────────────┘      └──────────────────┘\n```\n\n### Components\n\n- **API Server** (`cmd/server`): Go-based REST API server handling authentication, data retrieval, and Keycloak monitoring\n- **Web Server** (`cmd/web`): Serves the React frontend and proxies API requests\n- **MCP Server** (`cmd/mcp-server`): Read-only Model Context Protocol (MCP) server exposing monitoring data to MCP clients, disabled by default\n- **Frontend** (`web/`): React + TypeScript dashboard with Recharts for visualization\n- **Database**: PostgreSQL 17 with TimescaleDB for time-series data\n\nFor detailed architecture information, see the [architecture docs](docs/architecture.md).\n\n### MCP Server\n\n`cmd/mcp-server` exposes tenants, Keycloak realms, alerts, events and Adaptive Multi-Factor Authentication (AMFA) statistics to MCP clients such as Claude Code and Claude Desktop. Every tool is read-only, it runs as its own process alongside the API server, and it is disabled by default: set `mcp.enabled` in `config.yaml` to turn it on. Clients authenticate with personal access tokens and see only what the token and the acting user's RBAC roles allow. See [cmd/mcp-server/README.md](cmd/mcp-server/README.md) for the token lifecycle, client setup and tool reference.\n\n## Quick Start\n\nThe fastest way to get started is with Docker. See the **[Quick Start Guide](docs/quickstart.md)** for detailed step-by-step instructions.\n\n### Docker Deployment (Recommended)\n\n```bash\n# 1. Clone the repository\ngit clone https://github.com/DefensePoint/keycloak-monitoring.git\ncd keycloak-monitoring\n\n# 2. Copy and edit configuration\ncp config.yaml.example config.yaml\n# Edit config.yaml and add your Keycloak connection details\n\n# 3. Create the environment file the compose stack reads\n#    Exporting these in your shell is not enough: the services load env_file,\n#    so the values have to be in .env itself.\ncp .env.example .env\n#    Then edit .env and set at least MONITORING_AUTH_SIMPLE_DEFAULT_PASS,\n#    MONITORING_AUTH_SESSION_SECRET and MONITORING_SECURITY_ENCRYPTION_KEY.\n#    The password may not contain admin, password, secret, default, changeme\n#    or welcome, as substrings.\n\n# 4. Build and start services\nmake docker-build\nmake docker-up\n\n# 5. Access the dashboard at http://localhost:7880\n# Login with your configured admin credentials\n# IMPORTANT: Change the password after first login; the initial password remains valid until changed\n```\n\n### What You Get\n\nAfter following the quick start:\n\n- Complete monitoring platform running in Docker\n- PostgreSQL database with TimescaleDB\n- Real-time monitoring of your Keycloak instance\n- Automated security configuration scanning\n- Web dashboard with analytics and alerts\n\n### Next Steps\n\n1. **Add more Keycloak instances** via the Tenants page or configuration file\n2. **Configure notifications** for Slack, Email, or GitLab (see [quickstart guide](docs/quickstart.md#setting-up-notifications))\n3. **Review security alerts** on the Alerts page\n4. **Customize configuration checks** in `config.yaml`\n\nSee the **[Quick Start Guide](docs/quickstart.md)** for comprehensive setup instructions, including notification configuration and security best practices.\n\nFor a self-contained demo with two automatically configured Keycloaks, see\n[Local setup](docs/setup.md#self-contained-demo) and run `make docker-demo-up`.\n\n## Documentation\n\nComprehensive documentation is available in the `docs/` directory:\n\n### Getting Started\n\n- **[Quick Start Guide](docs/quickstart.md)** - Get up and running in 10 minutes\n- **[Keycloak Setup Guide](docs/keycloak-setup.md)** - How to configure Keycloak for monitoring\n\n### Configuration & Deployment\n\n- **[Configuration Guide](docs/configuration.md)** - Detailed configuration reference\n- **[RBAC Guide](docs/rbac.md)** - Role-Based Access Control configuration and management\n- **[Deployment Guide](docs/deployment.md)** - Production deployment instructions\n- **[AMFA Integration Guide](docs/amfa-integration.md)** - Connect each tenant's Adaptive MFA engine to KMT\n- **[Troubleshooting](docs/troubleshooting.md)** - Common issues and solutions\n\n### Development & Architecture\n\n- **[Architecture Guide](docs/architecture.md)** - System design and component overview\n- **[Engineering Guide](docs/engineering-guide.md)** - Development setup and workflow\n- **[Hacking Guide](docs/hacking-guide.md)** - Code structure and contribution guidelines\n\n## Development\n\n### Project Structure\n\n```bash\n.\n├── cmd/\n│   ├── mcp-server/      # MCP server entry point\n│   ├── server/          # API server entry point\n│   └── web/             # Web server entry point\n├── internal/            # Internal packages (not exported)\n├── pkg/                 # Public packages (can be imported)\n├── web/                 # React frontend\n│   ├── src/\n│   │   ├── components/  # React components\n│   │   ├── pages/       # Page components\n│   │   ├── services/    # API services\n│   │   └── types/       # TypeScript types\n│   └── dist/            # Built frontend (generated)\n├── deployments/         # Deployment configurations\n│   ├── local/           # Local docker-compose\n│   └── server/          # Production docker-compose\n├── docs/                # Documentation\n├── config.yaml.example  # Configuration template\n├── Dockerfile           # Multi-stage Docker build\n├── Makefile             # Build and development commands\n└── README.md            # This file\n```\n\n### Make Commands\n\nRun `make help` to see all available commands\n\n### Running Tests\n\n```bash\n# Run all tests\nmake test-all\n\n# Run backend tests with coverage\nmake test-backend\n\n# Run frontend tests\nmake test-frontend\n\n# Run specific test\ngo test -v ./pkg/keycloak/...\n```\n\nFor the full testing reference — including running backend tests via Docker without a local Go install, env-gated DB tests (`KMT_TEST_DATABASE_DSN`), and the build-tagged AMFA integration tests (`-tags=integration`, `AMFA_TEST_DSN`) — see [docs/engineering-guide.md § Testing](docs/engineering-guide.md#testing).\n\n## Deployment\n\n### Docker Compose (Recommended)\n\nThe easiest way to deploy is using Docker Compose:\n\n```bash\n# 1. Copy configuration\ncp config.yaml.example config.yaml\n\n# 2. Edit config.yaml with your settings\n\n# 3. Create .env and set the initial admin password in it\ncp .env.example .env\n\n# 4. Build images\nmake docker-build\n\n# 5. Start services\nmake docker-up\n\n# 6. Check logs\nmake docker-logs\n```\n\n### Manual Deployment\n\nSee [docs/deployment.md](docs/deployment.md) for detailed deployment instructions including:\n\n- Kubernetes deployment\n- Systemd service configuration\n- Reverse proxy setup (nginx/traefik)\n- SSL/TLS configuration\n- Production best practices\n\n## Configuration\n\nThe application is configured via `config.yaml`. Key configuration sections include:\n\n### Multi-Tenant Keycloak Monitoring\n\n```yaml\nkeycloak:\n  # Global settings (inherited by all tenants)\n  global:\n    polling:\n      metrics_interval: 5m\n      events_interval: 30s\n      health_interval: 1m\n\n    # Automated configuration checking\n    config_checker:\n      poll_interval: 5m\n      checks:\n        realm_security:\n          enabled: true\n          check_ssl_required: true\n          check_brute_force: true\n          min_password_length: 12\n        client_security:\n          enabled: true\n          check_redirect_uris: true\n          production_environment: true\n\n  # Monitored Keycloak instances\n  tenants:\n    prod-keycloak:\n      enabled: true\n      name: \"Production Keycloak\"\n      server_url: \"https://keycloak.example.com\"\n      admin_realm: \"master\"\n      client_id: \"monitoring-service\"\n      client_secret: \"${PROD_KEYCLOAK_CLIENT_SECRET}\"\n      tags: [\"production\", \"critical\"]\n```\n\n### Notification Integrations\n\n```yaml\nnotifications:\n  # Send critical alerts to Slack\n  slack:\n    enabled: true\n    webhook_url: \"${SLACK_WEBHOOK_URL}\"\n    min_severity: \"warning\"  # warning, error, critical\n\n  # Email for errors and critical\n  email:\n    enabled: true\n    smtp_host: \"smtp.gmail.com\"\n    smtp_port: 587\n    from: \"alerts@example.com\"\n    to: [\"security-team@example.com\"]\n    min_severity: \"error\"  # error, critical only\n\n  # Create GitLab issues for critical alerts\n  gitlab:\n    enabled: true\n    url: \"https://gitlab.com\"\n    token: \"${GITLAB_TOKEN}\"\n    project_id: \"12345\"\n    min_severity: \"critical\"  # critical only\n```\n\n### Authentication\n\n```yaml\nauth:\n  simple:\n    enabled: true\n    # SECURITY: Set credentials via environment variables, NOT in config files\n    # Leave these empty and use:\n    #   MONITORING_AUTH_SIMPLE_DEFAULT_USER=admin\n    #   MONITORING_AUTH_SIMPLE_DEFAULT_PASS=<strong-password>  # Must meet complexity requirements\n    #   MONITORING_AUTH_SIMPLE_DEFAULT_EMAIL=admin@example.com\n    default_user: \"\"\n    default_pass: \"\"\n    default_email: \"\"\n  oauth2:\n    enabled: false\n    provider_url: \"https://keycloak.example.com/realms/master\"\n    client_id: \"monitoring-dashboard\"\n    client_secret: \"your-secret\"\n```\n\nInitial administrator credentials are needed when the database has no users. See\n[environment requirements and password rules](docs/configuration.md#deployment-variable-requirements).\n\nChange the password after first login. The platform does not rotate it automatically, so the initial password remains valid until changed.\n\nFor complete configuration reference, see the [configuration documents](docs/configuration.md) or review the [configuration example](config.yaml.example).\n\n### Environment Variables\n\nUse `MONITORING_*` overrides for keys with a built-in default or a key present in\n`config.yaml`. Other variables are ignored. See the\n[environment variable reference](docs/configuration.md#environment-variables).\n\n```bash\nexport MONITORING_DATABASE_HOST=localhost\nexport MONITORING_DATABASE_PASSWORD=secure_password\nexport MONITORING_AUTH_SESSION_SECRET=$(openssl rand -base64 32)\n```\n\nKeycloak tenants are configured under `keycloak.tenants` in `config.yaml`. Keep their client secrets out of the file with a placeholder, `client_secret: \"${PROD_KEYCLOAK_CLIENT_SECRET}\"`, and set that variable in the environment.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding guidelines, and how to submit pull requests.\n\n## License\n\nApache-2.0 -- see [LICENSE](LICENSE).\n"}