Keycloak Setup Guide for DTaaS

This guide explains how to configure Keycloak for authentication in the DTaaS workspace deployment.

Key Benefits

✅ Standards-Based: Uses OIDC/OAuth2 standards

✅ Enterprise-Ready: Supports SSO, MFA, user federation

✅ Minimal Changes: Environment-variable based configuration

Overview

The configuration uses:

• Keycloak as the identity provider (IdP) with OIDC support
• Traefik Forward Auth to protect routes using OIDC
• Traefik as the reverse proxy

Architecture

User Request → Traefik → Forward Auth → Keycloak (OIDC)
               ↓
         Protected Service

Quick Start

In this guide, either <DOMAIN_NAME> OR intocps.org are used as placeholders for server hostname of the installation.

1. Configure Environment Variables

Keycloak-specific environment variables are:

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://intocps.org/auth/realms/dtaas

Edit Keycloak-configuration in .env:

# Keycloak Admin Credentials (for initial setup)
KEYCLOAK_ADMIN=admin
KEYCLOAK_ADMIN_PASSWORD=changeme

# Keycloak Realm
KEYCLOAK_REALM=dtaas

# Keycloak Client Configuration (will be created in post-install step)
KEYCLOAK_CLIENT_ID=dtaas-workspace
KEYCLOAK_CLIENT_SECRET=<generated-secret>

2. Configure Keycloak

The following instructions are part of post-install step.

Access Keycloak Admin Console

1. Navigate to https://intocps.org/auth
2. Click Administration Console
3. Login with credentials from the .env file (default: admin / changeme)

Create a Realm

1. In the top-left dropdown (currently showing "Master"), click Create Realm
2. Realm name: dtaas (or match the KEYCLOAK_REALM in .env)
3. Click Create
4. Click on Realm Settings -> User Profile
5. Click on Create attribute with
6. name: profile
7. display name: profile
8. Permission: who can edit ✅ on admin
9. Click Create

Create Users

1. In the left sidebar, click Users
2. Click Create new user
3. Fill in user details:
4. Username: user1 (or desired username)
5. Email: user's email
6. First name / Last name: required
7. Email verified: OFF
8. Profile: https://intocps.org/auth/realms/dtaas/<USERNAME> The profile URL is created by adding /<USERNAME> to the <REACT_APP_AUTH_AUTHORITY> URL used in the client.js
9. Click Create
10. Set password:
11. Go to the Credentials tab
12. Click Set password
13. Enter a password
14. Temporary: OFF (so users do not have to change it on first login)
15. Click Save
16. Repeat for additional users (e.g., user2)

Create OAuth2 Client for Traefik Forward-Auth Service

1. In the left sidebar, click Clients
2. Click Create client
3. Configure the client:
4. Client type: OpenID Connect
5. Client ID: dtaas-workspace (match KEYCLOAK_CLIENT_ID in .env)
6. Click Next
7. Capability config:
8. Client authentication: ON
9. Authorization: OFF
10. Authentication flow: enable Standard flow
11. Click Next
12. Login settings:
13. Root URL: https://intocps.org
14. Valid redirect URIs:
    • https://intocps.org/_oauth/*
    • https://intocps.org/*
15. Valid post logout redirect URIs: https://intocps.org/*
16. Web origins: https://intocps.org
17. Click Save
18. Get the client secret:
19. Go to the Credentials tab
20. Copy the Client secret value
21. Update KEYCLOAK_CLIENT_SECRET in the .env file

Create OAuth2 Client for DTaaS Client Service

The DTaaS web client is a React single-page application (SPA) that uses the Authorization Code flow with PKCE (Proof Key for Code Exchange). This requires a public client (no client secret) with PKCE enforced.

1. In the left sidebar, click Clients
2. Click Create client
3. Configure the client:
4. Client type: OpenID Connect
5. Client ID: dtaas-client
6. Click Next
7. Capability config:
8. Client authentication: OFF (public client — no secret needed)
9. Authorization: OFF
10. Authentication flow: enable Standard flow only
11. Click Next
12. Login settings:
13. Root URL: https://intocps.org
14. Valid redirect URIs: https://intocps.org/*
15. Valid post logout redirect URIs: https://intocps.org/*
16. Web origins: https://intocps.org
17. Click Save
18. Enforce PKCE:
19. Go to the Advanced tab of the client
20. Under Advanced Settings, set Proof Key for Code Exchange Code Challenge Method to S256
21. Click Save
22. Verify scopes:
23. Go to the Client Scopes tab of the client
24. Confirm that profile is listed as an assigned scope

3. Restart Services

After configuring Keycloak, restart the services to apply the new client secret:

docker compose down
docker compose up -d

4. Test Authentication

1. Navigate to https://intocps.org
2. The browser should redirect to the Keycloak login page
3. Log in with one of the created users
4. The browser should redirect back to the DTaaS landing page

Production Considerations

To use an external Keycloak instance (recommended for production):

1. Update KEYCLOAK_ISSUER_URL in .env:

KEYCLOAK_ISSUER_URL=https://keycloak.intocps.org/auth/realms/dtaas

Update client redirect URIs in Keycloak to use the production domain

1. Secure Credentials

• Change the default Keycloak admin password
• Use strong client secrets
• Store secrets securely (Docker secrets or external secret managers)
• Rotate secrets regularly

2. Database Backend

For production, configure Keycloak with a proper database (PostgreSQL, MySQL):

keycloak:
  environment:
   - KC_DB=postgres
   - KC_DB_URL=jdbc:postgresql://postgres:5432/keycloak
   - KC_DB_USERNAME=keycloak
   - KC_DB_PASSWORD=secure_password

Troubleshooting

Cannot Access Keycloak Admin Console

• Ensure the Keycloak service is running: docker compose ps
• Check Keycloak logs: docker compose logs keycloak
• Verify port 80/443 is accessible

Authentication Loop/Redirect Issues

• Verify KEYCLOAK_ISSUER_URL matches the realm name
• Ensure redirect URIs in the Keycloak client include /_oauth/*
• Confirm COOKIE_DOMAIN matches the domain
• Clear browser cookies and retry

"Invalid Client" Error

• Verify KEYCLOAK_CLIENT_ID matches the client ID in Keycloak
• Ensure KEYCLOAK_CLIENT_SECRET is correct
• Confirm client authentication is enabled for the client

Forward Auth Not Working

• Check traefik-forward-auth logs: docker compose logs traefik-forward-auth
• Verify environment variables are set correctly
• Ensure Keycloak is reachable from the traefik-forward-auth container

Advanced Configuration

Custom Claims and Scopes

To access custom user attributes:

1. In Keycloak, create client scopes with mappers
2. Assign scopes to the client
3. Configure traefik-forward-auth to request additional scopes

Role-Based Access Control (RBAC)

RBAC is supported in Keycloak but not implemented in the traefik-forward-auth service by default.

Single Sign-On (SSO)

Keycloak supports SSO across multiple applications. Configure additional clients for other services as needed.

References

• Keycloak Documentation
• Traefik Forward Auth
• OIDC Specification