Login with Amazon Developer Guide for Websites

Login with Amazon Developer Guide for Websites

Login with Amazon: Developer Guide for Websites
Copyright © 2017 Amazon Services, LLC or its affiliates. All rights reserved.
Amazon and the Amazon logo are trademarks of Amazon.com, Inc. or its affiliates. All other trademarks not owned by Amazon are the property of their respective owners

Welcome

This is the Login with Amazon Developer Guide for Websites. This guide contains conceptual information about the Login with Amazon web service, as well as information about how to use Login with Amazon in your website.

Login with Amazon is a web service that enables Amazon customers to login to your website or mobile app using their Amazon credentials. Once they have logged in, your app can access some information from their Amazon profile.

How Do I…?

See the following table for links to information on how to work with Login with Amazon.

with Amazon
Learn how Login with Amazon works| Login with Amazon Conceptual Overview
Get started with Login with Amazon| Login with Amazon Getting Started Guide for Websites
Decide whether Login with Amazon is the right choice for my application| Using Login with Amazon
Get the FAQ| Login with Amazon Frequently Asked Questions
Get help from the community of developers| Login with Amazon Discussion Forums

Understanding Login with Amazon

Topics

• Login with Amazon Conceptual Overview
• Access Token
• Authorization Code
• Refresh Token
• Customer Profile
• Authorization Grants
• Client Application
• Client Identifier

Login with Amazon enables Amazon customers to use their trusted Amazon account to log into websites and mobile apps.

This section shows how Login with Amazon uses access tokens to allow websites to login customers and access their customer profiles

Login with Amazon Conceptual Overview

The conceptual overview describes how Login with Amazon allows a user to login and grant your website or access to their customer profile data. For more details on the customer experience in native mobile apps, including how your customers can skip the login screen and experience single sign-on, please see our Customer Experience Overview for Android/Fire apps, and our Customer Experience Overview for iOS apps.

The Login with Amazon process begins when a user visits your website or app (A). They click the Login with Amazon button (B) and get redirected to a login screen. Amazon provides pages (C) where the user logs in, then consents to allow your website access to their profile data. If they have already consented, they will only have to login. Amazon then redirects the user from the login screen to your website or app (D). Your website or app uses security credentials provided by Login with Amazon to access the customer profile (E) (including name and email address).

If a Login with Amazon app wants to identify a user without accessing their name and email address, they will not request profile data. In this case, the user is not presented with a consent screen after they log in.

Figure 1: Login with Amazon user flow
Login with Amazon works by providing third-party websites and mobile apps (clients) with a recognizable login button that users click to sign in with their Amazon credentials. To login, users are directed to amazon.com and asked to provide their Amazon password. For example:

Figure 2: Login with Amazon login screen
If this is the first time users have logged in from this website or app, Amazon presents them with a list of permissions requested by the client. Clients can request the name and email address of the user, and/or request the user’s postal (ZIP) code. For example:

Figure 3: Login with Amazon consent screen
After users log in, the client will use one of the authorization grants to get an access token. The client can then use the access token to access a customer profile, specifying an access scope.

Single Sign-On (SSO) for Web

The login screen for Login with Amazon client websites features a “Keep me signed in” checkbox. When a user checks this box, Login with Amazon will remember the credentials the user supplied as their login (for up to 14 days). When they visit another Login with Amazon website in the same browser, and choose to login, they will get a consent screen or an acknowledgement screen instead of a login screen.

If the website is requesting profile data that requires consent, after a user clicks the Login with Amazon button, they are redirected to a consent screen asking for permission to share their data. When the user clicks Okay, they are redirected back to the Login with Amazon client website.

If the website does not require consent, or a user has already consented, they are presented with an acknowledgement screen after clicking the Login with Amazon button. The acknowledgement screen shows the email address that Login with Amazon remembers, and asks them to confirm that they want to login using that account. When they click Continue, they are redirected to the Login with Amazon website.

The acknowledgement screen also gives a user the opportunity to logout of their current account and login again with different credentials. If a user enters a new account and checks the “Keep me signed in” checkbox again, the next time they see an acknowledgement screen it will feature the new account. This does not change their login on previous websites until the website tries to reauthorize the user.

If a user logs out of a website, it does not log them out of other Login with Amazon websites. The single sign-on feature is shared between Login with Amazon third-party websites and the Amazon.com retail site. Amazon.cn, Amazon.co.jp, and country-specific sites in the European Union have a “Keep me signed in” checkbox but do not participate in single sign-on.

