feat(keycloak): add keycloak to docker-compose and enable sso by default for development testing by crivetimihai · Pull Request #2949 · IBM/mcp-context-forge

crivetimihai · 2026-02-14T16:46:34Z

Summary

This epic adds a complete local Keycloak development path for SSO testing in compose, and hardens the SSO callback path so local auth-code login is reliable by default when the SSO profile is enabled.

Closes #2875

What Changed

1) Compose + Keycloak dev profile

Added docker-compose.sso.yml as an overlay for local SSO testing.
Enabled Keycloak-specific gateway env defaults for the SSO profile (realm/client/base URLs, role mapping defaults, etc.).
Added local Keycloak realm seed data in infra/keycloak/realm-export.json.
Updated compose docs and make targets for compose-sso / sso-test-login workflows.

2) Keycloak discovery/bootstrap wiring

Extended Keycloak discovery/bootstrap behavior for dev split-host setup:
- browser-facing URL (e.g. localhost:8180) for auth redirect
- internal URL (e.g. keycloak:8080) for backchannel calls
Updated config/docs so this path is explicit and repeatable.

3) SSO callback reliability fixes

Hardened Keycloak userinfo handling in SSOService:
- if Keycloak userinfo fails in dev host/port split scenarios, fallback to id_token claims.
Removed fragile post-commit ORM attribute reads in authenticate_or_create_user by snapshotting resolved values before commit/await boundaries.
Added explicit rollback in role-sync assignment exception paths to avoid leaving the SQLAlchemy session in a broken transaction state.

4) Test coverage and smoke checks

Added/updated unit tests for:
- Keycloak id_token fallback behavior
- session-safe callback auth flow (no post-commit lazy-load dependence)
- bootstrap/discovery behavior for Keycloak URLs
- role-sync failure rollback handling
Added scripts/test-sso-flow.sh and wired make sso-test-login to validate:
- provider exposure
- auth URL correctness
- seeded user role claims
- full browser callback redirect to /admin with auth cookie set

5) Documentation

Added developer-facing Keycloak local login guidance, including:
- default URLs
- default credentials
- pre-seeded users
- quick troubleshooting for error=sso_failed
Updated SSO/compose docs to reflect the local dev flow.

Changed Files (High-Level)

Compose/config: docker-compose.yml, docker-compose.sso.yml, .env.example, mcpgateway/config.py, mcpgateway/utils/keycloak_discovery.py, mcpgateway/utils/sso_bootstrap.py
SSO service: mcpgateway/services/sso_service.py
Tests: tests/unit/mcpgateway/services/test_sso_service.py, tests/unit/mcpgateway/utils/test_keycloak_discovery.py, tests/unit/mcpgateway/utils/test_sso_bootstrap.py
Smoke automation: scripts/test-sso-flow.sh
Docs: docs/docs/deployment/compose.md, docs/docs/development/developer-workstation.md, docs/docs/development/index.md, docs/docs/manage/sso.md, docs/docs/manage/sso-keycloak-tutorial.md
Generated diagrams updated: docs/docs/design/images/classes.svg, docs/docs/design/images/code2flow.svg, docs/docs/design/images/packages.svg

Validation Performed

pytest tests/unit/mcpgateway/services/test_sso_service.py -q
pytest tests/unit/mcpgateway/routers/test_sso_router.py -q
pytest tests/unit/mcpgateway/utils/test_keycloak_discovery.py tests/unit/mcpgateway/utils/test_sso_bootstrap.py -q
make sso-test-login (includes browser callback check)
docker compose -f docker-compose.yml -f docker-compose.sso.yml --profile sso up -d --build

Notes / Follow-up

This PR is intentionally opened as a draft to unblock review while additional follow-up fixes are still expected.
The diagram SVG changes are regenerated outputs from the updated docs image workflow.

