@cdmbase/wiki-browser 12.0.18-alpha.10

package/lib/templates/content/docs/adminide-modules/project-tools/keycloak-guide.md

@@ -0,0 +1,543 @@
+# Keycloak Dashboard Setup Guide
+
+This comprehensive guide covers how to configure different types of clients in the Keycloak Admin Console dashboard. We'll cover three main authentication flows:
+
+1. **Client Credentials Flow** - For machine-to-machine authentication
+2. **Implicit Flow** - For single-page applications (SPAs)
+3. **Standard Flow (Authorization Code) with Credentials** - For traditional web applications with PKCE support
+
+---
+
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [1. Client Credentials Flow Setup](#1-client-credentials-flow-setup)
+- [2. Implicit Flow Setup](#2-implicit-flow-setup)
+- [3. Standard Flow with Credentials Setup](#3-standard-flow-with-credentials-setup)
+- [Troubleshooting](#troubleshooting)
+- [Best Practices](#best-practices)
+
+---
+
+## Prerequisites
+
+Before starting, ensure you have:
+
+- Access to Keycloak Admin Console
+- Admin privileges for the realm you're working with
+- Basic understanding of OAuth 2.0 flows
+- Knowledge of your application's redirect URIs and web origins
+
+**Accessing Keycloak Admin Console:**
+
+1. Navigate to your Keycloak instance URL (e.g., `https://keycloak.yourdomain.com`)
+2. Click **Administration Console**
+3. Log in with admin credentials
+4. Select your realm from the dropdown (top-left corner)
+
+---
+
+## 1. Client Credentials Flow Setup
+
+The Client Credentials flow is used for **machine-to-machine (M2M) authentication** where there's no user involved. This is ideal for:
+
+- Service-to-service communication
+- Backend API authentication
+- Automated processes
+
+### Step 1: Create a New Client
+
+1. In the Keycloak Admin Console, navigate to:
+    - **Clients** → Click **Create client** (or **Add client**)
+
+2. **Client Settings:**
+    - **Client type:** Select **OpenID Connect**
+    - **Client ID:** Enter a unique identifier (e.g., `my-service-client`)
+    - Click **Next**
+
+### Step 2: Configure Capability Config
+
+1. **Capability config** screen:
+    - ✅ **Client authentication:** **ON** (Required for client credentials)
+    - ✅ **Service accounts roles:** **ON** (Enables service account)
+    - ❌ **Authorization:** OFF (unless you need fine-grained authorization)
+    - ❌ **Standard flow:** OFF (not needed for client credentials)
+    - ❌ **Direct access grants:** OFF (optional, enables password grant)
+    - ❌ **Implicit flow:** OFF
+    - Click **Next**
+
+### Step 3: Configure Login Settings
+
+1. **Login settings:**
+    - **Root URL:** Leave empty or enter your service base URL
+    - **Home URL:** Leave empty
+    - **Valid redirect URIs:** Leave empty (not used in client credentials flow)
+    - **Web origins:** Leave empty or add `*` for development
+    - Click **Save**
+
+### Step 4: Enable Service Account Roles
+
+1. After saving, you'll be on the **Client details** page
+2. Navigate to the **Service account roles** tab
+3. Click **Assign role**
+4. You'll see two options:
+    - **Filter by clients** - Assign roles from other clients
+    - **Filter by realm** - Assign realm-level roles
+
+#### Assign Realm Management Roles (Common Use Case)
+
+1. Click **Filter by realm**
+2. In the search box, type `realm-management` or browse available roles
+3. Select the roles you need:
+    - **realm-admin** - Full realm administration
+    - **manage-users** - User management
+    - **manage-clients** - Client management
+    - **view-users** - Read-only user access
+    - **manage-realm** - Realm configuration management
+4. Click **Assign**
+
+#### Assign Client Roles
+
+1. Click **Filter by clients**
+2. Select the client you want to assign roles from
+3. Select the specific roles
+4. Click **Assign**
+
+### Step 5: Get Client Credentials
+
+1. Navigate to the **Credentials** tab
+2. You'll see:
+    - **Client secret:** Copy this value (you'll only see it once!)
+    - **Client ID:** Your client identifier
+3. **Important:** Save the client secret securely - you cannot retrieve it again
+
+### Step 6: Test Client Credentials Flow
+
+You can test the flow using curl:
+
+```bash
+curl -X POST "https://your-keycloak-domain.com/realms/your-realm/protocol/openid-connect/token" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "grant_type=client_credentials" \
+  -d "client_id=my-service-client" \
+  -d "client_secret=your-client-secret"
+```
+
+**Expected Response:**
+
+```json
+{
+    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
+    "expires_in": 300,
+    "token_type": "Bearer",
+    "scope": "profile email"
+}
+```
+
+### Step 7: Verify Service Account User
+
+1. Navigate to **Users** → Search for your client ID (e.g., `service-account-my-service-client`)
+2. Click on the service account user
+3. Go to **Role mapping** tab
+4. Verify that the assigned roles appear under **Assigned roles**
+
+### Configuration Summary for Client Credentials Flow
+
+| Setting                | Value                  |
+| ---------------------- | ---------------------- |
+| Client authentication  | ✅ ON                  |
+| Service accounts roles | ✅ ON                  |
+| Standard flow          | ❌ OFF                 |
+| Implicit flow          | ❌ OFF                 |
+| Direct access grants   | ❌ OFF (optional)      |
+| Public client          | ❌ OFF                 |
+| Authorization          | ❌ OFF (unless needed) |
+
+---
+
+## 2. Implicit Flow Setup
+
+The Implicit flow is designed for **single-page applications (SPAs)** and mobile apps where the client secret cannot be securely stored. This flow returns tokens directly to the browser.
+
+**⚠️ Security Note:** Implicit flow is considered less secure than Authorization Code flow with PKCE. Consider using Standard Flow with PKCE instead.
+
+### Step 1: Create a New Client
+
+1. Navigate to **Clients** → Click **Create client**
+2. **Client Settings:**
+    - **Client type:** Select **OpenID Connect**
+    - **Client ID:** Enter a unique identifier (e.g., `my-spa-client`)
+    - Click **Next**
+
+### Step 2: Configure Capability Config
+
+1. **Capability config** screen:
+    - ❌ **Client authentication:** **OFF** (Public client)
+    - ✅ **Implicit flow:** **ON**
+    - ❌ **Standard flow:** OFF (or ON if you want both)
+    - ❌ **Direct access grants:** OFF
+    - ❌ **Service accounts roles:** OFF
+    - Click **Next**
+
+### Step 3: Configure Login Settings
+
+1. **Login settings:**
+    - **Root URL:** Enter your application base URL (e.g., `https://myapp.com`)
+    - **Home URL:** Enter your application home page (e.g., `https://myapp.com/home`)
+    - **Valid redirect URIs:**
+        - Add your callback URLs (e.g., `https://myapp.com/callback`, `https://myapp.com/auth/callback`)
+        - For development: `http://localhost:3000/callback`
+        - Use wildcards carefully: `https://myapp.com/*`
+    - **Web origins:**
+        - Add allowed origins (e.g., `https://myapp.com`)
+        - For development: `http://localhost:3000`
+        - Use `*` only for development (not recommended for production)
+    - **Valid post logout redirect URIs:**
+        - Add logout redirect URLs (e.g., `https://myapp.com/logout`)
+    - Click **Save**
+
+### Step 4: Configure Advanced Settings
+
+1. After saving, go to the **Advanced** tab
+2. **Access Token Lifespan:** Set appropriate value (default: 5 minutes)
+3. **Implicit flow settings:**
+    - Ensure **Implicit flow** is enabled in the main settings
+4. **Fine Grain OpenID Connect Configuration:**
+    - **Access token:** ✅ Enabled
+    - **ID token:** ✅ Enabled (if you need user identity)
+
+### Step 5: Configure Protocol Mappers (Optional)
+
+1. Navigate to the **Client scopes** tab
+2. Click on **Dedicated scope** or **Default client scopes**
+3. You can add custom protocol mappers to include additional claims in tokens
+
+### Step 6: Test Implicit Flow
+
+You can test using a browser redirect:
+
+```
+https://your-keycloak-domain.com/realms/your-realm/protocol/openid-connect/auth?
+  client_id=my-spa-client
+  &redirect_uri=https://myapp.com/callback
+  &response_type=id_token token
+  &scope=openid profile email
+  &nonce=random-nonce-value
+  &state=random-state-value
+```
+
+## 3. Standard Flow with Credentials Setup
+
+The Standard Flow (Authorization Code) with credentials is the **recommended approach** for web applications. When combined with PKCE (Proof Key for Code Exchange), it provides the best security for both public and confidential clients.
+
+### Step 1: Create a New Client
+
+1. Navigate to **Clients** → Click **Create client**
+2. **Client Settings:**
+    - **Client type:** Select **OpenID Connect**
+    - **Client ID:** Enter a unique identifier (e.g., `my-web-app-client`)
+    - Click **Next**
+
+### Step 2: Configure Capability Config
+
+1. **Capability config** screen:
+    - ✅ **Client authentication:** **ON** (for confidential client with credentials)
+    - ✅ **Standard flow:** **ON** (Authorization Code flow)
+    - ✅ **Direct access grants:** **ON** (optional, enables username/password login)
+    - ❌ **Implicit flow:** OFF (not recommended)
+    - ❌ **Service accounts roles:** OFF (unless you need M2M)
+    - Click **Next**
+
+### Step 3: Configure Login Settings
+
+1. **Login settings:**
+    - **Root URL:** Enter your application base URL (e.g., `https://myapp.com`)
+    - **Home URL:** Enter your application home page (e.g., `https://myapp.com/home`)
+    - **Valid redirect URIs:**
+        - Add your callback URLs:
+            - `https://myapp.com/auth/callback`
+            - `https://myapp.com/callback`
+        - For development: `http://localhost:3000/auth/callback`
+        - **Important:** Must match exactly (including trailing slashes)
+    - **Web origins:**
+        - Add allowed origins:
+            - `https://myapp.com`
+            - For development: `http://localhost:3000`
+    - **Valid post logout redirect URIs:**
+        - Add logout redirect URLs:
+            - `https://myapp.com/logout`
+            - `https://myapp.com/`
+    - Click **Save**
+
+### Step 4: Get Client Credentials
+
+1. Navigate to the **Credentials** tab
+2. You'll see:
+    - **Client secret:** Copy this value immediately
+    - **Client ID:** Your client identifier
+    - **Client authenticator:** Should be `client-secret` (default)
+3. **Regenerate secret:** If needed, click **Regenerate secret** (old secret becomes invalid)
+
+### Step 5: Configure Advanced Settings
+
+1. Go to the **Advanced** tab
+2. **Access Token Lifespan:** Set appropriate value (default: 5 minutes)
+3. **PKCE Code Challenge Method:**
+    - Select **S256** (recommended) or **plain**
+    - **S256** uses SHA-256 hash (more secure)
+4. **Proof Key for Code Exchange Code Challenge Method:**
+    - Set to **S256** for PKCE support
+5. **Fine Grain OpenID Connect Configuration:**
+    - **Access token:** ✅ Enabled
+    - **ID token:** ✅ Enabled
+    - **Refresh token:** ✅ Enabled (for long-lived sessions)
+
+### Step 6: Configure Client Scopes (Optional)
+
+1. Navigate to the **Client scopes** tab
+2. **Default client scopes** are automatically assigned:
+    - `openid` - Required for OpenID Connect
+    - `profile` - User profile information
+    - `email` - User email
+    - `roles` - User roles
+3. **Optional scopes:**
+    - Click **Add client scope** to add custom scopes
+    - Configure protocol mappers for custom claims
+
+### Step 7: Enable Direct Access Grants (Optional)
+
+If you enabled **Direct access grants** in Step 2, you can also authenticate using username/password:
+
+```bash
+curl -X POST "https://your-keycloak-domain.com/realms/your-realm/protocol/openid-connect/token" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "grant_type=password" \
+  -d "client_id=my-web-app-client" \
+  -d "client_secret=your-client-secret" \
+  -d "username=user@example.com" \
+  -d "password=user-password" \
+  -d "scope=openid profile email"
+```
+
+**⚠️ Security Warning:** Direct access grants should only be used for trusted applications. Consider using Standard Flow with PKCE instead.
+
+### Configuration Summary for Standard Flow with Credentials
+
+| Setting                    | Value                 |
+| -------------------------- | --------------------- |
+| Client authentication      | ✅ ON                 |
+| Public client              | ❌ NO                 |
+| Standard flow              | ✅ ON                 |
+| Direct access grants       | ✅ ON (optional)      |
+| Implicit flow              | ❌ OFF                |
+| PKCE Code Challenge Method | ✅ S256 (recommended) |
+| Valid redirect URIs        | ✅ Required           |
+| Web origins                | ✅ Required           |
+| Client secret              | ✅ Required           |
+
+---
+
+## Troubleshooting
+
+### Common Issues and Solutions
+
+#### Issue 1: "Invalid redirect URI"
+
+**Symptoms:**
+
+- Error: `Invalid parameter: redirect_uri`
+- Authorization fails with redirect URI mismatch
+
+**Solutions:**
+
+1. Check that the redirect URI in your request **exactly matches** one in **Valid redirect URIs**
+2. Ensure no trailing slashes mismatch (e.g., `/callback` vs `/callback/`)
+3. Check protocol (http vs https)
+4. Verify port numbers match
+5. For development, ensure `http://localhost:3000` is added (not just `http://localhost`)
+
+#### Issue 2: "Client authentication failed"
+
+**Symptoms:**
+
+- Error: `Invalid client credentials`
+- Token exchange fails
+
+**Solutions:**
+
+1. Verify **Client authentication** is **ON** for confidential clients
+2. Check that **Client secret** is correct (copy-paste, no extra spaces)
+3. Ensure you're using the correct client ID
+4. Verify the client secret hasn't been regenerated
+5. For client credentials flow, ensure **Service accounts roles** is enabled
+
+#### Issue 3: "Service account not found"
+
+**Symptoms:**
+
+- Error when trying to use client credentials flow
+- Service account user doesn't exist
+
+**Solutions:**
+
+1. Ensure **Service accounts roles** is enabled in client settings
+2. Save the client configuration
+3. Navigate to **Users** and search for `service-account-{client-id}`
+4. If user doesn't exist, toggle **Service accounts roles** off and on again
+5. Assign roles to the service account user
+
+#### Issue 4: "CORS errors in browser"
+
+**Symptoms:**
+
+- Browser console shows CORS errors
+- Requests blocked by browser
+
+**Solutions:**
+
+1. Add your application origin to **Web origins** in client settings
+2. Ensure protocol matches (http vs https)
+3. Include port number if not standard (e.g., `http://localhost:3000`)
+4. For development, you can temporarily use `*` (not recommended for production)
+5. Check that **Root URL** is set correctly
+
+#### Issue 5: "PKCE code challenge mismatch"
+
+**Symptoms:**
+
+- Error: `Invalid code verifier`
+- Token exchange fails after authorization
+
+**Solutions:**
+
+1. Ensure **code_verifier** matches the one used to generate **code_challenge**
+2. Verify **code_challenge_method** is set correctly (S256 or plain)
+3. Check that code verifier hasn't been modified between requests
+4. Ensure PKCE settings are enabled in client **Advanced** tab
+
+#### Issue 6: "Access token expired too quickly"
+
+**Symptoms:**
+
+- Tokens expire before expected
+- Frequent re-authentication required
+
+**Solutions:**
+
+1. Go to client **Advanced** tab
+2. Increase **Access Token Lifespan** (default: 5 minutes)
+3. Consider implementing refresh token flow
+4. Ensure **Refresh token** is enabled in client scopes
+
+#### Issue 7: "Roles not appearing in token"
+
+**Symptoms:**
+
+- User has roles assigned but they don't appear in access token
+- Token claims missing role information
+
+**Solutions:**
+
+1. Navigate to **Client scopes** → **roles** scope
+2. Check **Mappers** tab
+3. Ensure **realm roles** and **client roles** mappers are configured
+4. Verify user has roles assigned in **Users** → **Role mapping**
+5. Check that **roles** scope is included in token request
+
+---
+
+## Best Practices
+
+### Security Best Practices
+
+1. **Use Standard Flow with PKCE** instead of Implicit flow when possible
+2. **Never expose client secrets** in client-side code
+3. **Use HTTPS** for all redirect URIs in production
+4. **Limit redirect URIs** - don't use wildcards in production
+5. **Rotate client secrets** regularly (every 90 days)
+6. **Use appropriate token lifespans** - balance security and user experience
+7. **Enable refresh tokens** for long-lived sessions
+8. **Implement proper token storage** - use httpOnly cookies or secure storage
+
+### Client Configuration Best Practices
+
+1. **Naming Convention:**
+    - Use descriptive client IDs (e.g., `myapp-web-client`, `myapp-mobile-client`)
+    - Include environment suffix (e.g., `myapp-web-dev`, `myapp-web-prod`)
+
+2. **Redirect URIs:**
+    - Be specific - avoid wildcards in production
+    - Include all environments (dev, staging, prod)
+    - Document each redirect URI's purpose
+
+3. **Scopes:**
+    - Request only necessary scopes
+    - Create custom scopes for fine-grained permissions
+    - Document scope usage
+
+4. **Service Account Roles:**
+    - Follow principle of least privilege
+    - Assign only necessary roles
+    - Document role assignments
+    - Review role assignments regularly
+
+5. **Token Configuration:**
+    - Set appropriate access token lifespan
+    - Enable refresh tokens for better UX
+    - Configure token claims via protocol mappers
+
+### Environment-Specific Configuration
+
+**Development:**
+
+- Use `http://localhost` redirect URIs
+- Shorter token lifespans for testing
+- More permissive CORS settings
+
+**Staging:**
+
+- Use staging-specific domains
+- Mirror production settings
+- Test all flows thoroughly
+
+**Production:**
+
+- Strict redirect URI validation
+- No wildcards in redirect URIs
+- Longer token lifespans with refresh tokens
+- Regular security audits
+
+### Monitoring and Maintenance
+
+1. **Regular Audits:**
+    - Review client configurations quarterly
+    - Check for unused clients
+    - Verify redirect URIs are still valid
+    - Review service account role assignments
+
+2. **Documentation:**
+    - Document each client's purpose
+    - Maintain a client registry
+    - Document redirect URIs and their purposes
+    - Keep track of client secret rotation dates
+
+3. **Testing:**
+    - Test authentication flows after configuration changes
+    - Verify token claims contain expected information
+    - Test error scenarios
+    - Validate CORS configuration
+
+---
+
+## Additional Resources
+
+### Keycloak Documentation
+
+- [Keycloak Server Administration Guide](https://www.keycloak.org/docs/latest/server_admin/)
+- [Keycloak Securing Apps Guide](https://www.keycloak.org/docs/latest/securing_apps/)
+- [OAuth 2.0 Flows](https://oauth.net/2/)
+
+### Related Documentation in This Project
+
+- See `docs/TROUBLESHOOTING_AUTH0_CLIENT_SECRET.md` for Auth0-specific troubleshooting
+- Check `packages-modules/user-auth0/server-core/src/auth/keycloak/` for implementation examples