Single Sign-On (SSO) for Mobile

Login with Amazon has implemented support for single sign-on on Kindle Fire, iOS and Android mobile devices.

Under single sign-on, when a user logs into an Amazon-branded app from an iOS or Android device, that login is automatically remembered. If the user opens another Amazon or Login with Amazon mobile app, the app will automatically log them in with the same account, without requiring them to enter any login credentials. On Kindle, Login with Amazon automatically uses the account registered to the device.

When the single-sign on feature is enabled on a device, Login with Amazon apps with an already signed- in account will keep using that account until the user logs out. For more details, please see our Customer Experience Overview for Android/Fire apps, and our Customer Experience Overview for iOS apps.

Access Token

After users log in, they are returned to your website or mobile app. At this point, your client can obtain an access token by calling the Login with Amazon authorization service. That token allows clients to access the customer’s name and email address from their customer profile.

When you are granted an access token, you may also receive a refresh token. A refresh token is valid for longer than an access token, and allows you to trade in the refresh token for a new access token and a new refresh token.

To access customer data, you must provide an access token to the Login with Amazon authorization service. An access token is an alphanumeric code 350 characters or more in length, with a maximum size of 2048 bytes.
Access tokens begin with the characters Atza|. Access tokens are only valid for sixty minutes and are specific to the user logging in and the data the app requested when it triggered the login. When you receive an access token, it is as a structure in JSON format with three pieces of information: the access_token, the token_type, and expires_in (the number of seconds before the token expires).These access tokens are bearer tokens, so the token_type is always bearer. For example:

{
“access_token”:”Atza|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR…”,
“token_type”:”bearer”,
“expires_in”:3600,
“refresh_token”:”AtzrIIQEBLzAtAhRPpMJxdwVz2Nn6f2y-tpJX2DeX…”
}

Access tokens are returned in both the Implicit and Authorization Codegrants.
An access token is a bearer token and as such can be used by another client. See The OAuth 2.0 Authorization Framework: Bearer Token Usage for more information.

Refresh Token

A refresh token allows a website to request a new access token, even if the access token has expired. Refresh tokens follow the same format as access tokens , except they begin with the string Atzr|. Refresh tokens are valid indefinitely, unless the user has removed the website or mobile app from the list of allowed apps for their account. Refresh tokens have a maximum size of 2048 bytes. A refresh token is specifically assigned to one client and cannot be used by another client.

Refresh tokens are returned only in the Authorization Code Grant.

Customer Profile

A customer profile contains the data that Login with Amazon applications can access regarding a particular customer. This includes: a unique ID for the user; the user’s name, the user’s email address, and their postal code. This data is divided into three scopes: _profile, profile:userid and _postalcode.

When you request an access token, you can request multiple access scopes by separating them with a space (e.g. _profile postalcode ). When your request is granted, it will specify the scope(s)returned.

profile

The profile scope includes a user’s name and email address. With access to the customer’s profile, you can uniquely identify them when they login, and you can communicate with them via email. The profile data is returned in JSON format and consists of three parts: the _userid, the email, and the name.
The _userid is assigned by Amazon, and uniquely identifies the user’s account. The email is the email address that they have registered with Amazon. Amazon does not verify this email address.

{
“email” : “johndoe@gmail.com”,
“name” : “John Doe”,
“user_id” : “amznl.account.K2LI23KL2LK2”
}

When a website or app requests access to the profile scope, the user will be presented with a consent screen the first time they login. The consent screen shows the information requested and their current values. The user must consent to share this information in order for login to complete. Once the user consents, that consent is recorded and future attempts to login with the same scope will not present a consent screen.

profile:user_id

The second access scope is _profile:user_id. profile:userid only includes the user_id field of the profile. This uniquely identifies the user but does not provide their name, email address, or postal code. Because no personal information is requested, the user will not be presented with a consent screen the first time they log in.

Every company that creates websites or apps for Login with Amazon gets the same _userid for a customer. However, when a customer logs in to another company’s app or site, the _userid will be different. This is so _userid cannot be used to track customers across the Web.

postal_code

The third access scope is the _postalcode scope. This includes the user’s zip/postal code number from their primary shipping address. The postal code provides valuable location data that allows you to tune your offerings and understand your customers better. For example:

