Authentication & Session Management
Authentication in a BFF application flows through several layers. Understanding how these layers connect helps you configure sessions correctly and debug problems when they arise.
How Sessions Work
Section titled “How Sessions Work”The Session Cookie
Section titled “The Session Cookie”After a successful login, BFF sets an HttpOnly, Secure, SameSite cookie in the browser. This cookie is the browser’s proof of session — it is sent automatically on every subsequent request to the BFF host. The cookie itself is signed and encrypted by ASP.NET Core’s data protection stack.
The browser never has access to the access token or refresh token. These are stored server-side.
Cookie-Based vs. Server-Side Sessions
Section titled “Cookie-Based vs. Server-Side Sessions”By default, BFF stores session state (including tokens) inside the encrypted cookie. This works but has limitations:
| Cookie-Based (default) | Server-Side Sessions | |
|---|---|---|
| Token storage | Inside the encrypted cookie | Server-side store (DB, memory) |
| Cookie size | Grows with claims/tokens — can hit browser 4KB limit | Fixed small size (session ID only) |
| Server-initiated logout | Not possible | ✅ Possible |
| Back-channel logout | Not supported | ✅ Supported |
| Session visibility | None | ✅ Query all active sessions |
| Scale-out | Cookie encryption keys must be shared | Session store must be shared |
Token Lifecycle
Section titled “Token Lifecycle”Tokens stored in the session are managed automatically:
- Access token — When an API call is made through the BFF, the access token is retrieved from the session. If it is expired or close to expiring, BFF automatically refreshes it using the refresh token.
- Refresh token — Stored server-side (in the session). Revoked automatically at logout.
- ID token — Used during logout to send a
id_token_hintto the identity provider.
See Token Management for how to access tokens programmatically.
Management Endpoints
Section titled “Management Endpoints”The BFF exposes several HTTP endpoints for managing the user’s session. These endpoints are called by the frontend to trigger authentication flows or query session state.
| Endpoint | Default Path | Purpose |
|---|---|---|
| Login | /bff/login | Start the OIDC authentication flow |
| Logout | /bff/logout | End the session and sign out |
| User | /bff/user | Return current user claims and session state |
| Silent Login | /bff/silent-login | Non-interactive login (deprecated in v4) |
| Back-Channel Logout | /bff/backchannel | Receive server-to-server logout notifications |
| Diagnostics | /bff/diagnostics | Show current tokens (development only) |
In This Section
Section titled “In This Section”| Page | Description |
|---|---|
| Authentication Handlers | OIDC and cookie handler configuration |
| Server-Side Sessions | Persistent session storage with Entity Framework or custom stores |
| OIDC Prompts | Controlling interactive vs. silent authentication |
| Login Endpoint | How to trigger login from the frontend |
| Logout Endpoint | How to trigger logout and CSRF protection |
| User Endpoint | Reading user claims and session state |
| Back-Channel Logout | Server-initiated session termination |
| Silent Login | Non-interactive login (deprecated) |
| Diagnostics | Development-time token inspection |