keycloak-auth

Mcafee123's avatarfrom Mcafee123

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

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 8, 2026
[Developer Tools]

When & Why to Use This Skill

This Claude skill streamlines the configuration of cookie-based OIDC authentication using Keycloak for the affolterNET.Web.Bff framework. It provides expert guidance on setting up secure identity providers, managing session cookies, and implementing robust token refresh mechanisms to ensure seamless and secure user authentication in web applications.

Use Cases

  • Case 1: Initializing OIDC authentication settings in appsettings.json for a .NET Backend-for-Frontend (BFF) project using Keycloak.
  • Case 2: Implementing automated token refresh logic to prevent session expiration and handle silent re-authentication in Single Page Applications (SPAs).
  • Case 3: Configuring secure login and logout endpoints (/bff/account/login and /bff/account/logout) with custom return URLs.
  • Case 4: Troubleshooting common authentication issues such as incorrect redirect URIs, cookie SameSite policy conflicts, and token refresh failures.
namekeycloak-auth
descriptionConfigure 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

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