{
“user_id” : “amznl.account.K2LI23KL2LK2”
“email” : “johndoe@gmail.com”,
“name” : “John Doe”,
“postal_code”: “98l0l”,
}

When an app requests access to the _postalcode scope, alone or in concert with the profile or _profile:userid scope, the user will have to consent to share the information.

Authorization Grants

The Login with Amazon authorization service offers two authorization grants that your website or mobile app can use to authenticate users and access their customer profile. These two grants are the Implicit Grant and the Authorization Code Grant.

The following grant descriptions are in terms of HTTP requests and responses. The mobile SDKs wrap these calls in their own methods and callbacks; however, the overall flow is the same.

Implicit Grant

In the Implicit Grant, a user clicks on a link (or presses a button) (A) that directs them to an Amazon login page. After they login, they are asked to grant an app access to specific profile data (B) and are redirected back to the app. If the user is granted access, an access token is embedded directly in the redirection URI as a URI fragment (C). (This is the implicit grant). The URI fragments, including the access token, are stripped from the redirection URI by the user-agent (the web browser) and the user-agent executes the URI (D). (At this point, the user sees they are logged in to the client and continues using the app normally.) The client website retrieves the access token by using browser-based scripting (e.g. JavaScript) to query the user- agent for the fragments (E). That script can then send the access token to the client (F), or use the access token directly to retrieve the customer profile data from Amazon (G).

Authorization Code Grant

In the Authorization Code Grant, a user clicks on a link (or presses a button) (A) that directs them to an Amazon login page. After they login, they are asked to grant an app access to specific profile data (B) and are redirected back to the app. An authorization code is embedded directly in the redirection URI as a query parameter (C) (this is authorization code grant). The user-agent executes the URI, including the query parameters (at this point, the user sees they are logged in to the app and continues normally). The query parameters are processed directly by the app, and the app uses the authorization code to request an access token directly from the authorization service (D). The authorization code must be paired with a client identifier and client secret, known only to the app. This prevents malicious software from intercepting the authorization code and impersonating thea pp.

Once the authorization code, client identifier and client secret are verified, the app is granted an access token and a refresh token from the authorization service (E). They can use the access token to access the customer profile data from Amazon. When the access token expires, they can use the refresh token to gain a new access token and a new refresh token.

Client Application

Before you can use Login with Amazon on a website or in a mobile app, you must register an application with Login with Amazon. Your Login with Amazon application is the registration that contains basic information about your business, and information about each website or mobile app you create that supports Login with Amazon. This business information is displayed to users each time they use Login with Amazon on your website or mobile app. Users will see the name of your application, your logo, and a link to your privacy policy. To create an application, clients must supply the following:

• Name. This name will be displayed on the consent screen when a user is asked to give your website or mobile app permission to access their profile It also appears on the list of active Login with Amazon clients in the Your Account section for Amazon users.
• Description. The description helps you differentiate each of your Login with Amazon applications and is not displayed to users.
• Privacy Notice URL. The Privacy Notice URL is the location of your company or application’s privacy policy (for example: http://www.example.com/privacy.html). This link is displayed to users on the consent

Clients may also supply the following:

• Logo Image File. This logo is displayed on the sign-in and consent screen when users log into your website or mobile app. The logo will be shrunk to 50 pixels in height if it is taller than 50 pixels; there is no limitation on the width of the The following formats are accepted: PNG, JPEG,and GIF.

After creating an application, you can register each website or mobile app that will use Login with Amazon.

For more information, including registration for individual websites, see Register your Login with Amazon Application.

Client Identifier

When clients create a website or mobile app, they are assigned a client identifier and a client secret. Client identifiers and client secrets are assigned in pairs. An app can have multiple client identifiers.

The client identifier is used to identify your app, either alone or along with the client secret. Both authorization grants use the client identifier, but the Authorization Code Grant requires the client secret as well.

The client identifier has a maximum size of 100 bytes. The client secret has a maximum size of 64 bytes.

Using Login with Amazon

Topics

• Register with Login with Amazon
• Set up your Website
• Choose an Authorization Grant
• The Implicit Grant
• The Authorization Code Grant
• Use Access Tokens to Read a Customer Profile
• Log Out Users

Login with Amazon enables Amazon customers to use their trusted Amazon account to log into websites and mobile apps.

This section discusses how to use Login with Amazon, from creating your application to setting up your website, choosing an authorization grant, and implementing that grant. Once the protocol is implemented, users can login to your site using Login with Amazon and grant you access to their customer profile data.

Register with Login with Amazon

Before you can use Login with Amazon on a website or in a mobile app, you must register an application with Login with Amazon. Your Login with Amazon application contains information about your business, and information about each website or mobile app you create that supports Login with Amazon. The business information is displayed to users each time they use Login with Amazon on your website or mobile app. Users will see the name of your application, your logo, and a link to your privacy policy. These steps demonstrate how to register a Login with Amazon application:

Register Your Login with Amazon Application

1. Go to https://login.amazon.com.
2. If you have signed up for Login with Amazon before, click App Console. Otherwise, click Sign Up. You will be redirected to Seller Central, which handles application registration for Login with Amazon. If this is your first time using Seller Central, you will be asked to set up a Seller Central
3. Click Register New Application. The Register Your Application form will appear:

a. In the Register Your Application form, enter a Name and a Description for your application.
The Name is the name displayed on the consent screen when users agree to share information with your application. This name applies to Android, iOS, and website versions of your application. The Description helps you differentiate each of your Login with Amazon applications and is not displayed to users.
b. Enter a Privacy URL for your application now.
The Privacy Notice URL is the location of your company or application’s privacy policy (for example:
http://www.example.com/privacy.html). This link is displayed to users on the consent screen.
c. If you want to add a Logo Image for your application, click Choose File and locate the applicable image.
This logo is displayed on the sign-in and consent screen when users log into your website or mobile app. The logo will be shrunk to 50 pixels in height if it is taller than 50 pixels; there is no limitation on the width of the logo. The following formats are accepted: PNG, JPEG, GIF.

4. Click Save. Your sample registration should look similar to this:
   
   After your basic application settings are saved, you can add settings for specific websites and mobile apps that will use this Login with Amazon account.

Add Web Settings to your Application

1. From the Application screen, click Web Settings. You will automatically be assigned values for Client ID and Client Secret. The client ID identifies your website, and the client secret is used in some circumstances to verify your website is authentic. The client secret, like a password, is confidential. To view the client secret, click Show Secret.

2. To add Allowed JavaScript Origins or Allowed Return URLs to your application, click Edit.
   Note: To use Login with Amazon with a website, you must specify either Allowed JavaScript Origins or Allowed Return URLs. Specify Allowed JavaScript Origins to provide a popup authentication experience to your users, or Allowed Return URLs to provide a redirect authentication experience. If you are using Amazon Pay, you must specify Allowed JavaScript Origins.
   
   a. If you’re providing a popup authentication experience for your users, add your website origin to
   Allowed JavaScriptOrigins.
   An origin is the combination of protocol, domain name and port (for example: https://www.example.com:8443). Allowed origins must use the HTTPS protocol. If you are using a standard port (port 80 or port 443) you need only include the domain name (for example: https://www.example.com).
   Adding your domain here allows the SDK for JavaScript to communicate with your website directly during the login process. Web browsers normally block cross- origin communication between scripts unless the script specifically allows it.
   To add more than one origin, click Add another.
   b. If your website will be making HTTPS calls to the Login with Amazon authorization service and
   specifying a _redirecturi for replies, add those redirect URIs to Allowed Return URLs.
   The return URL includes the protocol, domain, path, and query string(s) (for example, https://www.example.com/login.php).
   To add more than one return URL, click Add another. If you’d like to dynamically redirect users to different URLs after authentication (for example: if you’d like to redirect each user back to the page they were on prior to logging in) you won’t need to list them all here. Instead, initially redirect all users to one static URL (the Allowed Return URL). In your authorization request, assign a dynamic value to the state parameter and use that value to create a second redirect to the desired URL. For more information, see Dynamically Redirecting Users.
   Note: Redirecting users to a new page for authentication leaves them vulnerable to cross-site request forgery. To secure your app, we strongly recommend using the state parameter to validate each authorization response. For more information, see Cross-site Request Forgery.

3. Click Save.

Set up your Website

There are a few steps you should take before going live with Login with Amazon on your website. This includes loading the Login with Amazon SDK for JavaScript, adding Login  with Amazon graphics, and integrating new Amazon customers into your accounts database.

Load the Login with Amazon SDK for JavaScript

Login with Amazon provides a JavaScript SDK that you may use to obtain access tokens and retrieve customer profiles. Before you can make an access grant call or retrieve a profile, the SDK must load itself from Amazon’s content delivery network. To load the SDK, use the following cod

<div id “amazon-root”>