The state parameter is used to prevent cross-site request forgery (CSRF) attacks against the redirection URI. It is used to link the request with the response delivered on the redirect URI. The state token should be set to a unique value in time. Uniqueness is required to prevent potential replay attacks of the authorization request.
In some cases, like when your buyers are using a mobile device, you want to redirect buyers to the Amazon authentication page within the same window, rather than presenting the buyer with a pop-up window.
This section covers the following information:
Changes you need to make to your website to enable redirect authentication
Cross-site request forgery happens when an attacker tricks a user into clicking a malicious link, where the link goes to a site where the user is authenticated. Any commands embedded in the malicious link might be executed automatically because the user is already authenticated on the site, so the user does not see a login screen or any other evidence of malicious activity. In the case of Login with Amazon, cross-site request forgery could be used to mimic a client or an authentication server.
When a client registers for Login with Amazon, they are assigned a client identifier (client_id) and a client secret (client_secret). The client verifies their identity by using the client_id and client_secret parameters in access token requests (these values would have to be forged by an attacker).
Login with Amazon also uses the State parameter to prevent cross-site request forgery. The client sets the value of the State parameter when it initiates an authorization request. Unlike the client_id and client_secret values, the State value can and should be different for each authorization request. The authorization server returns the same value when communicating with the client to deliver authorization codes and access tokens. If the State parameter doesn't match the value from the initial call, the communication should be ignored. For more information about the state parameter and its use, see Cross-site request forgery in the Login with Amazon documentation.
Clients can calculate the State value in any way they choose, but you should ensure that the value is secure from forgery. Login with Amazon recommends using Hash-based Message Authentication Code (HMAC) to calculate State values. HMAC methodology is detailed in RFC2104. For more information, see RFC2104.
To calculate a State value using this method, you must have a csrf_secret known only to the client and an authenticator message. The State value is calculated as HMAC(csrf_secret, authenticator). The authenticator value is then stored by the client.
When the state is returned by an authorization response, you can verify the state by retrieving the authenticator value and running the HMAC(csrf_secret, authenticator) calculation again. If the values do not match, you should ignore the authorization response.
The first time a buyer signs in and is authenticated on your website, they must give their consent to share their Amazon Pay profile information with you. If, during a redirect authentication, a buyer clicks the Cancel button on the consent screen and denies you consent, Amazon Pay forwards the buyer to the redirect URL, but instead of passing back an AccessToken, an error description is returned.
Note that an AccessToken is returned in the URL Fragment, where an error description is returned via a query string. Before rendering the redirect URL, you need to check for a query string with an error description and, if found, redirect the buyer to the page where the login process was initiated.
The following example shows a URL fragment where the buyer gave their consent to share their Amazon Pay profile information with you.
The following example shows an error description returned in the query string when a buyer declines to share their profile information with you.