Integrating token-based Cross-Site Request Forgery (CSRF) protection

Perform six steps to integrate token-based Cross-Site Request Forgery (CSRF) protection.

For information about enabling token-based CSRF protection, see the Enabling token-based Cross-Site Request Forgery (CSRF) protection related link.

The following list outlines the steps for client integration with token-based CSRF protection:
  1. The system authenticates the user. Only authenticated users can access REST resources.
  2. The client acquires a new CSRF token from the server by calling the REST endpoint baseURL/v1/csrf/tokens. The server generates a new, unique CSRF token and sends the token to the client in a custom HTTP response header. The header name is X-IBM-SPM-CSRF.
  3. The client retrieves the CSRF token from the custom header. The CSRF token is stored in the client. The CSRF token is required for any later REST API calls.
  4. The client must send a valid token with every API request. The token is sent in a custom request HTTP header. The name of the custom header is X-IBM-SPM-CSRF.
  5. When the server receives a client request, the CSRF token is removed from the request header and is validated by the server. If the CSRF token is valid, then the request is marked as valid and the request continues. If the CSRF token is not valid, the request is blocked and a 403 forbidden HTTP status code is returned. The following JSON response object with the error message and code is returned in the message body: 
    
 {
  “errors”: [
   {
	“code”: -150220,
	“message”: “The request is forbidden as the specified token is not allowed”,
	“level”: “error”
    }
  ]
}
  6. The token is valid for the duration of the session. If the session is invalidated for any reason, the client must repeat the preceding steps to get a new CSRF token before the client makes any new API calls. The client must update its local store with the new token.