Skip to content

Keycloak Configuration

Keycloak runs as shared infrastructure in its own standalone repository (Keycloak repo), separate from the Recron AppHost. This guide documents the realm configuration used by Recron.

Table of Contents

  1. Creating a Realm
  2. Basic Settings
  3. Creating the Scalar Client (API Documentation)
  4. Creating the Frontend Client (Web Application)
  5. LinkedIn Identity Provider (Social Login)
  6. Theme Configuration
  7. Import/Export Configuration

1. Creating a Realm

Step 1: Access the Admin Console

  1. Navigate to https://auth.bluebraces.online/admin
  2. Log in as administrator

Step 2: Create a New Realm

  1. Click the dropdown in the top-left corner (defaults to "master")
  2. Click "Create Realm"
  3. Fill in the details:
  4. Realm name: recron
  5. Display name: Recron
  6. Enabled: ✅ ON
  7. Click "Create"

2. Basic Settings

Realm Settings → Login

  1. Go to Realm settings in the left menu
  2. Switch to the Login tab
  3. Enable the following options:
  4. ✅ User registration
  5. ✅ Forgot password
  6. ✅ Remember me
  7. ✅ Login with email
  8. Click Save

3. Creating the Scalar Client

The Scalar client is used for API documentation (Scalar API Reference) and uses the Client Credentials Flow.

Step 1: Create the Client

  1. Go to Clients in the left menu
  2. Click "Create client"

Step 2: General Settings

  1. Client type: OpenID Connect
  2. Client ID: scalar
  3. Click Next

Step 3: Capability Config

  1. Client authentication: ✅ ON (confidential client)
  2. Authorization: ✅ ON
  3. Authentication flow:
  4. ❌ Standard flow (disable)
  5. ❌ Implicit flow (disable)
  6. ❌ Direct access grants (disable)
  7. ✅ Service accounts roles (enable)
  8. PKCE Code Challenge Method: S256
  9. Click Next

Step 4: Retrieve the Client Secret

  1. After saving, go to the Credentials tab
  2. Copy the Client Secret (needed for configuration)
  3. Save it in Recron.AppHost/appsettings.Development.json:
{
  "Parameters": {
    "username": "your-username",
    "password": "your-password",
    "scalar-client-id": "scalar",
    "scalar-client-secret": "<copied-secret>"
  }
}

4. Creating the Frontend Client

The Frontend client is used by the frontend application (SolidJS SPA) and uses the Authorization Code Flow with PKCE.

Step 1: Create the Client

  1. Go to Clients in the left menu
  2. Click "Create client"

Step 2: General Settings

  1. Client type: OpenID Connect
  2. Client ID: frontend
  3. Click Next

Step 3: Capability Config

  1. Client authentication: ❌ OFF (public client)
  2. Authorization: ❌ OFF
  3. Authentication flow:
  4. ✅ Standard flow (enable)
  5. ❌ Implicit flow (disable)
  6. ❌ Direct access grants (disable)
  7. ❌ Service accounts roles (disable)
  8. PKCE Code Challenge Method: S256 (requires PKCE)
  9. Click Next

Step 4: Login Settings

  1. Root URL: http://localhost:5173 (or your application URL)
  2. Home URL: http://localhost:5173
  3. Valid redirect URIs:
  4. http://localhost:5173/*
  5. In production, also add: https://your-domain.com/*
  6. Valid post logout redirect URIs:
  7. http://localhost:5173/*
  8. In production, also add: https://your-domain.com/*
  9. Web origins:
  10. http://localhost:5173
  11. + (automatically adds all valid redirect URIs)
  12. In production, also add: https://your-domain.com
  13. Click Save

Step 5: Application Configuration

The frontend application reads Keycloak configuration from environment variables (recron-web/.env):

VITE_AUTH_ISSUER=https://auth.bluebraces.online/realms/recron
VITE_AUTH_CLIENT_ID=frontend
VITE_AUTH_URL=http://localhost:5173
VITE_API_BASE_URL=http://localhost:5000

