Realm Configuration

This guide walks you through creating and configuring the secure-test realm in Keycloak for the Authentication Test API.

What is a Realm?

A realm in Keycloak is an isolated space that manages:

• Users and groups
• Roles and permissions
• Clients (applications)
• Authentication settings

Prerequisites

• Keycloak installed and running
• Access to Keycloak Admin Console
• Admin credentials

Step 1: Access Admin Console

1. Open browser: http://localhost:8080
2. Click "Administration Console"
3. Login with admin credentials

Step 2: Create Realm

Admin ConsoleREST API

1. Hover over "Master" in the top-left corner
2. Click "Create Realm"
3. Enter Realm Details:
   • Realm name: secure-test
   • Enabled: ✓ (checked)
4. Click "Create"

You should now see "secure-test" in the realm selector.

Create the realm via API:

# Get admin token
TOKEN=$(curl -X POST http://localhost:8080/realms/master/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin" \
  -d "password=admin" \
  -d "grant_type=password" \
  -d "client_id=admin-cli" \
  | jq -r '.access_token')

# Create realm
curl -X POST http://localhost:8080/admin/realms \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "realm": "secure-test",
    "enabled": true,
    "displayName": "Secure Test Realm",
    "displayNameHtml": "<b>Secure Test</b>"
  }'

Step 3: Configure Realm Settings

General Settings

1. Select "secure-test" realm from dropdown
2. Go to "Realm settings"
3. Configure General tab:
4. Display name: Secure Test Realm
5. HTML Display name: <b>Secure Test</b>
6. Frontend URL: Leave empty for development

7. Require SSL: none (development) or external requests (production)

8. Click "Save"

Login Settings

1. Go to "Realm settings" → "Login" tab
2. Configure:
3. User registration: ✗ (unchecked for security)
4. Forgot password: ✓ (optional)
5. Remember me: ✓ (optional)
6. Email as username: ✗ (use separate username)
7. Login with email: ✓ (allow email login)
8. Duplicate emails: ✗ (prevent duplicate emails)

9. Verify email: ✗ (disable for testing)

10. Click "Save"

Token Settings

1. Go to "Realm settings" → "Tokens" tab
2. Configure Token Lifespans:
3. Access Token Lifespan: 5 Minutes (default)
4. Access Token Lifespan For Implicit Flow: 15 Minutes
5. Client login timeout: 1 Minutes
6. Login timeout: 30 Minutes

7. Login action timeout: 5 Minutes

8. Click "Save"

Token Lifespan

For development, you can increase token lifespan to avoid frequent re-authentication. For production, keep tokens short-lived for security.

Email Settings (Optional)

For password reset and email verification:

1. Go to "Realm settings" → "Email" tab
2. Configure SMTP:
3. Host: smtp.gmail.com (or your SMTP server)
4. Port: 587
5. From: noreply@example.com
6. Enable SSL: ✗
7. Enable StartTLS: ✓
8. Enable Authentication: ✓
9. Username: Your email

10. Password: Your email password

11. Click "Save"

12. Click "Test connection" to verify

Step 4: Create Realm Role

Create the schedule-user role required by the API.

Admin ConsoleREST API

1. Go to "Realm roles" in left menu
2. Click "Create role"
3. Enter Role Details:
   • Role name: schedule-user
   • Description: Role for accessing schedule API
4. Click "Save"

# Get admin token (if not already set)
TOKEN=$(curl -X POST http://localhost:8080/realms/master/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin" \
  -d "password=admin" \
  -d "grant_type=password" \
  -d "client_id=admin-cli" \
  | jq -r '.access_token')

# Create role
curl -X POST http://localhost:8080/admin/realms/secure-test/roles \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "schedule-user",
    "description": "Role for accessing schedule API"
  }'

Step 5: Configure Security Settings

Brute Force Detection

Protect against brute force attacks:

1. Go to "Realm settings" → "Security defenses" tab
2. Configure Brute Force Detection:
3. Enabled: ✓
4. Permanent Lockout: ✗
5. Max Login Failures: 5
6. Wait Increment: 60 Seconds
7. Quick Login Check Milli Seconds: 1000
8. Minimum Quick Login Wait: 60 Seconds
9. Max Wait: 900 Seconds

10. Failure Reset Time: 43200 Seconds (12 hours)

11. Click "Save"

Password Policy

Set password requirements:

1. Go to "Realm settings" → "Security defenses" → "Password policy" tab
2. Add Policies:
3. Minimum Length: 8
4. Not Username: ✓
5. Uppercase Characters: 1
6. Lowercase Characters: 1
7. Digits: 1

8. Special Characters: 1

9. Click "Save"

Step 6: Verify Realm Configuration

Check Realm Endpoints

Get the OpenID Connect configuration:

curl http://localhost:8080/realms/secure-test/.well-known/openid-configuration | jq

You should see:

{
  "issuer": "http://localhost:8080/realms/secure-test",
  "authorization_endpoint": "http://localhost:8080/realms/secure-test/protocol/openid-connect/auth",
  "token_endpoint": "http://localhost:8080/realms/secure-test/protocol/openid-connect/token",
  "jwks_uri": "http://localhost:8080/realms/secure-test/protocol/openid-connect/certs",
  ...
}

Verify JWKS Endpoint

Check the JSON Web Key Set:

curl http://localhost:8080/realms/secure-test/protocol/openid-connect/certs | jq

You should see public keys used for JWT signature verification.

Testing with Users

To test token generation, you'll need to create users first. See the User Management guide for creating test users.

Export Realm Configuration

Admin ConsoleCLI

1. Go to "Realm settings"
2. Click "Action" → "Partial export"
3. Select what to export:
   • ✓ Export groups and roles
   • ✓ Export clients
   • ✗ Export users (for security)
4. Click "Export"

Download: secure-test-realm.json

```bash

Export realm