…sting - Add Keycloak service to docker-compose.yml (pinned to v26.1) with pre-configured realm export for local SSO development - Add docker-compose.sso.yml overlay for SSO-specific configuration - Add "sso" to testing and inspector service profiles so --profile sso brings up the full dev stack (Keycloak + testing + inspector) - Implement SSO bootstrap utility for automatic Keycloak realm/client setup - Add Keycloak discovery helper with well-known endpoint support - Enhance SSO service with id_token claims fallback for split-host configurations (restricted to 401 + split-host detection only) - Improve admin.py SSO logout with proper id_token_hint RP-initiated flow - Skip expired id_token_hint in logout URL to avoid Keycloak rejection - Add cookie size validation for id_token storage (>3.8KB warning) - Use dynamic max_age for SSO cookies matching token_expiry setting - Improve error handling and logging throughout SSO flows - Add sso-keycloak-tutorial and developer workstation documentation - Add test-sso-flow.sh script for manual SSO flow verification - Add Makefile targets for Keycloak lifecycle management Closes #2949 Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

- Add SSO service tests for Keycloak userinfo fallback, callback error handling, personal team resolution, and user authentication flows - Add Keycloak discovery and SSO bootstrap unit tests - Update SSO router tests to use handle_oauth_callback_with_tokens - Update admin module tests for Keycloak-aware logout behavior with separate coverage for keycloak-enabled and keycloak-disabled paths - Add expired id_token_hint omission test - Add id_token cookie size and max_age validation tests Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