5. LinkedIn Identity Provider (Social Login)

LinkedIn allows users to sign in with their LinkedIn account using OpenID Connect.

Prerequisites

  • LinkedIn Company Page — required to create an app. This must be a Company Page, not a personal profile. If you don't have one, click "Create a new LinkedIn Page" in the app creation form or create one at linkedin.com/company/setup.
  • Privacy policy URL — must be a valid URL starting with https://. The app includes a privacy policy page at /privacy (e.g., https://app.bluebraces.online/privacy).
  • App logo — square image, at least 100x100px.

Step 1: Register an Application on LinkedIn

  1. Go to LinkedIn Developer Portal
  2. Click "Create app"
  3. Fill in the form:
Field Value
App name Recron
LinkedIn Page Search for your company name or paste the URL
Privacy policy URL https://app.bluebraces.online/privacy
App logo Upload a square logo (min. 100x100px)
Legal agreement Check "I have read and agree to these terms"
  1. Click "Create app"

Step 2: Add the "Sign In with LinkedIn" Product

  1. In your LinkedIn app, go to the Products tab
  2. Find "Sign In with LinkedIn using OpenID Connect"
  3. Click "Request access" and accept the terms
  4. Wait for approval (usually instant)

Step 3: Configure OAuth 2.0 Settings

  1. Go to the Auth tab in your LinkedIn app
  2. Under OAuth 2.0 settings → Authorized redirect URLs for your app, click "Add redirect URL" and add:
  3. https://auth.bluebraces.online/realms/recron/broker/linkedin-openid-connect/endpoint
  4. Copy the Client ID and Primary Client Secret from the top of the Auth tab

