Keycloak Setup Guide for DTaaS

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

Overview

Keycloak uses the OIDC/OAuth2 standards and supports single sign-on, multi-factor authentication and user federation. The deployment is configured through environment variables.

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

This guide uses either <DOMAIN_NAME> or intocps.org as a placeholder for the server hostname of the installation.

1. Configure Environment Variables

The 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

KEYCLOAK_REALM is informational: docker-compose.yml does not use it. The realm that DTaaS uses is the one named at the end of KEYCLOAK_ISSUER_URL (/realms/<realm>).

Edit the Keycloak configuration in config/.env:

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

# Keycloak Realm (informational; the realm in KEYCLOAK_ISSUER_URL is used)
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 the post-install step.

Access Keycloak Admin Console

1. Go to https://intocps.org/auth
2. Click Administration Console
3. Log in with the credentials from the config/.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 realm named in KEYCLOAK_ISSUER_URL in config/.env)
3. Click Create
4. Click Realm Settings -> User Profile
5. Click Create attribute with
6. name: profile
7. display name: profile
8. Permission: who can edit selected on admin
9. Click Create

Create Users

1. In the left sidebar, click Users
2. Click Create new user
3. Fill in the user details:
4. Username: user1 (or the desired username)
5. Email: the 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 the <REACT_APP_AUTH_AUTHORITY> URL from client.js with /<USERNAME> appended
9. Click Create
10. Set a 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 config/.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 config/.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). It needs 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 --env-file config/.env down
docker compose --env-file config/.env up -d

4. Test Authentication

1. Go 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 config/.env:

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

1. Update the client redirect URIs in Keycloak to use the production domain.

Secure Credentials

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

Database Backend

For production, configure Keycloak with a database such as PostgreSQL or 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 that the Keycloak service is running: docker compose --env-file config/.env ps
• Check the Keycloak logs: docker compose --env-file config/.env logs keycloak
• Verify that ports 80 and 443 are reachable

Authentication Loop/Redirect Issues

• Verify that KEYCLOAK_ISSUER_URL contains the correct realm name
• Ensure that the redirect URIs in the Keycloak client include /_oauth/*
• Confirm that SERVER_DNS is correct (COOKIE_DOMAIN is derived from it)
• Clear the browser cookies and retry

"Invalid Client" Error

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

Forward Auth Not Working

• Check the traefik-forward-auth logs: docker compose --env-file config/.env logs traefik-forward-auth
• Verify that the environment variables are set correctly
• Ensure that 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 the scopes to the client
3. Configure traefik-forward-auth to request the additional scopes

Role-Based Access Control (RBAC)

Keycloak supports RBAC, but the traefik-forward-auth service does not use it 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