…ult for development testing (#2949) * feat(keycloak): add Keycloak SSO to docker-compose for development testing - Add Keycloak service to docker-compose.yml (pinned to v26.1) with pre-configured realm export for local SSO development - Add docker-compose.sso.yml overlay for SSO-specific configuration - Add "sso" to testing and inspector service profiles so --profile sso brings up the full dev stack (Keycloak + testing + inspector) - Implement SSO bootstrap utility for automatic Keycloak realm/client setup - Add Keycloak discovery helper with well-known endpoint support - Enhance SSO service with id_token claims fallback for split-host configurations (restricted to 401 + split-host detection only) - Improve admin.py SSO logout with proper id_token_hint RP-initiated flow - Skip expired id_token_hint in logout URL to avoid Keycloak rejection - Add cookie size validation for id_token storage (>3.8KB warning) - Use dynamic max_age for SSO cookies matching token_expiry setting - Improve error handling and logging throughout SSO flows - Add sso-keycloak-tutorial and developer workstation documentation - Add test-sso-flow.sh script for manual SSO flow verification - Add Makefile targets for Keycloak lifecycle management Closes #2949 Signed-off-by: Mihai Criveti <crivetimihai@gmail.com> * test(keycloak): add and update tests for Keycloak SSO integration - Add SSO service tests for Keycloak userinfo fallback, callback error handling, personal team resolution, and user authentication flows - Add Keycloak discovery and SSO bootstrap unit tests - Update SSO router tests to use handle_oauth_callback_with_tokens - Update admin module tests for Keycloak-aware logout behavior with separate coverage for keycloak-enabled and keycloak-disabled paths - Add expired id_token_hint omission test - Add id_token cookie size and max_age validation tests Signed-off-by: Mihai Criveti <crivetimihai@gmail.com> --------- Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

…ult for development testing (#2949) * feat(keycloak): add Keycloak SSO to docker-compose for development testing - Add Keycloak service to docker-compose.yml (pinned to v26.1) with pre-configured realm export for local SSO development - Add docker-compose.sso.yml overlay for SSO-specific configuration - Add "sso" to testing and inspector service profiles so --profile sso brings up the full dev stack (Keycloak + testing + inspector) - Implement SSO bootstrap utility for automatic Keycloak realm/client setup - Add Keycloak discovery helper with well-known endpoint support - Enhance SSO service with id_token claims fallback for split-host configurations (restricted to 401 + split-host detection only) - Improve admin.py SSO logout with proper id_token_hint RP-initiated flow - Skip expired id_token_hint in logout URL to avoid Keycloak rejection - Add cookie size validation for id_token storage (>3.8KB warning) - Use dynamic max_age for SSO cookies matching token_expiry setting - Improve error handling and logging throughout SSO flows - Add sso-keycloak-tutorial and developer workstation documentation - Add test-sso-flow.sh script for manual SSO flow verification - Add Makefile targets for Keycloak lifecycle management Closes #2949 Signed-off-by: Mihai Criveti <crivetimihai@gmail.com> * test(keycloak): add and update tests for Keycloak SSO integration - Add SSO service tests for Keycloak userinfo fallback, callback error handling, personal team resolution, and user authentication flows - Add Keycloak discovery and SSO bootstrap unit tests - Update SSO router tests to use handle_oauth_callback_with_tokens - Update admin module tests for Keycloak-aware logout behavior with separate coverage for keycloak-enabled and keycloak-disabled paths - Add expired id_token_hint omission test - Add id_token cookie size and max_age validation tests Signed-off-by: Mihai Criveti <crivetimihai@gmail.com> --------- Signed-off-by: Mihai Criveti <crivetimihai@gmail.com> Signed-off-by: Vishu Bhatnagar <vishu.bhatnagar@ibm.com>

…ult for development testing (IBM#2949) * feat(keycloak): add Keycloak SSO to docker-compose for development testing - Add Keycloak service to docker-compose.yml (pinned to v26.1) with pre-configured realm export for local SSO development - Add docker-compose.sso.yml overlay for SSO-specific configuration - Add "sso" to testing and inspector service profiles so --profile sso brings up the full dev stack (Keycloak + testing + inspector) - Implement SSO bootstrap utility for automatic Keycloak realm/client setup - Add Keycloak discovery helper with well-known endpoint support - Enhance SSO service with id_token claims fallback for split-host configurations (restricted to 401 + split-host detection only) - Improve admin.py SSO logout with proper id_token_hint RP-initiated flow - Skip expired id_token_hint in logout URL to avoid Keycloak rejection - Add cookie size validation for id_token storage (>3.8KB warning) - Use dynamic max_age for SSO cookies matching token_expiry setting - Improve error handling and logging throughout SSO flows - Add sso-keycloak-tutorial and developer workstation documentation - Add test-sso-flow.sh script for manual SSO flow verification - Add Makefile targets for Keycloak lifecycle management Closes IBM#2949 Signed-off-by: Mihai Criveti <crivetimihai@gmail.com> * test(keycloak): add and update tests for Keycloak SSO integration - Add SSO service tests for Keycloak userinfo fallback, callback error handling, personal team resolution, and user authentication flows - Add Keycloak discovery and SSO bootstrap unit tests - Update SSO router tests to use handle_oauth_callback_with_tokens - Update admin module tests for Keycloak-aware logout behavior with separate coverage for keycloak-enabled and keycloak-disabled paths - Add expired id_token_hint omission test - Add id_token cookie size and max_age validation tests Signed-off-by: Mihai Criveti <crivetimihai@gmail.com> --------- Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

crivetimihai marked this pull request as ready for review February 14, 2026 17:25

crivetimihai requested review from kevalmahajan and madhav165 as code owners February 14, 2026 17:25

crivetimihai changed the title ~~[EPIC][SSO]: Add Keycloak to docker-compose and enable SSO by default for development testing~~ feat(keycloak): add keycloak to docker-compose and enable sso by default for development testing Feb 14, 2026

crivetimihai force-pushed the sso-keycloak branch from 250d25d to 1581e4a Compare February 14, 2026 23:32

crivetimihai self-assigned this Feb 14, 2026

crivetimihai added this to the Release 1.0.0-RC1 milestone Feb 14, 2026

crivetimihai added 2 commits February 14, 2026 23:47

crivetimihai force-pushed the sso-keycloak branch from 1581e4a to 5a171c6 Compare February 14, 2026 23:55

crivetimihai merged commit 71c361c into main Feb 15, 2026
54 checks passed

crivetimihai deleted the sso-keycloak branch February 15, 2026 00:22

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(keycloak): add keycloak to docker-compose and enable sso by default for development testing#2949

feat(keycloak): add keycloak to docker-compose and enable sso by default for development testing#2949
crivetimihai merged 2 commits intomainfrom
sso-keycloak

crivetimihai commented Feb 14, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

crivetimihai commented Feb 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What Changed

1) Compose + Keycloak dev profile

2) Keycloak discovery/bootstrap wiring

3) SSO callback reliability fixes

4) Test coverage and smoke checks

5) Documentation

Changed Files (High-Level)

Validation Performed

Notes / Follow-up

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

crivetimihai commented Feb 14, 2026 •

edited

Loading