Step 4: Configure LinkedIn IdP in Keycloak

  1. Go to Keycloak Admin Console (https://auth.bluebraces.online/admin)
  2. Select the recron realm
  3. Go to Identity Providers in the left menu
  4. Click "Add provider" → "LinkedIn OpenID Connect"
  5. Fill in:
  6. Alias: linkedin-openid-connect (must match this exactly for the theme icon)
  7. Display Name: LinkedIn
  8. Client ID: paste from LinkedIn Developer Portal
  9. Client Secret: paste from LinkedIn Developer Portal
  10. Default Scopes: openid profile email
  11. Sync Mode: Import
  12. Click "Save"

Step 5: Configure Attribute Mappers (Optional)

After saving the IdP, go to the Mappers tab and add:

Name Mapper Type Claim User Attribute
LinkedIn First Name Attribute Importer given_name firstName
LinkedIn Last Name Attribute Importer family_name lastName
LinkedIn Email Attribute Importer email email
LinkedIn Profile Picture Attribute Importer picture picture

Step 6: Verification

  1. Navigate to https://auth.bluebraces.online/realms/recron/account
  2. You should see a LinkedIn button on the login page (with the LinkedIn icon from the Keywind theme)
  3. Click it to test the sign-in flow

Available Data from LinkedIn

LinkedIn's OpenID Connect provides the following data:

Field Example
sub 782bbtaQ
name John Doe
given_name John
family_name Doe
picture Profile picture URL
email doe@email.com
email_verified true
locale en-US

Note: Extended profile data (job title, company, work history, skills) requires separate LinkedIn API access that must be approved by LinkedIn. The self-serve "Sign In with LinkedIn" product only provides the basic data listed above.

6. Theme Configuration

Step 1: Theme Installation

The Keywind theme is located in the Keycloak repo at themes/keywind/. It is bind-mounted into the Keycloak container via the Keycloak repo's docker-compose.yml.

Step 2: Set the Theme in Realm

  1. Go to Realm settings
  2. Switch to the Themes tab
  3. Set:
  4. Login theme: keywind
  5. Account theme: keywind
  6. Email theme: keywind
  7. Admin Console theme: leave default
  8. Click Save

Step 3: Customize Colors

To change the theme colors, edit the file in the Keycloak repo:

themes/keywind/login/document.ftl

Find the <style> section at the end of the file (before </#macro>) and modify the colors as needed.

Reloading changes:

After saving changes to document.ftl:

  1. Restart the Keycloak container (docker compose restart in the Keycloak repo)
  2. Wait for the container to start
  3. Clear browser cache (Ctrl+Shift+Delete)
  4. Open the login page in incognito mode: https://auth.bluebraces.online/realms/recron/account

Step 4: Verification

  1. Log out of the Admin Console
  2. Navigate to: https://auth.bluebraces.online/realms/recron/account
  3. You should see the new Keywind theme

7. Import/Export Configuration

Exporting the Realm Configuration

  1. Go to Realm settings
  2. Click the Action tab → Partial export
  3. Select what to export:
  4. ✅ Export groups and roles
  5. ✅ Export clients
  6. Click Export

Via Keycloak repo (automatic on startup):

The realm configuration file is located in the Keycloak repo at:

realms/realm-export.json

The Keycloak docker-compose.yml mounts this directory to /opt/keycloak/data/import and starts Keycloak with --import-realm, which imports the realm on first startup.

Local development: Start Keycloak from the Keycloak repo (docker compose up -d). The realm is auto-imported on first startup. Then start Recron's AppHost, which connects to Keycloak via the keycloak-authority parameter (default: https://auth.bluebraces.online).

Production: Keycloak runs from its own docker-compose.yml on the VPS at /opt/keycloak/. The realm is imported on first startup. On subsequent restarts, realm data persists in the Keycloak data volume.

Importing the Realm Configuration

Option 1: Via Admin Console

  1. Go to the dropdown in the top-left corner
  2. Click "Create Realm"
  3. Click "Browse" and select the realm-export.json file
  4. Click "Create"

Option 2: Via Keycloak repo (local development)

Start Keycloak from the Keycloak repo with docker compose up -d. The realm is automatically imported from realms/realm-export.json on first startup.

Updating an Existing Realm

⚠️ Warning: Importing may overwrite the existing configuration!

  1. Back up the current configuration (export the realm)
  2. Stop the Keycloak container (docker compose down in the Keycloak repo)
  3. Update the realms/realm-export.json file in the Keycloak repo
  4. Restart the Keycloak container (docker compose up -d)

Key Settings Summary

Realm: recron

  • ✅ User registration: enabled
  • ✅ Forgot password: enabled
  • ✅ Remember me: enabled
  • ✅ Login with email: enabled
  • 🔐 SSL required: external
  • 🎨 Theme: keywind

Client: scalar (API Documentation)

  • Type: Confidential
  • Flow: Client Credentials (Service Account)
  • Authentication: ON
  • Authorization: ON
  • Redirect URIs: /*

Client: frontend (Web App)

  • Type: Public
  • Flow: Authorization Code + PKCE
  • Authentication: OFF
  • PKCE: S256 (required)
  • Redirect URIs: http://localhost:5173/*
  • Web origins: http://localhost:5173
  • Admin Console: https://auth.bluebraces.online/admin
  • Realm Account: https://auth.bluebraces.online/realms/recron/account
  • OpenID Configuration: https://auth.bluebraces.online/realms/recron/.well-known/openid-configuration
  • Token Endpoint: https://auth.bluebraces.online/realms/recron/protocol/openid-connect/token

Troubleshooting

Problem: Theme Not Loading

  1. Check that the themes/keywind/login folder exists in the Keycloak repo
  2. Restart the Keycloak container (docker compose restart)
  3. Check the Keycloak container logs (docker compose logs keycloak)

Problem: Client Secret Not Working

  1. Make sure you copied the entire secret
  2. Verify the client has "Client authentication" enabled
  3. Regenerate the secret in the "Credentials" tab

Problem: CORS Errors in Frontend

  1. Check "Web origins" in the frontend client
  2. Make sure http://localhost:5173 or + is listed
  3. Restart the frontend application

Problem: Redirect URI Mismatch

  1. Check "Valid redirect URIs" in the client
  2. Must contain the exact application URL + /*
  3. Example: http://localhost:5173/*

Additional Resources