v9 (current) v8
Edit Page

Cookie Authentication

RESTHeart Cloud

Cookie Authentication allows the client browser to store an authentication token in a secure cookie. This mechanism enables authentication based on the stored cookie, allowing the client to remain authenticated across multiple requests without having to send credentials each time. The token is securely saved in the cookie, ensuring that sensitive data is protected and accessible only to the intended server.

Note
 this is the suggested authentication mechanism when the client is the browser.

Typically, a client first authenticates using Basic Authentication and then uses the auth token returned in the first response for further requests. This auth token is usually stored in the local storage by web clients. The local storage is readable by JavaScript, thus exposing this approach to Cross-site Scripting (XSS) security attacks. Storing the auth token in a secure cookie avoids XSS.

Important
 Using cookie authentication and JWT tokens effectively enables Single Sign-On.

Configuration Options

Cookie Authentication is disabled by default. To enable it, the following three plugins must be enabled and configured: authCookieSetter, authCookieHandler, and authCookieRemover.

The cookie authentication mechanism can function using three different options:

Option 1 — JWT verified by jwtAuthenticationMechanism

This option is recommended if you also want to allow clients to authenticate via JWTs sent in the Authorization header (not stored in a cookie).

/tokenBasicAuthMechanism/enabled->true
/jwtAuthenticationMechanism/enabled->true
/jwtTokenManager/enabled->true
/rndTokenManager/enabled->false

Option 2 — JWT verified by tokenBasicAuthMechanism

Choose this option if you have multiple instances of RESTHeart verifying cookies, and JWT header-based authentication isn’t required.

/tokenBasicAuthMechanism/enabled->true
/jwtAuthenticationMechanism/enabled->false
/jwtTokenManager/enabled->true
/rndTokenManager/enabled->false

Option 3 — RGT cookies (randomly generated tokens)

For authentication via RGT cookies, enable these components:

  • tokenBasicAuthMechanism: Manages the basic authentication process.

  • rndTokenManager: Manages and validates randomly generated tokens for Basic Authentication cookies.

/tokenBasicAuthMechanism/enabled->true
/jwtAuthenticationMechanism/enabled->false
/jwtTokenManager/enabled->false
/rndTokenManager/enabled->true
Note
 RGT cookies can only be verified by the RESTHeart instance that issued them. For multi-instance deployments, it is advisable to use JWT cookies instead.

authCookieSetter

This component is responsible for initiating a user’s authenticated session by setting the authentication cookie.

Activates when the /token/cookie endpoint is called with valid credentials, setting a cookie populated with a token generated by the enabled Token Manager.

Configuration

authCookieSetter:
  enabled: false          # Not enabled by default
  secure: true            # true if only allow setting the cookie on https
  name: rh_auth           # The name of the cookie to be set
  domain: localhost       # The domain within which the cookie is valid
  path: /                 # The cookie path, applicable to the entire domain
  http-only: true         # If true, enhances security by making the cookie inaccessible to JavaScript
  same-site: true         # Restricts the cookie to first-party contexts, preventing CSRF attacks
  same-site-mode: strict  # Strictly prevents the cookie from being sent along with cross-site requests
  expires-ttl: 86400     # Defines the duration (in seconds, default 1 day) for which the cookie is valid

When using JWT tokens, the cookie can be updated by calling POST /token/cookie?renew. The query parameter renew forces the jwtTokenManager to generate a new JWT token.

You can also add the ?renew query parameter to GET /token or GET /token/cookie requests to force token renewal.

authCookieHandler

Responsible for utilizing the authentication cookie to maintain authenticated sessions across requests.

Reads the rh_auth cookie (actual cookie name is defined in authCookieSetter configuration), if available, and constructs an Authorization header. This allows for seamless continuation of sessions and supports both Basic and JWT authentication mechanisms.

Configuration

authCookieHandler:
  enabled: false          # Not enabled by default

authCookieRemover

Handles the secure and explicit termination of authenticated sessions.

Clears the authentication cookie in response to a POST /logout request. This effectively logs out the user by wiping the authentication cookie from the user’s browser, ensuring the session is securely terminated.

Configuration

authCookieRemover:
  enabled: false          # Not enabled by default
  secure: false           # If the request to clean the cookie should be authenticated
  uri: /logout            # The endpoint that triggers this service

Example usage

This is an example of how a user might log in, make some requests, and then log out within a system using cookie authentication with the configuration described previously. This example assumes that the system is web-based and communicates over HTTP.

Logging In

The user submits their credentials (username and password) via Basic Authentication (Authorization header) from a form on a client application, which sends a GET request to the`/roles/{username}` endpoint, including the ?set-auth-cookie query parameters

GET /roles/{username}?set-auth-cookie HTTP/1.1
Host: localhost
Content-Type: application/json
Authorization: Basic YWRtaW46c2VjcmV0

If the credentials are valid, the server responds by setting an rh_auth cookie containing the authentication token and returns a success response.

HTTP/1.1 200 OK
Set-Cookie: rh_auth="Basic YWRtaW46MmliNWFsaDFxajZ4eHY5aWlyOTZsejh1bnJjMHQzNWFucnEyYzh1cG12cHNpOGc3dDQ="; Version=1; Path=/; Domain=localhost; Secure; HttpOnly; Expires=Sat, 20 Apr 2024 11:53:00 GMT; SameSite=Strict
Content-Type: application/json

{
    "authenticated": true,
    "roles": [ "user-role" ]
}

Note that the value of the cookie doesn’t include the actual user credentials but uses the auth token generated by the enabled Token Manager.

Making Authenticated Requests

Once the cookie is set, the user can make subsequent requests to the server. The browser automatically includes the rh_auth cookie with each request to the domain.

For example, if the user wants to access a protected resource, they might send a GET request to the server:

GET /protected-resource HTTP/1.1
Host: localhost
Cookie: rh_auth="Basic YWRtaW46MmliNWFsaDFxajZ4eHY5aWlyOTZsejh1bnJjMHQzNWFucnEyYzh1cG12cHNpOGc3dDQ="

The server checks the cookie, validates the session, and if valid, responds with the requested data.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": "Here is your protected resource data."
}

Logging Out

To log out, the user sends a POST request to the logout endpoint. This request doesn’t need to include user credentials but should be made from the same domain to ensure the browser includes the authentication cookie.

POST /logout HTTP/1.1
Host: localhost
Cookie: rh_auth=

The server processes the logout request and clears the authentication cookie by setting its value to null.

HTTP/1.1 200 OK
Set-Cookie: rh_auth=; path=/; domain=localhost; secure; HttpOnly; SameSite=Strict
Content-Type: application/json

After this, the user is logged out, and their session is terminated. The cookie is invalidated, and any subsequent requests to the server that require authentication will fail until the user logs in again.