Claude Code Plugins

Community-maintained marketplace

Feedback

keycloak-auth

@Mcafee123/affolterNET.Web
0
0

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

Install Skill

1Download skill
2Enable skills in Claude

Open claude.ai/settings/capabilities and find the "Skills" section

3Upload to Claude

Click "Upload skill" and select the downloaded ZIP file

Note: Please verify skill by going through its instructions before using it.

SKILL.md

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

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