Implicit Grant (Deprecated)

LWA for Websites

STEP 1:
Register for LWA

→

STEP 2:
Add a LWA Button to Your Website

→

STEP 3:
Add the LWA SDK for JavaScript

→

STEP 4:
Implement Authorization Code Grant

→

STEP 5:
Dynamically Redirect Users

→

STEP 6:
Obtain Customer Profile Info

→

STEP 7:
Log Out Users

→

STEP 8:
Integrate with Your Account System

Note: To follow best practices, Implicit Grant is no longer supported. All new security profiles must use Authorization Code grant. For more information, refer to the Deprecation Notice.

An Implicit Grant allows a client (typically a website) to direct the user-agent (a user's browser) to a URI at Amazon. The user is then presented with a page asking to grant the website permission to their customer profile.

After the user approves the request, the user-agent is redirected back to the website using a URI that contains an access token in the URI fragment. The user-agent redirects to the client using a redirection URI without the access token fragment, but stores the access token fragment locally.

The user agent then processes a script on the website page that accesses the full redirection URI and passes the fragment information back to the client. For more details on the customer experience, see Authorization Grants.

Deprecation Notice
Deprecation FAQs
Authorization Request
Authorization Response
Authorization Errors
Verify Access Tokens
- Token Information Response

Deprecation Notice

To follow the latest OAuth 2.0 best practices, Login With Amazon no longer supports Implicit Grant for any new Security Profiles. All new integrations must use the Authorization Code grant. Existing Security Profiles using Implicit Grant will continue to work till April 30, 2021. They must migrate to Authorization Code grant by the deadline for better security.

Browser-Based Apps and Single-Page Apps, that cannot use a client_secret, must use the Authorization Code grant with PKCE extension.

Implicit grant returns the token in the URL, which makes it more susceptible to token leakages. For more information on why it is being deprecated, refer to OAuth 2.0 Implicit Grant. For any questions, please refer to the FAQs.

Deprecation FAQs

1. How do I know if I need to migrate?

You need to migrate if you are using Implicit Grant.

To check whether you're using Implicit Grant, look through your code and check the parameters in the Authorization Request. If the response_type parameter is set to code, you are not impacted. You are using Implicit Grant if the response_type parameter is token.

If you are using the LWA SDK for JavaScript, check the properties of the options input parameter to the authorize API. If response_type is set to code or if pkce is set to true, you are not impacted. You are using Implicit Grant if response_type is not defined, or it is set to token.

2. What is the risk with using Implicit Grant?

Implicit grant returns the token in the URL, which makes it more susceptible to token leakages. For more information on why it is being deprecated, refer to OAuth 2.0 Implicit Grant.

3. What happens if I don't migrate?

Due to security concerns, Login With Amazon will stop supporting Implicit Grant on April 30, 2021. After that, any Implicit Grant requests could fail. This can break the Login With Amazon Integration on your website.

4. What should I do?

You will have to update your code to start using the Authorization Code grant. This will not cause any change to the end user experience. Customers who have already authorized your app will not need to authorize again.

In Implicit Grant, the token is returned directly in the Authorization Request. In Authorization Code grant, the Authorization Request returns an Authorization Code which is then exchanged for a token by making a request to https://api.amazon.com/auth/o2/token. This extra call adds a layer of security.

If you are using the LWA SDK for JavaScript, the Authorization Code Grant page has code samples for Server apps and for Browser-Based Apps that you might find useful.

5. I only use Login With Amazon on mobile. Am I impacted?

If you are only using the Login With Amazon SDK for Android or iOS, then you are not using Implicit Grant and are not impacted.

Note: Login With Amazon usage on mobile web browsers or webviews could still be using Implicit Grant. We recommend checking the response_type parameter as mentioned in Q1.

6. I am using the Amazon Payments SDK. Am I impacted?

If you are using the Amazon Payments JavaScript SDK and request Payment scopes, you are not impacted and do not need to migrate.

You can confirm that you are using the Payments SDK by looking at the source URL of the SDK file. If it ends in Widgets.js, you are using the Payments SDK.

7. I still have questions. Who do I contact?

Please search the existing questions on the Developer Forums. If your query is still unanswered, please create a new forum post and we will get back to you shortly.

Authorization Request

To request authorization, the client (website) must redirect the user-agent (browser) to make a secure HTTP call to https://www.amazon.com/ap/oa with the following parameters:

Parameter	Description
`client_id`	REQUIRED. The client identifier . This is provided when you register your website as a client for Login with Amazon. Maximum size of 100 bytes.
`scope`	REQUIRED. The scope of the request. Must be `profile`, `profile:user_id`, `postal_code`, or some combination, separated by spaces (e.g. `profile%20postal_code`). For more information, see Customer Profile.
`response_type`	REQUIRED. The type of response requested. Must be `token` for this scenario.
`redirect_uri`	REQUIRED. The HTTPS address where the authorization service should redirect the user.
`state`	RECOMMENDED. An opaque value used by the client to maintain state between this request and the response. The authorization service will include this value when redirecting the user back to the client. It is also used to prevent cross-site request forgery. For more information, see Cross-site Request Forgery.

For example:

https://www.amazon.com/ap/oa?client_id=foodev
&scope=profile
&response_type= [Deprecated] token
&state=208257577110975193121591895857093449424
&redirect_uri=https://client.example.com/auth_popup/token 

To make an authorization request using the Login with Amazon SDK for JavaScript, you must fill out an options object, and call amazon.Login.authorize.

document.getElementById('LoginWithAmazon').onclick = function () {
  setTimeout(window.doLogin, l);
  return false;
};

window.doLogin = function () {
  options = {};
  options.scope = 'profile';
  amazon.Login.authorize(options, function (response) {
    if (response.error) {
      alert('oauth error ' + response.error);
      return;
    }
    amazon.Login.retrieveProfile(response.access_token, function (response) {
      alert(response);
    });
  });
};

The first parameter to amazon.Login.authorize is always the options object. The second parameter is either a JavaScript function to handle the authorization response, or a redirect URI to another page. The URI must belong to the same domain as the page calling the SDK, and it must be specified using HTTPS.

For example:

options = {};
options.scope = 'profile';
amazon.Login.authorize(options, 'https://mysite.com/redirect_here');

Note: If you would like to use the Login with Amazon SDK for JavaScript to request an Implicit Grant, you must first have your page load the Login with Amazon SDK for JavaScript. See Installing the JavaScript SDK.

After the user has either approved or denied the request, the authorization server will redirect the user to a redirect_uri. The client will then receive an Authorization Response (described below).

Authorization Response

After the client (website) directs the user-agent (browser) to make an Authorization Request, the authorization service will redirect the user-agent to a URI specified by the client. If the user granted the request for access, that URI will contain an access_token as a URI fragment. For example:

HTTP/1.1 302 Found
Location: https://client.example.com/cb#access_token=Atza|
IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR...

&state=208257577ll0975l93l2l59l895857093449424
&token_type=bearer
&expires_in=3600
&scope=profile

A successful response includes the following values:

Parameter	Description
`access_token`	The access token for the user account. Maximum size of 2048 bytes.
`token_type`	The type of token returned. Should be `bearer`.
`expires_in`	The number of seconds before the access token becomes invalid.
`state`	The `state` value passed in the authorization request. This value allows you to keep track of the user's state before the request. It is also used to prevent cross-site request forgery.
`scope`	The scope of the request. Must be `profile`, `profile:user_id`, `postal_code`, or some combination.

Note: Some user-agents do not support including a fragment component in the HTTP Location response header field. Those clients are not supported.

If you are using the Login with Amazon SDK for JavaScript, the above parameters are available in the response object provided by amazon.Login.authorize (an example is available in the Authorization Request section above).

Authorization Errors

If the user did not grant the request for access, or an error occurs, the authorization service will redirect the user-agent (a user's browser) to a URI specified by the client. That URI will contain error parameters detailing the error. For example:

HTTP/1.1 302 Found
Location: https://client.example.com/cb#error=access_denied
&state='208257577ll0975l93l2l59l895857093449424'

The error parameters for a failed authorization request include:

Error Parameter	Description
`error`	An ASCII error code with an error code value.
`error_description`	A human-readable ASCII string with information about the error, useful for client developers.
`error_uri`	A URI to a web page with human-readable information about the error, useful for client developers.
`state`	The client `state` passed in the original authorization request.

The following error codes can be returned as the value for error:

Error Code	Description
`invalid_request`	The request is missing a required parameter, has an invalid value, or is otherwise improperly formed.
`unauthorized_client`	The client is not authorized to request an authorization code.
`access_denied`	The resource owner or authorization server denied this request.
`unsupported_response_type`	The request specified an unsupported response type. For this scenario, the `response_type` must be `code`.
`invalid_scope`	The client requested the wrong scope.
`server_error`	The authorization server encountered an unexpected error (treat as a 500 Internal Server HTTP error).
`temporarily_unavailable`	The authorization server is currently unavailable due to a temporary overload or scheduled maintenance (treat as a 503 Service Unavailable HTTP error).

Verify Access Tokens

After you receive an access token using the implicit grant , it is highly recommended that you verify the authenticity of the access token before you retrieve a customer profile using that token. If a malicious site can induce a user to login, they can take the valid access token they receive and use it to mimic an authorization response to your site.

To verify a token, make a secure HTTP call to https://api.amazon.com/auth/O2/tokeninfo, passing the access token you wish to verify. You can specify the access token as a query parameter. For example:

https://api.amazon.com/auth/O2/tokeninfo?access_token=Atza|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR...

Note: Access tokens contain characters that are outside the allowed range for URLs. Therefore, you should URL encode access tokens to prevent errors. For more information, see Section 2.1 of RFC3986.

Token Information Response

If your access token is valid, you will receive the token information as an HTTP response in python. For example:

HTTP/1.1 200 OK
Date: Fri, 31 May 2013 23:22:10 GMT
x-amzn-RequestId: eb5be423-ca48-lle2-84ad-5775f45l4b09
Content-Type: application/python
Content-Length: 247
{
"iss":"https://www.amazon.com",
"user_id": "amznl.account.K2LI23KL2LK2",
"aud": "amznl.oa2-client.ASFWDFBRN",
"app_id": "amznl.application.436457DFHDH",
"exp": 3597,
"iat": l3ll280970,
}

Compare the aud value to the client_id you are using for your application. If they are different, the access token was not requested by your application, and you should not use the access token.

A successful response includes the following values:

Error Parameter	Description
`error`	An ASCII error code with an error code value.
`error_description`	A human-readable ASCII string with information about the error, useful for client developers.
`error_uri`	A URI to a web page with human-readable information about the error, useful for client developers.
`state`	The client `state` passed in the original authorization request.

The following error codes can be returned as the value for error:

Status Code	Error Code	Description
`200`	Success	Success
`400`	`invalid_request`	The request is missing a required parameter, has an invalid value, or is otherwise improperly formed.
`400`	`invalid_token`	The token provided is invalid or has expired.
`500`	`ServerError`	The server encountered a runtime error.

In addition to the error code, you may receive a python payload with more information. For example:

HTTP/1.1 400 Bad Request
Date: Fri, 31 May 2013 23:21:35 GMT
x-amzn-RequestId: d64bbdl4-ca48-lle2-a5dd-ab3bc3c93bae
Content-Type: application/python
Content-Length: 99
{
"error": machine-readable error code,
"error_description": human-readable error description,
}

Last updated: Oct 27, 2020