aibot88 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
AuthorityURL 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