---

name: keycloak-auth description: Configure cookie-based OIDC authentication with Keycloak for affolterNET.Web.Bff. Use when setting up login/logout, token refresh, or Keycloak integration.

Keycloak Authentication

Configure cookie-based OIDC authentication with Keycloak.

For complete reference, see Library Guide.

Quick Start

appsettings.json

Copy{
  "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

Login/Logout Endpoints

The BFF provides these authentication endpoints:

Login with Return URL

Copy/bff/account/login?returnUrl=/dashboard

Configuration Options

AuthProviderOptions

CookieAuthOptions

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:

Copy// 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