Best practices

In addition to the core API interactions, building a secure and user-friendly authentication system requires adhering to several best practices. This section covers essential aspects such as token management, error handling, security measures, and logout procedures.

Implementing sign-ups and sign-ins correctly is the first step. To protect Customers and their data, you must also consider the broader security and usability landscape.

Token management

After a Customer logs in, Composable Commerce returns a Customer object. Your backend for frontend (BFF) then issues its own session token (for example, a JSON web token (JWT) or a session cookie) to the client. Managing this token securely is important.

Here are a few key aspects to consider for client-side token management:

• Securely store session tokens:
  • For web applications: use HttpOnly cookies. The HttpOnly attribute prevents client-side scripts from accessing the cookie, thereby mitigating Cross-Site Scripting (XSS) attacks. Always combine this with the Secure attribute to ensure that cookies are sent only over HTTPS.
  • For mobile applications: use secure storage mechanisms provided by the operating system, such as the iOS Keychain or Android Keystore.
• Implement robust session management: make sure that your session management solution has the following characteristics:
  • Secure: protects against common attacks such as XSS, cross-site request forgery (CSRF), session hijacking, and token replay.
  • Controllable: provides immediate, server-side invalidation of any user session.
  • User-friendly: maintains a seamless user experience without sacrificing security.
  • Resilient: ensures that a compromise of one part of the session mechanism doesn't lead to a full session takeover.
  • Performant and scalable: handles many concurrent sessions efficiently.
  • Auditable and monitorable: enables logging and monitoring of session-related events.
  • Clear authorization: integrates with systems that enforce user permissions.
  • Manages token lifecycle: securely handles the creation, transmission, storage, rotation, and expiration of session tokens.
  • Minimizes attack surface: uses techniques such as HttpOnly and Secure cookies to reduce vulnerabilities.
  • Prevents information leakage: avoids exposing sensitive system details in tokens and error messages.
• Use appropriate TTL for tokens: make sure that your session tokens have a reasonable time to live (TTL). A common pattern is to use short-lived access tokens combined with longer-lived refresh tokens. This balances security by limiting the window of compromise with user convenience by reducing frequent re-logins.
• Provide clear UX for token-based flows: inform Customers about session expiration and provide clear prompts for re-authentication when necessary.

Error handling

Your application's response to errors significantly impacts both the security and user experience.

• Provide user-friendly error messages: as with InvalidCredentials, make sure that the messages displayed to Customers are generic so as not to reveal sensitive information but are helpful enough to guide them. For example, "The email or password you entered is incorrect. Please try again."
• Log detailed errors server-side for debugging: although client-side messages are generic, ensure that your BFF's logs contains detailed error information from Composable Commerce (such as specific error codes and full response bodies) to make the troubleshooting process easier. Never expose these detailed logs to the client.

Security measures

Ensure that you follow these security best practices in every layer of your authentication system:

• Always use HTTPS: all communication between the client, your BFF, and Composable Commerce must occur over HTTPS to encrypt the data.
• Validate all user-supplied data: before sending any user input to Composable Commerce, your BFF should thoroughly validate it to prevent malformed data and potential injection attacks.
• Enforce password complexity rules: Composable Commerce securely hashes and stores passwords, but doesn't enforce complexity. Your BFF must validate password requirements such as minimum length and character types during the sign up and password reset processes.
• Always verify email addresses: as covered previously, email verification is a fundamental security measure against fake accounts and for secure password recovery.
• Implement rate limiting on authentication endpoints: use rate limiting on your BFF's login, sign up, and password reset endpoints to prevent brute-force attacks.
• Limit failed sign-in attempts: track failed attempts per user account. After a certain number of failed login attempts, temporarily lock the account or impose a delay between subsequent attempts.
• Use an API Gateway for global rate limiting: if you use an API Gateway, then configure global rate limiting rules to protect your BFF from an overwhelming amount of traffic.

Logout procedures

A secure logout mechanism is as important as a secure login. Follow these logout mechanism best practices:

• Implement a clear logout mechanism: provide an easily accessible Logout button in the UI.
• Client-side: Clear tokens and user session data: when a user logs out, your client-side application must immediately delete any session tokens and clear any cached user-specific data.
• Server-side (BFF): Invalidate the session: your BFF should actively invalidate the session on the server to prevent token-replay attacks. This is critical if your session management involves server-side session stores or refresh tokens.

By applying these best practices, you can build an authentication system that's not only functional but is also highly secure, resilient, and provides a trustworthy experience for Customers.

Key takeaways

• Token management: use HttpOnly and Secure cookies for web apps and OS-level secure storage for mobile. Implement short-lived access tokens with long-lived refresh tokens.
• Error handling: provide generic, user-friendly error messages on the client-side while logging detailed, specific errors on the server-side for debugging.
• Security: enforce HTTPS, validate all user input in the BFF, and implement password complexity rules. Use rate limiting and account lockouts to prevent brute-force attacks.
• Logout: ensure that the logout process clears tokens on the client and invalidates the session on the server to prevent reuse.

Test your knowledge