Allow to store the auth token in a secure cookie and allow to authenticate from it.
Rationale
Using cookie authentication and JWT token effectively enable Single Sign On.
Usually a client first authenticate using Basic Authentication and then use the auth token returned in the first response for furthers requests. This auth token is usually stored in the local storage by web clients. The local storage is readable by JavaScript thus opening this approach to Cross-site Scripting security attacks. Storing the auth token in a secure cookie avoids XSS.
Detailed documentation
Cookie Authentication Overview
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
0. 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).
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.
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.
1. authCookieSetter
This component is responsible for initiating a user's authenticated session by setting the authentication cookie.
Activates when a URL includes the query parameter ?set-auth-cookie and a user is authenticated, setting a cookie populated with a token generated by the enabled Token Manager.
Configuration
# Sets the auth token when the request has been successfully authenticated
# and the query parameter '?set-auth-cookie' is present
# The cookie is populated with the auth token generated by the currently enabled Token Manager.
authCookieSetter:
enabled: false # Not enabled by default
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.
exprires-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 specifying both '?set-auth-cookie&renew-auth-token'.
The query parameter renew-auth-token forces the jwtTokenManager to update the JWT.
2. 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
# Constructs the Authorization header using the auth cookie,
# It is compatible with both Basic and JWT authentication mechanisms.
# It reads the auth cookie (if present) and formats the value appropriately
# to create an Authorization header.
authCookieHandler:
enabled: false # Not enabled by default
3. 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
# This service handles the clearing of the auth cookie in response to a POST /logout request.
# When this endpoint is called, it effectively wipes the auth cookie from the user's browser,
# effectively logging out the user.
authCookieRemover:
enabled: false # Not enabled by default
secure: false # If request to clean the cookie should be authenticated
defaultUri: /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.
1. 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.
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.
2. 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."
}
3. 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
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.
Brief overview
Allow to store the auth token in a secure cookie and allow to authenticate from it.
Rationale
Detailed documentation
Cookie Authentication Overview
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
0. Configuration Options
Cookie Authentication is disabled by default. To enable it, the following three plugins must be enabled and configured:
authCookieSetter,authCookieHandlerandauthCookieRemover.The cookie authentication mechanism can function using three different options:
Option 1: JWT Verified by
jwtAuthenticationMechanismThis option is recommended if you also want to allow clients to authenticate via JWTs sent in the
Authorizationheader (not stored in a cookie).Option 2: JWT Verified by
tokenBasicAuthMechanismChoose this option if you have multiple instances of RESTHeart verifying cookies, and JWT header-based authentication isn't required.
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.1. authCookieSetter
This component is responsible for initiating a user's authenticated session by setting the authentication cookie.
Activates when a URL includes the query parameter
?set-auth-cookieand a user is authenticated, setting a cookie populated with a token generated by the enabled Token Manager.Configuration
When using JWT tokens, the cookie can be updated specifying both '?set-auth-cookie&renew-auth-token'. The query parameter
renew-auth-tokenforces thejwtTokenManagerto update the JWT.2. authCookieHandler
Responsible for utilizing the authentication cookie to maintain authenticated sessions across requests.
Reads the
rh_authcookie (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
3. authCookieRemover
Handles the secure and explicit termination of authenticated sessions.
Clears the authentication cookie in response to a
POST /logoutrequest. This effectively logs out the user by wiping the authentication cookie from the user's browser, ensuring the session is securely terminated.Configuration
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.
1. Logging In
The user submits their credentials (username and password) via Basic Authentication (
Authorizationheader) from a form on a client application, which sends a GET request to the/roles/{username}endpoint, including the?set-auth-cookiequery parametersIf the credentials are valid, the server responds by setting an
rh_authcookie containing the authentication token and returns a success response.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.
2. Making Authenticated Requests
Once the cookie is set, the user can make subsequent requests to the server. The browser automatically includes the
rh_authcookie 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:
The server checks the cookie, validates the session, and if valid, responds with the requested data.
3. 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.
The server processes the logout request and clears the authentication cookie by setting its value to null
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.