Keycloak Authentication

Configure cookie-based OIDC authentication with Keycloak.

For complete reference, see Library Guide.

Quick Start

appsettings.json

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

code

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

typescript

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