Keycloak Authentication

Configure cookie-based OIDC authentication with Keycloak.

For complete reference, see Library Guide.

Quick Start

appsettings.json

{
  "affolterNET": {
    "Web": {
      "Auth": {
        "Provider": {
          "Authority": "https://keycloak.example.com/realms/myrealm",
          "ClientId": "my-bff-client",
          "ClientSecret": "your-client-secret"
        },
        "CookieAuth": {
          "CookieName": ".MyApp.Auth",
          "ExpireTimeSpan": "01:00:00"
        }
      },
      "BffOptions": {
        "AuthMode": "Authenticate"
      }
    }
  }
}

Authentication Modes

| Mode | Description | |------|-------------| | None | No authentication required | | Authenticate | Valid session required, no permission checks | | Authorize | Valid session + Keycloak RPT permissions required |

Login/Logout Endpoints

The BFF provides these authentication endpoints:

| Endpoint | Method | Description | |----------|--------|-------------| | /bff/account/login | GET | Initiates OIDC login flow | | /bff/account/logout | GET/POST | Logs out user | | /bff/account/user | GET | Returns current user info |

Login with Return URL

/bff/account/login?returnUrl=/dashboard

Configuration Options

AuthProviderOptions

| Property | Description | |----------|-------------| | Authority | Keycloak realm URL | | ClientId | OIDC client identifier | | ClientSecret | OIDC client secret |

CookieAuthOptions

| Property | Type | Default | Description | |----------|------|---------|-------------| | CookieName | string | .AspNetCore.Auth | Authentication cookie name | | ExpireTimeSpan | TimeSpan | 01:00:00 | Cookie expiration | | SlidingExpiration | bool | true | Extend cookie on activity |

Token Refresh

The RefreshTokenMiddleware automatically refreshes tokens:

• Checks token expiration before each request
• Refreshes when < 10 seconds until expiration
• Uses semaphore lock to prevent concurrent refreshes
• Signs out user on refresh failure

SPA Integration

The BFF returns 401 instead of redirecting to Keycloak:

// Handle 401 in your SPA
if (response.status === 401) {
    window.location.href = '/bff/account/login?returnUrl=' +
        encodeURIComponent(window.location.pathname);
}

Troubleshooting

Login redirects to wrong URL

• Verify Authority URL is correct
• Check Keycloak client redirect URIs include your app
• Ensure cookies are being set (check SameSite settings)

Token refresh fails

• Check refresh token hasn't expired
• Verify Keycloak client has offline_access scope
• Review Keycloak session timeout settings

Logout doesn't work

• Ensure Keycloak client has logout redirect URI configured
• Check if front-channel logout is enabled