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