INTO-CPS-Association · prasadtalasila · Jan 19, 2026 · Jan 21, 2026 · Jan 22, 2026 · Jan 22, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,27 @@
 
 The main changes made so far are listed here.
 
+## 21-Jan-2026
+
+* **Keycloak Integration**: Added Keycloak as the default identity provider for authentication
+  * Replaced GitLab OAuth with OIDC-based authentication
+  * New `keycloak` service in `compose.traefik.secure.yml`
+  * Updated `traefik-forward-auth` to use OIDC provider
+  * Added persistent volume for Keycloak data
+* **Environment Configuration**: Updated `.env.example` with Keycloak-specific variables
+  * Maintained backward compatibility with GitLab OAuth
+  * Added comprehensive comments for both authentication methods
+* **Documentation**: Created comprehensive setup and migration guides
+  * [KEYCLOAK_SETUP.md](KEYCLOAK_SETUP.md) - Detailed Keycloak configuration
+  * [KEYCLOAK_MIGRATION.md](KEYCLOAK_MIGRATION.md) - Migration guide from GitLab
+  * Updated [CONFIGURATION.md](CONFIGURATION.md) to reference Keycloak
+  * Updated [TRAEFIK_SECURE.md](TRAEFIK_SECURE.md) with Keycloak instructions
+* **Flexibility**: Designed for minimal changes when moving Keycloak external
+  * Environment variable based configuration
+  * Easy to switch between internal and external Keycloak
+  * Can still use GitLab OAuth with minor compose file modifications
+
+
 ## Week of 10-Feb-2026
 
 ### Added
@@ -77,6 +98,7 @@ The main changes made so far are listed here.
 
 ## 15-Dec-2025
 
+
 * Adds both ml-workspace and workspace in one docker compose
   and puts them behind traefik proxy
 * Based on the KASM core ubuntu image.

