sso

CLAUDE.md

@@ -88,6 +88,9 @@ npm test
 # Start all services (PostgreSQL, API, Nginx, Frontend)
 podman-compose up -d
 
+# Start with SSO testing enabled (Keycloak + SAML IdP)
+podman-compose -f docker-compose.yml -f docker-compose.sso.yml up -d
+
 # Check service health
 curl http://localhost:8081/health
 
@@ -97,10 +100,15 @@ podman-compose logs -f
 # View specific service logs
 podman-compose logs -f api-service
 podman-compose logs -f postgres
+podman-compose logs -f keycloak
+podman-compose logs -f saml-idp
 
 # Stop services  
 podman-compose down
 
+# Stop SSO services
+podman-compose -f docker-compose.yml -f docker-compose.sso.yml down
+
 # Rebuild services after code changes
 podman-compose up -d --build
 ```
@@ -182,12 +190,34 @@ podman-compose down
 - **Port 3000**: React frontend (direct access)
 - **Port 5432**: PostgreSQL database
 - **Port 9090**: Metrics endpoint (if enabled)
+- **Port 8090**: Keycloak SSO server (admin console)
+- **Port 8091**: SimpleSAMLphp IdP (SAML console: /simplesaml)
+- **Port 8443**: SimpleSAMLphp IdP (HTTPS)
 
 The service provides different test user contexts:
 - Regular user: `test@example.com`
 - Admin user: `admin@example.com`  
 - Limited user: `limited@example.com`
 
+### SSO Testing Users
+
+For SSO testing with Keycloak or SAML IdP, use these credentials:
+
+| Email | Password | Permissions | Provider |
+|-------|----------|-------------|----------|
+| admin@example.com | admin123 | internal.* | Keycloak |
+| test@example.com | test123 | app.read, token.read | Keycloak |
+| limited@example.com | limited123 | repo.read | Keycloak |
+| user1@example.com | user1pass | Basic access | SAML IdP |
+| user2@example.com | user2pass | Basic access | SAML IdP |
+
+### SSO Access Points
+
+- **Keycloak Admin Console**: http://localhost:8090 (admin / admin)
+- **SAML IdP Admin Console**: http://localhost:8091/simplesaml (admin / secret)
+- **Keycloak Realm**: http://localhost:8090/realms/kms
+- **SAML IdP Metadata**: http://localhost:8091/simplesaml/saml2/idp/metadata.php
+
 ## Key Configuration
 
 ### Required Environment Variables
@@ -211,14 +241,28 @@ SERVER_HOST=0.0.0.0
 SERVER_PORT=8080
 
 # Authentication  
-AUTH_PROVIDER=header  # or 'sso'
+AUTH_PROVIDER=header  # 'header', 'sso', or 'saml'
 AUTH_HEADER_USER_EMAIL=X-User-Email
 
+# SSO / OAuth2 Configuration (for Keycloak)
+OAUTH2_ENABLED=false  # Set to true for OAuth2/OIDC auth
+OAUTH2_PROVIDER_URL=http://keycloak:8080/realms/kms
+OAUTH2_CLIENT_ID=kms-api
+OAUTH2_CLIENT_SECRET=kms-client-secret
+OAUTH2_REDIRECT_URL=http://localhost:8081/api/oauth2/callback
+
+# SAML Configuration (for SimpleSAMLphp)
+SAML_ENABLED=false  # Set to true for SAML auth
+SAML_IDP_SSO_URL=http://saml-idp:8080/simplesaml/saml2/idp/SSOService.php
+SAML_IDP_METADATA_URL=http://saml-idp:8080/simplesaml/saml2/idp/metadata.php
+SAML_SP_ENTITY_ID=http://localhost:8081
+SAML_SP_ACS_URL=http://localhost:8081/api/saml/acs
+SAML_SP_SLS_URL=http://localhost:8081/api/saml/sls
+
 # Features
 RATE_LIMIT_ENABLED=true
 CACHE_ENABLED=false  # Set to true to enable Redis
 METRICS_ENABLED=true
-SAML_ENABLED=false  # Set to true for SAML auth
 ```
 
 ### Optional Configuration
@@ -323,15 +367,67 @@ Example: `repo` permission includes `repo.read` and `repo.write`.
 - **Filtering**: Support for date ranges, event types, statuses, users, resource types
 - **Statistics**: Aggregated metrics by type, severity, status, and time
 
+## SSO Testing Workflow
+
+### Quick Start - OAuth2/OIDC Testing (Keycloak)
+
+```bash
+# 1. Start services with SSO enabled
+podman-compose -f docker-compose.yml -f docker-compose.sso.yml up -d
+
+# 2. Wait for Keycloak to start (check logs)
+podman-compose logs -f keycloak
+
+# 3. Test OAuth2 login flow
+curl -v "http://localhost:8090/realms/kms/protocol/openid-connect/auth?client_id=kms-api&response_type=code&redirect_uri=http://localhost:8081/api/oauth2/callback"
+
+# 4. Access Keycloak admin console
+open http://localhost:8090
+# Login with: admin / admin
+
+# 5. Test API with OAuth2 token
+# (Use Keycloak to get access token, then use in Authorization: Bearer header)
+```
+
+### Quick Start - SAML Testing (SimpleSAMLphp)
+
+```bash
+# 1. Services should already be running from previous step
+
+# 2. Access SAML IdP admin console  
+open http://localhost:8091/simplesaml
+# Login with: admin / secret
+
+# 3. View IdP metadata
+curl http://localhost:8091/simplesaml/saml2/idp/metadata.php
+
+# 4. Test SAML authentication flow
+# Navigate to your app and it should redirect to SAML IdP for auth
+```
+
+### Environment Switching
+
+```bash
+# Switch to OAuth2 mode
+podman exec kms-api-service sh -c "export AUTH_PROVIDER=sso OAUTH2_ENABLED=true && supervisorctl restart all"
+
+# Switch to SAML mode  
+podman exec kms-api-service sh -c "export AUTH_PROVIDER=sso SAML_ENABLED=true && supervisorctl restart all"
+
+# Switch back to header mode
+podman exec kms-api-service sh -c "export AUTH_PROVIDER=header && supervisorctl restart all"
+```
+
 ## Development Notes
 
 ### Critical Information
 - **Go Version**: Requires Go 1.23+ (currently using 1.24.4)
 - **Node Version**: Requires Node 24+ and npm 11+ 
 - **Database**: Auto-migrations run on startup
-- **Container Names**: Use `kms-postgres`, `kms-api-service`, `kms-frontend`, `kms-nginx`
-- **Default Ports**: API:8080, Nginx:8081, Frontend:3000, DB:5432, Metrics:9090
+- **Container Names**: Use `kms-postgres`, `kms-api-service`, `kms-frontend`, `kms-nginx`, `kms-keycloak`, `kms-saml-idp`
+- **Default Ports**: API:8080, Nginx:8081, Frontend:3000, DB:5432, Metrics:9090, Keycloak:8090, SAML:8091
 - **Test Database**: `kms_test` (separate from `kms`)
+- **SSO Config**: Located in `sso-config/` directory
 
 ### Important Files
 - `internal/config/config.go` - Complete configuration management