Skip to main content

Session Management: Cookies vs Local Storage

When building a web application, you will need to manage user sessions. This includes storing user data such as authentication tokens, user preferences, and other data that needs to persist across page reloads.

The Nodeblocks Front-end SDK provides two ways to manage user sessions: cookies and local storage. In this guide, we will talk about how to configure session management on the front-end and the differences between cookies and local storage.

Refreshing Access Tokens​

The Nodeblocks Auth service provides a way to refresh access tokens using refresh tokens. For the Front-end Framework this is required, and the front-end will automatically refresh the access token before it expires.

Back-end Session configuration​

Before configuring the front-end, ensure that your backend services are configured correctly to handle session management. For example, if you are using the Nodeblocks services with cookies, configure them like this:

import {
  createNodeblocksXApp,
  defaultAdapter,
} from '@basaldev/blocks-xxx-service';
import {
  crypto,
  security,
} from '@basaldev/blocks-backend-sdk';

const adapter = await defaultAdapter.createXXXServiceAdapter(
{
  authenticate: security.defaultCookieAuth,
  ...
}, { ... });

...


await createNodeblocksOrderApp({
  corsOptions: {
    credentials: true,
    origin: [...], // List of URLs that are allowed to access the server
  },
  enableCookieParser: true,
}).startService({
  ...
  adapter,
});

For local storage, enableCookieParser should be set to false, and authenticate should be set to security.defaultBearerAuth.

Alternatively, for custom session management, you can create your own authenticate method and pass it to the createXXXServiceAdapter function.

Front-end Session configuration​

The Nodeblocks Frontend SDK provides a SessionService interface that you can use to manage user sessions. The SDK provides two implementations of the SessionService interface: CookieSessionService and LocalStorageSessionService, which you can use to manage user sessions using cookies and local storage, respectively. In addition, you can also create your own custom implementation of the SessionService interface.

CookieSessionService is designed to work with the back-end's defaultCookieAuth method, while LocalStorageSessionService is designed to work with the back-end's defaultBearerAuth method.

CookieSessionService​

To use the CookieSessionService, you need to create an instance of the CookieSessionService class and pass it to your API clients and front-end framework template:

import { api, session } from '@basaldev/blocks-frontend-sdk';

const sessionService = new session.CookieSessionService();
const authApi = new api.AuthDefaultAdapterApi(
  'https://auth.example.com',
  sessionService
);

The CookieSessionService class does not access cookies directly (as they use the Secure and HttpOnly flags), but it will use the response codes from refreshing the access token to determine if the user is authenticated.

The following cookies are generally assumed to be set by the backend:

  • accessToken - The encrypted access token
  • refreshToken - The encrypted refresh token

The following local storage keys are used:

  • nbc-fingerprint - A generated fingerprint to identify this device. The fingerprint is used to determine if the device is the same as the one that originally logged in.

Troubleshooting​

If you are unable to authenticate using the CookieSessionService, check the following:

  • Ensure you are using https in your local environment (secure cookies require https)
  • Ensure that the backend has authenticate set to security.defaultCookieAuth
  • Ensure that the backend has corsOptions specified with credentials: true if you are using a different domain for the front-end and back-end

LocalStorageSessionService​

To use the LocalStorageSessionService, you need to create an instance of the LocalStorageSessionService class and pass it to your API clients and front-end framework template:

import { api, session } from '@basaldev/blocks-frontend-sdk';

const sessionService = new session.LocalStorageSessionService();
const authApi = new api.AuthDefaultAdapterApi(
  'https://auth.example.com',
  sessionService
);

The LocalStorageSessionService class uses the localStorage API to store the access token and refresh token. The access token will be automatically used to communicate in requests sent to the back-end.

The following local storage keys are used:

  • nbc-tokens - The encrypted access token and refresh token, as an object
  • nbc-fingerprint - A generated fingerprint to identify this device. The fingerprint is used to determine if the device is the same as the one that originally logged in.

Differences between Cookies and Local Storage​

There are different use cases for cookies and local storage. Generally, it is more secure to use cookies for session management, as they are less vulnerable to cross-site scripting attacks. However, in cases where web applications need to work cross-origin, it may be challenging to use cookies due to CORS restrictions.

danger

Nodeblocks has extra restrictions on local storage bearer token access:

  • The User Agent and IP address must match the original login request. If both do not match, the request will fail to authenticate.