The State Parameter

The state parameter is one of the supported Auth0 Authentication Parameters, used to help mitigate XSRF attacks.

A XSRF attack can occur when a malicious program causes a user's web browser to perform an unwanted action on a trusted site that the user is currently authenticated. This type of attack specifically target state-changing requests to initiate a type of action instead of getting user data because the attacker has no way to see the response of the forged request.

For the most basic cases the state parameter should be a nonce as shown in the example below. But this field can also be a Base64 encoded json object that can hold multiple values such as a return URL.

How to use the state parameter

By using the state parameter to hold a value for verification, malicious requests can be denied.

NOTE: Depending on the application type or framework this may be included for the developer. Also the exact structure of the requests may differ.

  1. Before redirecting a request to the IdP, have the client generate a random string.
xyzABC123
  1. Save this string to a variable in web storage.
auth0-authorize = xyzABC123
  1. Encode this value and set it as the state parameter in the request.
// Encode the String
var encodedString = Base64.encode(string);
tenant.auth0.com/authorize?...&state=encodedString
  1. After the request is sent, the user is redirected back to the client by Auth0. The state value will be included in this redirect. Note that depending on the type of connection used, this value might be in the body of the request or in the query string.
/login/callback?...&state=encodedString
  1. Decode the returned state value and compare it to the one you stored earlier. If the values match, then approve the request, else deny it.
// Decode the String
var decodedString = Base64.decode(encodedString);
if(decodedString == auth0-authorize) {
	// Authorized request
} else {
	// Request Denied
}

Further Reading

Protecting against other common threats

Using the state parameter for redirecting users