Tokens
Authentication · Tokens
It is important to read the sections Why this shape and Reference example and production readiness on Authentication before relying on this page. They explain why the default BFF-centred pattern exists, how you can extend or replace it, and what the reference implementation does and does not promise for production.
Read this page to see how the BFF stores access and refresh tokens, how refresh runs on incoming requests, and how the auth provider sets token lifetime at the platform level (Commercetools is the concrete example in the reference tree).
Token storage
- HTTP-only cookies — Application JavaScript cannot read the raw token values.
- Encrypt and sign before write — Nested JWS + JWE; implementation in
token-storage.service.ts. - Access token expiry — Follows the provider OAuth response (for example
expires_infrom Commercetools when that is your auth provider). - Refresh cookie cap — Code limits refresh cookie lifetime with
REFRESH_TOKEN_MAX_AGEinconfig/constants/src/auth.tsso the browser cookie does not outlive the refresh token the platform issued.
Token refresh
token-refresh.interceptor.ts— Detects missing or expired access tokens and tries to refresh using the refresh token—for examplerefresh-token.service.tswhencommercetools-authis the active auth provider.- Proactive refresh — When the access token is missing but a refresh token exists, the BFF may refresh before it handles the request.
- Failure — After a failed refresh, tokens are cleared and the caller gets
401 Unauthorized. Cart ID cleanup on that path lives intoken-refresh.interceptor.ts.
Cryptographic packaging
- Encryption — AES-256-GCM (A256GCM) on the nested JWE layer.
- Signing — HS256 on the JWS layer to detect tampering.
- Invalid values — Failed decrypt or verify clears the cookies.
Background on JWS/JWE: Auth0 – Demystifying JOSE (JWT family).
Provider token lifetimes (Commercetools example)
When Commercetools is your auth provider, these details apply:
-
Platform settings — Access and refresh lifetimes are defined in Commercetools API client configuration (Merchant Center or Management API) and appear in OAuth responses as
expires_in. -
Application behaviour — The BFF reads those values to set cookie expirations; it cannot extend the platform’s token lifetime beyond what the provider enforces.
-
Cookie alignment — Match
REFRESH_TOKEN_MAX_AGEto the refresh token lifetime your provider issues so cookies and tokens stay aligned.
Summary
| Concern | Detail |
|---|---|
| Storage | HTTP-only cookies; encrypt/sign before write |
| Refresh | Interceptor + auth provider refresh service when wired (for example Commercetools) |
| Cookie max-age | REFRESH_TOKEN_MAX_AGE in @config/constants auth module |
| Lifetime source | Provider API client settings (Commercetools when using that stack) |