Go net/http sessions

Package github.com/keenauth/keenauth-go/bff adds sign-in to a Go net/http application. Your server is the OAuth client and keeps every token on the server. The browser gets only an encrypted, HttpOnly session cookie and never sees an access, refresh or ID token. This is the backend-for-frontend (BFF) pattern. The package uses only the standard library. It is not published yet.

To protect an API that receives bearer tokens instead, see Protecting your API.

Before you start

1. In the dashboard, create a web application in your environment.
2. Choose client authentication: a client secret (bff.ClientSecretBasic) or private_key_jwt (bff.PrivateKeyJWT). For private_key_jwt, register the application's public key and keep the private key on your server.
3. Add the redirect URI https://app.acme.example/auth/callback and the post-logout redirect URI https://app.acme.example/.
4. Generate a cookie secret of at least 32 characters, for example with openssl rand -base64 32. Keep it in your secret store, not in the repository.

Set up

package main

import (
	"fmt"
	"net/http"
	"os"

	"github.com/keenauth/keenauth-go/bff"
)

func main() {
	auth, err := bff.New(bff.Options{
		Issuer:     "https://acme.eu.keenauth.app", // your environment's issuer, exactly
		ClientID:   "app_01j9zzzzzzzzzzzzzzzzzzzz",
		ClientAuth: bff.ClientSecretBasic{Secret: os.Getenv("KEENAUTH_CLIENT_SECRET")},
		AppBaseURL: "https://app.acme.example",
		Secrets:    []string{os.Getenv("KEENAUTH_COOKIE_SECRET")},
	})
	if err != nil {
		panic(err) // configuration errors stop the app at start-up
	}

	mux := http.NewServeMux()
	mux.Handle("GET /orders", auth.RequireAuth(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		s := bff.FromContext(r.Context()).Session
		fmt.Fprintf(w, "Signed in as %s", s.User.Email)
	})))

	http.ListenAndServe(":8080", auth.Middleware(mux))
}

To use private_key_jwt instead of a client secret, pass the private key. The package signs a new client assertion for every token and PAR request (iss and sub are your client ID, aud is the issuer, lifetime 2 minutes, a new jti each time):

pemBytes, err := os.ReadFile("/run/secrets/keenauth-app-key.pem")
if err != nil {
	panic(err)
}
key, err := assertion.ParsePrivateKeyPEM(pemBytes) // import "github.com/keenauth/keenauth-go/assertion"
if err != nil {
	panic(err)
}
auth, err := bff.New(bff.Options{
	Issuer:     "https://acme.eu.keenauth.app",
	ClientID:   "app_01j9zzzzzzzzzzzzzzzzzzzz",
	ClientAuth: bff.PrivateKeyJWT{Key: key, KeyID: "app-key-2026-11"},
	AppBaseURL: "https://app.acme.example",
	Secrets:    []string{os.Getenv("KEENAUTH_COOKIE_SECRET")},
})

ES256 (P-256), EdDSA (Ed25519), RS256 and PS256 (RSA, 2048 bits or more) are supported; the algorithm follows the key, and Algorithm: "PS256" selects PSS for an RSA key. Key can be any crypto.Signer, so a key held in a KMS or HSM works too. If you sign elsewhere, set bff.PrivateKeyJWT{Assertion: f} instead, where f returns a new signed assertion on every call. Set one of Key and Assertion, not both.

AppBaseURL is the public address of your app. The package builds the redirect URI and every redirect from it, never from the request's Host or X-Forwarded-* headers. Plain http is accepted only for localhost.

Routes

Middleware serves three routes and reads the session on every other request. You can also mount the routes alone with mux.Handle("/auth/", auth).

Sign-in uses the authorization code flow with PKCE (S256). The request is pushed to the server (PAR) when your environment offers it. On the callback the package checks state, iss and the ID token, including its nonce. Each successful sign-in creates a new session; the old one is discarded.

returnTo must be a path of your own app, such as /orders?tab=open. Any other value, such as //evil.example or a full URL, is ignored and the user lands on /.

Protect handlers

auth.RequireAuth(handler) lets a request through only with a session:

• a page request (GET or HEAD) without a session is redirected to /auth/login with returnTo;
• a request to /api/…, or with another method, gets 401 with a problem document. Pass bff.GuardOptions{API: true} to answer 401 on any path.

For POST, PUT, PATCH, DELETE and other unsafe methods, the browser must say the request comes from your app: Sec-Fetch-Site: same-origin, or an Origin header equal to your app's origin. Other requests get 403. This protects against cross-site request forgery in addition to SameSite=Lax.

Use the session and call your API

bff.FromContext(r.Context()) returns:

• Session: nil, or the signed-in user. Session.User has typed ID token claims such as Subject, Email, Name, OrgID and OrgRoles; all claims are in Session.User.Claims. The session never contains a token.
• AccessToken: a valid access token for server-side calls, or "". Do not send it to the browser.

When the access token expires within 60 seconds, the package refreshes it before your handler runs. Each refresh rotates the refresh token and sets the new session cookie on the response. If the server refuses the refresh token, the session ends. A temporary server error keeps the session unchanged. Concurrent requests in one process share one refresh.

Switch organization

auth.SwitchOrganizationPath("org_01j9…", "/dashboard") returns a link to /auth/login that signs the user in again in that organization. KeenAuth checks the membership. After sign-in, Session.User.OrgID holds the organization.

Sign out

Send a POST to /auth/logout from a form. The package deletes the session cookie (and the stored session, if you use a store), revokes the refresh token and sends the browser to your environment's logout endpoint, which returns it to your app. A request that the browser marks as coming from another site is refused. Browsers that do not send Sec-Fetch-Site can sign out only with a POST from your own pages.

Session storage

By default the whole session is in the cookie, encrypted and authenticated with AES-256-GCM using a key derived from the secret. A changed or copied cookie is rejected. The cookie is named __Host-keenauth_session.0 and set with Secure, HttpOnly, SameSite=Lax and Path=/. On http://localhost the __Host- prefix and Secure are left out. Large sessions are split into up to three cookies.

To keep tokens on the server, set Options.Store to a bff.SessionStore (Get, Set, Delete), for example backed by Redis. The cookie then holds only an encrypted random session ID. Every sign-in creates a new ID and deletes the previous record. The store holds tokens, so restrict access to it. bff.MemoryStore is for development and tests only.

A session lasts at most 7 days (SessionMaxAge); refreshing does not extend it. To change the secret, list the new one first: Secrets: []string{newSecret, oldSecret}. Remove the old one after SessionMaxAge.

Current limits

• DPoP-bound tokens and back-channel logout are not handled yet.
• Refreshes are shared only within one server process. With several instances, the application setting refresh_reuse_interval_s (default 5 seconds) lets a parallel refresh succeed; if you set it to 0, the second refresh ends the session.