Authentication

Use this hub to understand authentication in the SHOPin storefront accelerator: how sign-in and sign-up traffic flows from the presentation app to the BFF, and how the BFF applies cookies, CSRF, and tokens. The BFF calls your wired integration for identity and user-scoped commerce APIs (see Data sources); the presentation app does not call those backends directly.

Why this shape

The accelerator ships one clear pattern—presentation → BFF → integration, with tokens and CSRF handled in the BFF—so the default tree stays small and easier to follow. That is a baseline, not a claim that only one vendor or protocol is valid.

You can wire another ecommerce backend or identity provider by adding or swapping packages under integrations/ and the BFF data source (see Add a new integration, Integrations). You can also replace or extend how login, tokens, or session rules work, as long as you keep your deployment’s security goals in mind—the docs here describe what the reference implementation does, not every acceptable design.

Reference example and production readiness

This hub describes a reference implementation: one way to connect the presentation app, BFF, and an integration while keeping the repository approachable. It is not presented as universal best practice, as complete security for every product, or as something you should reuse without analysis.

The codebase is wired with a small set of defaults. They are fine for learning and for many early deployments, but they do not by themselves mean your auth is “finished” or risk-free:

• BFF-centred login — The presentation app posts to your backend, and the backend talks to the identity integration you configured. The exact OAuth or API calls depend on that package; the overall shape is “browser → BFF → provider,” not “browser only.”
• HTTP-only cookies and CSRF — Tokens are kept in HTTP-only cookies, and mutating requests to the BFF expect CSRF protection. See CSRF protection and Tokens.
• Document CSP — Page-level Content Security Policy for auth routes is not preconfigured in the repo. If you want CSP, add it where you host or in Next.js (Content Security Policy (CSP)).

Together, these are learning and extension shortcuts. They do not replace threat modelling, checking policy and regulatory fit, testing, monitoring, incident response, or review by people who understand your context. This documentation explains how the reference path behaves; it does not substitute for those steps.

Security measures (auth) lists concrete items: what the reference BFF already does (HTTP-only token cookies, CSRF, refresh interceptor, and similar) and what you typically bolt on in your own project (document CSP, CIAM or IdP, rate limiting, stricter validation).

What the accelerator implements

• BFF-owned sessions — The presentation app sends credentials and CSRF-protected requests to the BFF only. The BFF delegates to whatever auth services your active integration exposes. For example, the commercetools-auth package is the reference auth provider integration: OAuth-style flows—password grant, refresh, and anonymous tokens—when that package is wired. Access and refresh tokens are stored in HTTP-only cookies set by the BFF, not in browser storage visible to application JavaScript.
• Token handling — Before cookies are set, tokens are encrypted and signed (JWS + JWE). Details: Tokens.
• CSRF — State-changing BFF routes expect a double-submit style check with signed, encrypted CSRF values. Details: CSRF protection.
• Sign-in and sign-up UI — The presentation app owns form UX and client-side validation; it posts to BFF endpoints. Decisions about auth and where tokens live stay on the server.

Reference integrations in the repository: commercetools-auth is the bundled auth provider for Commercetools-oriented setups (OAuth login, register, logout, refresh). commercetools-api adds helpers such as UserClientService for user-scoped commerce API calls in that setup. Shared auth contracts live under core/contracts/src/auth; evolve them when you introduce a different identity or commerce stack.

Anonymous sessions

Guest shoppers rely on an anonymous session that the BFF creates and maintains. That flow is not exposed as POST /auth/anonymous-session on auth.controller.ts. For behaviour, cookies, and cart linkage, read Anonymous sessions and Cart.

Summary

Related

• BFF
• Communication between presentation and BFF
• Maintain contracts
• Data sources
• Add a new integration
• Rate limiting
• General workflow rules

Back to Cart & authentication · Back to How to work with SHOPin