Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
update custom API authentication docs (#14189)
Kacper Mękarski53e877129893
diff --git a/docs/developer/how-to/custom-api-authentication.mdx b/docs/developer/how-to/custom-api-authentication.mdxindex 1c4fbcd4be..3f7c188bf4 100644--- a/docs/developer/how-to/custom-api-authentication.mdx+++ b/docs/developer/how-to/custom-api-authentication.mdx@@ -77,7 +77,7 @@ module MyAppdef authenticatetoken = params[:token] || extract_bearer- return failure(I18n.t('spree.api.unauthorized')) if token.blank?+ return failure(Spree.t('api.unauthorized')) if token.blank?payload = verify_with_jwks(token)@@ -93,13 +93,13 @@ module MyAppsuccess(user)rescue JWT::DecodeError, JWT::ExpiredSignature, JWT::InvalidIssuerError, JWT::InvalidAudError, KeyError => e- failure(e.message)+ failure(Spree.t('api.unauthorized'))endprivatedef verify_with_jwks(token)- jwks_loader = ->(opts) { jwks(force: opts[:invalidate]) }+ jwks_loader = ->(opts) { jwks(force: opts[:kid_not_found]) }JWT.decode(token, nil, true,@@ -335,7 +335,7 @@ This revokes the Spree refresh token. The Spree JWT itself remains valid until iA few things worth getting right:- **Don't try to pass the third-party JWT through to protected endpoints.** Spree's `JwtAuthentication` concern verifies `iss: 'spree'` and the expected audience (`store_api` or `admin_api`) with HS256 against the Spree secret — a foreign RS256 token will never validate, and you don't want it to. The exchange-at-login model is the right one.-- **JWKS caching and rotation.** Cache the JWKS (the example uses a 1-hour TTL) but make sure your loader honors the `invalidate: true` option so that an unrecognized `kid` triggers a refetch. Otherwise key rotation at the IdP locks users out for up to the TTL.+- **JWKS caching and rotation.** Cache the JWKS (the example uses a 1-hour TTL) but make sure your loader honors the `kid_not_found: true` option so that an unrecognized `kid` triggers a refetch. Otherwise key rotation at the IdP locks users out for up to the TTL.- **Validate `iss` and `aud` claims.** Always. The example passes `verify_iss: true, verify_aud: true` to `JWT.decode` — don't drop those.- **Algorithm pinning.** Hard-code `algorithms: ['RS256']` (or whatever your IdP uses). Never let the token's own `alg` header decide — the classic `alg: none` and HS-as-RS confusion attacks both exploit lax algorithm selection.- **Rate limiting.** `POST /auth/login` is rate-limited per IP via `Spree::Api::Config[:rate_limit_login]`. Tune it in your app config if needed — the same limit applies to email/password and provider-dispatched logins.