diff --git a/KEYCLOAK_MIGRATION.md b/KEYCLOAK_MIGRATION.md
@@ -0,0 +1,234 @@
+# Keycloak Integration - Migration Guide
+
+This document describes the changes made to integrate Keycloak authentication into the DTaaS workspace deployment.
+
+## What Changed
+
+The `compose.traefik.secure.yml` file has been updated to use **Keycloak** as the identity provider instead of GitLab OAuth. This provides:
+
+- ✅ **OIDC Standards Compliance**: Uses OpenID Connect for authentication
+- ✅ **Better User Management**: Centralized identity and access management
+- ✅ **Flexibility**: Easy to switch between internal and external Keycloak
+- ✅ **Enterprise Features**: Support for SSO, MFA, user federation, and more
+- ✅ **Backward Compatibility**: Can still use GitLab OAuth with minor configuration changes
+
+## New Services
+
+### Keycloak Service
+
+A new `keycloak` service has been added to the compose file:
+
+```yaml
+keycloak:
+  image: quay.io/keycloak/keycloak:26.0.7
+  # Accessible at http://foo.com/auth
+  # Provides OIDC authentication
+```
+
+**Key Features:**
+- Runs in development mode (`start-dev`)
+- Accessible via Traefik at `/auth` path
+- Persistent data storage with Docker volume
+- Configurable via environment variables
+
+## Modified Services
+
+### traefik-forward-auth
+
+Updated to use OIDC provider instead of generic OAuth:
+
+**Before:**
+```yaml
+environment:
+  - DEFAULT_PROVIDER=generic-oauth
+  - PROVIDERS_GENERIC_OAUTH_AUTH_URL=${OAUTH_URL}/oauth/authorize
+  - PROVIDERS_GENERIC_OAUTH_TOKEN_URL=${OAUTH_URL}/oauth/token
+  - PROVIDERS_GENERIC_OAUTH_USER_URL=${OAUTH_URL}/api/v4/user
+```
+
+**After:**
+```yaml
+environment:
+  - DEFAULT_PROVIDER=oidc
+  - PROVIDERS_OIDC_ISSUER_URL=${KEYCLOAK_ISSUER_URL}
+  - PROVIDERS_OIDC_CLIENT_ID=${KEYCLOAK_CLIENT_ID}
+  - PROVIDERS_OIDC_CLIENT_SECRET=${KEYCLOAK_CLIENT_SECRET}
+```
+
+## Configuration Files Updated
+
+### 1. `compose.traefik.secure.yml`
+
+- Added `keycloak` service
+- Updated `traefik-forward-auth` to use OIDC
+- Added `keycloak-data` volume for persistence
+- Added `depends_on` to ensure Keycloak starts before auth
+
+### 2. `dtaas/.env.example`
+
+- Added Keycloak-specific environment variables
+- Maintained backward compatibility with GitLab OAuth
+- Added comprehensive comments for both authentication methods
+
+### 3. `CONFIGURATION.md`
+
+- Updated to reference Keycloak setup as the primary method
+- Kept GitLab OAuth instructions as an alternative
+- Added link to dedicated Keycloak setup guide
+
+### 4. `KEYCLOAK_SETUP.md` (New)
+
+- Comprehensive setup guide for Keycloak
+- Step-by-step configuration instructions
+- Troubleshooting section
+- Production deployment considerations
+
+## Environment Variables
+
+### New Required Variables
+
+```bash
+# Keycloak admin credentials
+KEYCLOAK_ADMIN=admin
+KEYCLOAK_ADMIN_PASSWORD=changeme
+
+# Keycloak realm and client
+KEYCLOAK_REALM=dtaas
+KEYCLOAK_CLIENT_ID=dtaas-workspace
+KEYCLOAK_CLIENT_SECRET=<from-keycloak>
+KEYCLOAK_ISSUER_URL=http://keycloak:8080/auth/realms/dtaas
+```
+
+### Deprecated Variables (GitLab OAuth)
+
+These are no longer used by default but remain for backward compatibility:
+
+```bash
+OAUTH_URL=https://gitlab.com
+OAUTH_CLIENT_ID=...
+OAUTH_CLIENT_SECRET=...
+```
+
+### Shared Variables
+
+```bash
+OAUTH_SECRET=...  # Still used for session encryption
+SERVER_DNS=foo.com
+USERNAME1=user1
+USERNAME2=user2
+```
+
+## Migration Path
+
+### Option 1: Use Embedded Keycloak (Default)
+
+1. Pull the latest changes
+2. Update your `.env` file with Keycloak variables
+3. Follow [KEYCLOAK_SETUP.md](KEYCLOAK_SETUP.md)
+4. Restart services
+
+### Option 2: Use External Keycloak
+
+1. Set up Keycloak externally
+2. Update `KEYCLOAK_ISSUER_URL` to point to external Keycloak
+3. Remove `keycloak` service from compose file (optional)
+4. Configure client in external Keycloak
+5. Update `.env` with credentials
+6. Restart services
+
+### Option 3: Continue Using GitLab OAuth
+
+1. Modify `traefik-forward-auth` service in compose file:
+   ```yaml
+   environment:
+     - DEFAULT_PROVIDER=generic-oauth
+     - PROVIDERS_GENERIC_OAUTH_AUTH_URL=${OAUTH_URL}/oauth/authorize
+     - PROVIDERS_GENERIC_OAUTH_TOKEN_URL=${OAUTH_URL}/oauth/token
+     - PROVIDERS_GENERIC_OAUTH_USER_URL=${OAUTH_URL}/api/v4/user
+     - PROVIDERS_GENERIC_OAUTH_CLIENT_ID=${OAUTH_CLIENT_ID}
+     - PROVIDERS_GENERIC_OAUTH_CLIENT_SECRET=${OAUTH_CLIENT_SECRET}
+     - PROVIDERS_GENERIC_OAUTH_SCOPE=read_user
+   ```
+2. Remove `keycloak` service from compose file
+3. Keep your existing `.env` configuration
+
+## Benefits of This Design
+
+### Minimal Changes for External Keycloak
+
+The configuration uses environment variables that make it easy to switch from embedded to external Keycloak:
+
+```bash
+# Internal (default)
+KEYCLOAK_ISSUER_URL=http://keycloak:8080/auth/realms/dtaas
+
+# External (just change the URL)
+KEYCLOAK_ISSUER_URL=https://keycloak.company.com/auth/realms/dtaas
+```
+
+No compose file changes needed!
+
+### Standard OIDC Implementation
+
+Using standard OIDC means:
+- Compatible with any OIDC provider (not just Keycloak)
+- Could switch to Okta, Auth0, Azure AD, etc. with just env var changes
+- Following security best practices
+- Better token management and refresh
+
+### Container Isolation
+
+- Keycloak runs in its own container
+- Can be removed/replaced without affecting other services
+- Data persisted in Docker volume
+- Easy to backup and restore
+
+## Testing the Setup
+
+After deploying the changes:
+
+1. **Check services are running:**
+   ```bash
+   docker compose -f compose.traefik.secure.yml ps
+   ```
+
+2. **Verify Keycloak is accessible:**
+   ```bash
+   curl -I http://foo.com/auth
+   # Should return 200 OK
+   ```
+
+3. **Test authentication flow:**
+   - Navigate to `http://foo.com/`
+   - Should redirect to Keycloak login
+   - Login with created user
+   - Should redirect back to application
+
+4. **Check logs if issues occur:**
+   ```bash
+   docker compose -f compose.traefik.secure.yml logs keycloak
+   docker compose -f compose.traefik.secure.yml logs traefik-forward-auth
+   ```
+
+## Production Considerations
+
+Before deploying to production:
+
+1. ✅ Use HTTPS (switch to `compose.traefik.secure.tls.yml`)
+2. ✅ Change default Keycloak admin password
+3. ✅ Use external Keycloak instance
+4. ✅ Configure Keycloak with proper database (PostgreSQL/MySQL)
+5. ✅ Set up proper backup strategy for Keycloak data
+6. ✅ Configure Keycloak realm with appropriate security policies
+7. ✅ Set `INSECURE_COOKIE=false` in traefik-forward-auth
+8. ✅ Use strong client secrets
+9. ✅ Enable MFA for users
+10. ✅ Regular security audits
+
+## References
+
+- [KEYCLOAK_SETUP.md](KEYCLOAK_SETUP.md) - Detailed setup instructions
+- [CONFIGURATION.md](CONFIGURATION.md) - General configuration guide
+- [Keycloak Documentation](https://www.keycloak.org/documentation)
+- [Traefik Forward Auth](https://github.com/thomseddon/traefik-forward-auth)
+- [OIDC Specification](https://openid.net/specs/openid-connect-core-1_0.html)
diff --git a/KEYCLOAK_QUICKREF.md b/KEYCLOAK_QUICKREF.md
@@ -0,0 +1,128 @@
+# Keycloak Integration - Quick Reference
+
+## Summary of Changes
+
+The `compose.traefik.secure.tls.yml` has been updated to use **Keycloak** for authentication instead of GitLab OAuth.
+
+## What's New
+
+### 1. New Keycloak Service
+- **Image**: `quay.io/keycloak/keycloak:26.0.7`
+- **Access**: `https://foo.com/auth`
+- **Purpose**: OIDC-based identity provider
+- **Storage**: Persistent volume `keycloak-data`
+
+### 2. Updated Authentication Flow
+```
+User → Traefik → Forward Auth → Keycloak (OIDC) → Protected Service
+```
+
+### 3. New Environment Variables
+| Variable | Purpose | Example |
+|----------|---------|---------|
+| `KEYCLOAK_ADMIN` | Admin username | `admin` |
+| `KEYCLOAK_ADMIN_PASSWORD` | Admin password | `changeme` |
+| `KEYCLOAK_REALM` | Realm name | `dtaas` |
+| `KEYCLOAK_CLIENT_ID` | OIDC client ID | `dtaas-workspace` |
+| `KEYCLOAK_CLIENT_SECRET` | OIDC client secret | `<from-keycloak>` |
+| `KEYCLOAK_ISSUER_URL` | OIDC issuer URL | `https://foo.com/auth/realms/dtaas` |
+
+## Quick Setup
+
+### Step 1: Configure Environment
+```bash
+cp dtaas/.env.example dtaas/.env
+# Edit dtaas/.env with Keycloak credentials
+```
+
+### Step 2: Start Services
+```bash
+docker compose -f compose.traefik.secure.tls.yml build
+docker compose -f compose.traefik.secure.tls.yml --env-file dtaas/.env up -d
+```
+
+### Step 3: Setup Keycloak (First Time Only)
+1. Go to `https://foo.com/auth`
+2. Login with admin credentials
+3. Create realm: `dtaas`
+4. Create client: `dtaas-workspace` (OIDC, confidential)
+5. Set redirect URIs: `https://foo.com/_oauth/*`
+6. Copy client secret to `.env`
+7. Create users in Keycloak
+8. Restart services
+
+### Step 4: Test
+Navigate to `https://foo.com/` and login with Keycloak user.
+
+## Key Benefits
+
+✅ **Standards-Based**: Uses OIDC/OAuth2 standards
+✅ **Flexible**: Easy to switch to external Keycloak
+✅ **Enterprise-Ready**: Supports SSO, MFA, user federation
+✅ **Minimal Changes**: Environment-variable based configuration
+✅ **Backward Compatible**: Can still use GitLab OAuth
+
+## Migration Paths
+
+### Use External Keycloak
+Just change `KEYCLOAK_ISSUER_URL` in `.env`:
+```bash
+KEYCLOAK_ISSUER_URL=https://foo.com/auth/realms/dtaas
+```
+
+### Revert to GitLab OAuth
+Modify `traefik-forward-auth` in compose file:
+```yaml
+environment:
+  - DEFAULT_PROVIDER=generic-oauth
+  - PROVIDERS_GENERIC_OAUTH_AUTH_URL=${OAUTH_URL}/oauth/authorize
+  - PROVIDERS_GENERIC_OAUTH_TOKEN_URL=${OAUTH_URL}/oauth/token
+  - PROVIDERS_GENERIC_OAUTH_USER_URL=${OAUTH_URL}/api/v4/user
+  - PROVIDERS_GENERIC_OAUTH_CLIENT_ID=${OAUTH_CLIENT_ID}
+  - PROVIDERS_GENERIC_OAUTH_CLIENT_SECRET=${OAUTH_CLIENT_SECRET}
+```
+
+## Documentation
+
+- 📖 [KEYCLOAK_SETUP.md](KEYCLOAK_SETUP.md) - Complete setup guide
+- 🔄 [KEYCLOAK_MIGRATION.md](KEYCLOAK_MIGRATION.md) - Migration details
+- ⚙️ [CONFIGURATION.md](CONFIGURATION.md) - Configuration reference
+- 🔐 [TRAEFIK_SECURE.md](TRAEFIK_SECURE.md) - Traefik with auth
+
+## Troubleshooting
+
+### Cannot access Keycloak
+```bash
+docker compose -f compose.traefik.secure.tls.yml logs keycloak
+```
+
+### Authentication issues
+```bash
+docker compose -f compose.traefik.secure.tls.yml logs traefik-forward-auth
+```
+
+### Check all services
+```bash
+docker compose -f compose.traefik.secure.tls.yml ps
+```
+
+## Production Checklist
+
+- [ ] Use HTTPS (compose.traefik.secure.tls.yml)
+- [ ] Change Keycloak admin password
+- [ ] Use external Keycloak instance
+- [ ] Configure Keycloak with proper database
+- [ ] Set `INSECURE_COOKIE=false`
+- [ ] Use strong client secrets
+- [ ] Enable MFA for users
+- [ ] Regular backups of keycloak-data volume
+- [ ] Set log level to INFO or WARN
+- [ ] Review security policies
+
+## Support
+
+For issues or questions:
+1. Check documentation links above
+2. Review logs as shown in troubleshooting
+3. Verify environment variables in `.env`
+4. Check Keycloak client configuration