browser-session

command
v0.18.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

README

Browser session

A minimal single-page app and API protected by a browser session. Users sign in with OIDC. The server keeps the tokens in encrypted cookies and gives the page no token to handle: this is the backend-for-frontend (BFF) pattern, from http/browsersession.

ExampleNewApp in that package runs the same wiring against a mock provider. The code here is in main.go and static/index.html.

Routes

Route Served by
GET /auth/login redirects to the provider
GET /auth/callback completes login and sets the session cookies
POST /auth/logout ends the session
GET /auth/config the issuer and client ID
GET /api/me the API, behind the session
everything else the single-page app; a browser without a session is sent to /auth/login

Configuration

Variable Meaning Default
OIDC_ISSUER the OIDC issuer URL required
OIDC_CLIENT_ID the client registered with the provider required
OIDC_CLIENT_SECRET its secret required
OIDC_REDIRECT_URI the callback URL registered with the provider http://127.0.0.1:8080/auth/callback
COOKIE_ENCRYPTION_KEY 64 hexadecimal characters; openssl rand -hex 32 required
LISTEN_ADDR address to listen on 127.0.0.1:8080

Register OIDC_REDIRECT_URI with the provider and allow the client's audience, which this example sets to the client ID. Changing COOKIE_ENCRYPTION_KEY signs every user out.

export OIDC_ISSUER=https://idp.example/realms/demo OIDC_CLIENT_ID=demo OIDC_CLIENT_SECRET=...
export COOKIE_ENCRYPTION_KEY=$(openssl rand -hex 32)
go run ./examples/browser-session

Open http://127.0.0.1:8080/. The cookies are Secure. Browsers still accept them over plain HTTP on 127.0.0.1, but not on other hosts.

  • Encrypted. The access token, refresh token and expiry are each stored in their own AES-256-GCM encrypted cookie. A cookie is bound to its name, so a value cannot be moved from one cookie to another.
  • HttpOnly, Secure, SameSite=Lax. The page's JavaScript cannot read them, and the browser does not send them on a cross-site POST, PUT, PATCH or DELETE. Do not make a state-changing API route answer a GET.
  • Not a bearer token. The session cookies are named bff_session, bff_refresh and bff_expiry. A JWT middleware does not read them, and their values are ciphertext. On each API request the server decrypts the access token and sets the Authorization header, so the API validates it as it would any bearer token. A request that arrives with an Authorization header of its own is refused.
  • Refresh. A session that expires within five minutes is refreshed on the way through, and the new tokens are written back to the cookies. If the refresh fails, the session is cleared.
  • Logout. POST only, and it does nothing without a session cookie: a cross-site request carries none, so another site cannot sign a user out. When there is a session, the provider session is ended too, so the next login is not automatic.
  • Authorization is the API's job. The session proves who signed in. The API still validates the token and decides what the caller may do.

Documentation

Overview

Command main is a minimal single-page app and API protected by a browser session: OIDC login, encrypted session cookies and a backend-for-frontend.

See the README for configuration.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL