Claude-skill-registry keycloak-auth

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

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/keycloak-auth" ~/.claude/skills/majiayu000-claude-skill-registry-keycloak-auth && rm -rf "$T"

manifest: skills/data/keycloak-auth/SKILL.md

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