todolist-proto/KEYCLOAK_SETUP.md

# Keycloak Configuration Issue

## Problem

The application is getting a `401 Unauthorized` error when trying to authenticate:

```
POST https://terminus.bluelake.cloud/realms/dalex-immo-dev/protocol/openid-connect/token 401 (Unauthorized)
```

## Root Cause

The Keycloak client `dalex-proto` either:
1. Does not exist in the `dalex-immo-dev` realm, OR
2. Is not configured correctly for public client access

## Solution

You need to configure the Keycloak client on the server. Follow these steps:

### Step 1: Access Keycloak Admin Console

Go to: https://terminus.bluelake.cloud/admin/

### Step 2: Select the Realm

- Select the `dalex-immo-dev` realm from the realm dropdown

### Step 3: Create or Configure the Client

1. Navigate to **Clients** in the left sidebar
2. Look for client ID `dalex-proto`
3. If it doesn't exist, click **Create client**

### Step 4: Client Configuration

Configure the client with these settings:

#### Basic Settings Tab
```
Client ID: dalex-proto
Name: Dalex Todo Prototype
Description: Todo application prototype
Always display in UI: ON (optional)
Enabled: ON
```

#### Capability Config
```
Client authentication: OFF (this is a public client)
Authorization: OFF
Authentication flow:
  ☑ Standard flow (Authorization Code Flow)
  ☐ Direct access grants
  ☐ Implicit flow
  ☐ Service accounts roles
  ☐ OAuth 2.0 Device Authorization Grant
```

#### Access Settings
```
Root URL: http://localhost:3030
Home URL: http://localhost:3030
Valid redirect URIs: 
  - http://localhost:3030/*
  - http://localhost:3030
Valid post logout redirect URIs:
  - http://localhost:3030/*
  - http://localhost:3030
Web origins: 
  - http://localhost:3030
  - * (for development only)
Admin URL: (leave empty)
```

#### Advanced Settings (Optional but Recommended)
```
Proof Key for Code Exchange Code Challenge Method: S256
Access Token Lifespan: 5 Minutes (or as needed)
```

### Step 5: Save

Click **Save** at the bottom of the page.

### Step 6: Test

1. Restart the application: `docker-compose restart frontend`
2. Open http://localhost:3030
3. You should be redirected to Keycloak login
4. After login, you should see the todo application

## Alternative: Use Existing Client

If you don't have admin access to create a new client, you can use an existing public client that's typically available in Keycloak:

### Option 1: Use 'account-console' client

This client usually exists by default. Edit `frontend/src/keycloak.ts`:

```typescript
keycloak = new Keycloak({
  url: 'https://terminus.bluelake.cloud/',
  realm: 'dalex-immo-dev',
  clientId: 'account-console'  // Changed from 'dalex-proto'
})
```

Then rebuild: `docker-compose up --build -d`

### Option 2: Use 'account' client

Another default client. Edit `frontend/src/keycloak.ts`:

```typescript
keycloak = new Keycloak({
  url: 'https://terminus.bluelake.cloud/',
  realm: 'dalex-immo-dev',
  clientId: 'account'  // Changed from 'dalex-proto'
})
```

Then rebuild: `docker-compose up --build -d`

## Backend Configuration

Don't forget to update the backend `backend/Program.cs` to match the client ID:

```csharp
options.Audience = "dalex-proto"; // Or "account-console" or "account"
```

Then rebuild: `docker-compose up --build -d`

## Verification

After configuration, you should see in the browser console:

```
Initializing Keycloak...
Keycloak config: {url: "...", realm: "dalex-immo-dev", clientId: "dalex-proto"}
Keycloak initialized. Authenticated: true
User authenticated successfully
App.vue mounted, loading todos...
```

## Need Help?

If you don't have admin access to Keycloak, contact your Keycloak administrator and share this document with the required client configuration.