Login with Amazon. Developer Guide API Version

Transcription

1 Login with Amazon Developer Guide API Version

2 Login with Amazon: Developer Guide Copyright 2013 Amazon Services, LLC or its affiliates. All rights reserved. The following are trademarks or registered trademarks of Amazon: Amazon, Amazon.com. In addition, Amazon.com graphics, logos, page headers, button icons, scripts, and service names are trademarks, or trade dress of Amazon in the U.S. and/or other countries. Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be affiliated with, connected to, or sponsored by Amazon.

3 Welcome... 1 Understanding Login with Amazon... 2 Features... 2 Login with Amazon Conceptual Overview... 3 Access Token... 5 Refresh Token... 6 Customer Profile... 6 Authorization Grants... 7 Implicit Grant... 7 Authorization Code Grant... 8 Client Applications... 9 Client Identifiers Using Login with Amazon Creating a New Application Setting Up Your Website Choosing an Authorization Grant Using the Implicit Grant Authorization Request Authorization Response Authorization Errors Using the Authorization Code Grant Authorization Request Authorization Response Access Token Request Access Token Response Access Token Errors Using Refresh Tokens Using Access Tokens to Read a Customer Profile Customer Profile Response Security Considerations Cross-site Request Forgery Client Secret Rotation Open Redirectors Code Injection Handling Customer Data Known Issues Glossary Index

4 How Do I...? Welcome This is the Login with Amazon Developer Guide. This guide contains conceptual information about the Login with Amazon web service, as well as information about how to use the service to allow Amazon customers to login to your website. Login with Amazon is a web service that enables Amazon customers to login to your website using their Amazon credentials and grant your site access to information from their Amazon profile. How Do I...? See the following table for links to information on how to work with Login with Amazon. How Do I... Learn more about the business case for Login with Amazon Learn how Login with Amazon works Get started with Login with Amazon Decide whether Login with Amazon is the right choice for my website Get the technical FAQ Get help from the community of developers Relevant Resources Understanding Login with Amazon Identity By Amazon Conceptual Overview Login with Amazon Getting Started Guide Using Login with Amazon Login with Amazon Frequently Asked Questions Login with Amazon Discussion Forums 1

5 Features Understanding Login with Amazon Topics Features (p. 2) Login with Amazon Conceptual Overview (p. 3) Login with Amazon enables Amazon customers to use their trusted Amazon account at participating web sites across the Internet. As a developer or web site owner, Login with Amazon offers you the following benefits: Increased login rate and reduced abandonment, leading to increased satisfaction and retention for your customers. Reduced infrastructure and operational costs, by outsourcing user authentication to Amazon. Increased customer trust, by combining the strength of Amazons brand with yours. Features Login with Amazon offers several features that help you manage customer login. Trusted Login. Customers can choose to Login with Amazon, using their Amazon credentials to gain access to your web site. Profile Information. Customers can choose to share information from their Amazon account with your web site, such as name and address. Over time, we ll add to the list of ways to interact with Amazon customers via Login with Amazon. Privacy Control. Login with Amazon handles the burden of managing customer consent, ensuring that information is only shared with the customer s explicit agreement. Standards-based Technology. 2

6 Login with Amazon Conceptual Overview Login with Amazon is based on OAuth 2.0, which has been broadly adopted for user-authorized exchanges across sites. This includes support for both Authorization Code and Implicit grant types. Javascript SDK Login with Amazon provides a Javascript SDK that enables developers to quickly and simply authorize users. Login with Amazon Conceptual Overview Topics Access Token (p. 5) Refresh Token (p. 6) Customer Profile (p. 6) Authorization Grants (p. 7) Client Applications (p. 9) Client Identifiers (p. 10) All Login with Amazon applications use the same broad steps to allow a user to login and grant the website access to their customer profile data. 3

7 Login with Amazon Conceptual Overview Login with Amazon works by providing third-party websites with a recognizable login button that users click to login with their Amazon credentials. To login, users are redirected to amazon.com. and asked to provide their Amazon password. For example: 4

8 Access Token If this is the first time users have logged in from this site, Amazon presents them with a list of permissions requested by the website. Websites can request the name and address of the user, and/or request the user's postal (zip) code. For example: After users log in, the client website will use one of the Authorization Grants to get an Access Token. The website can then use the Access Token to access a Customer Profile, specifying an access scope. Access Token After users login, they are redirected to your website. At this point, your website will obtain an access token by calling the Login with Amazon authorization service. That token allows websites to access the customer's name and address from Amazon. 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 refresh your access token by trading 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 between 18 and 128 characters in length. Access tokens are only valid for fifteen minutes and are specific to the user logging in and the data requested. When you request an access token, you get 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":"2yotnfzfejr1zcsicmwpaa", "token_type":"bearer", "expires_in":900, 5

9 Refresh Token "refresh_token":"tgzv3jokf0xg5qx2tlkwia" } Access tokens are returned in both the Implicit and Authorization Code grants. 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 after the access token has expired. Refresh tokens follow the same format as access tokens. Refresh tokens last indefinitely, unless the user has removed the website from their list of allowed websites on amazon.com. 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 is the data you can request from Amazon includes a user's name, address, and postal code. This data is divided into two access scopes: profile and postal_code. profile The profile scope includes a user's name and address. With access to the customer's profile, you can uniquely identify them when they login and communicate with them via . The profile data is returned in JSON format and consists of three parts: the CustomerID, the Primary , and the Name. For example: "Profile": { "CustomerID": amzn1.user.k2li23kl2lk2, "Primary ":johndoe@gmail.com, "Name" : "Mr. John Doe" } The CustomerID is used by Amazon to identify the user's account. The Primary is the primary address that they have registered with Amazon. postal_code The second access scope is the postal_code scope. This includes the user's zip/postal code number. The postal code provides valuable location data that allows you to tune your offerings and understand your customers better. TODO: postal_code example When you request customer profile data, you can request multiple access scopes by separating them with a space or a plus sign (e.g. profile+postal_code). When your request is granted, it will specify the scope(s) returned. 6

10 Authorization Grants Authorization Grants The Login with Amazon authorization service offers two authorization grants that your website can use to authenticate users and access their customer profile. These two grants are the Implicit Grant and the Authorization Code Grant. Implicit Grant In the Implicit Grant, a user clicks on a link (A) where they are asked to grant a client website access to specific profile data. If the user grants this access, they login to Amazon (B) and are redirected back to the client website. 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 website and continues browsing 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). 7

11 Authorization Grants Authorization Code Grant In the Authorization Code Grant, a user clicks on a link (A) where they are asked to grant a client website access to specific profile data. If the user grants this access, they login to Amazon (B) and are redirected back to the client website. An authorization code is embedded directly in the redirection URI as a query parameter (C). (This is the 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 client website and continues browsing normally.) The query parameters are processed directly by the client website, and the client website uses the authorization code to request an access token directly from the authorization service (D). The client 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. 8

12 Client Applications Client Applications Before using Login with Amazon, clients must create a new Login with Amazon application using Seller Central at To create an application, clients must supply the following: Application Display Name. This name will be displayed on the consent screen when a user is asked to give your application permission to access their profile. It also appears on the list of active Login with Amazon websites in the Your Account section for Amazon users. Privacy Notice URL.This is a link that users can click to access your Privacy Notice (or Privacy Policy). It is also displayed on the consent screen. Logo Image File. This logo is displayed on the consent screen to represent your business or website. Website Redirect URL(s). When a user clicks the Login with Amazon button on your website, they will be directed to Amazon.com. That request will include a redirect URL to direct the user back to your website when they have logged in. If the redirect URL on the request does not match one of the redirect URLs registered with your application, the request will fail. For more information, see Creating a New Application. 9

13 Client Identifiers Client Identifiers When clients create an application, they are assigned a client identifier and a client secret. Client identifiers and client secrets are assigned in pairs. An application can have multiple client identifiers. The client identifier is used to identify your client application, 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. For security reasons, you should periodically create a new client identifier and remove the old one. See Client Secret Rotation. 10

14 Creating a New Application Using Login with Amazon Topics Creating a New Application (p. 11) Setting Up Your Website (p. 13) Choosing an Authorization Grant (p. 16) Using the Implicit Grant (p. 16) Using the Authorization Code Grant (p. 20) Using Access Tokens to Read a Customer Profile (p. 25) 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. Creating a New Application The first step in using the Login with Amazon authorization service is to create a new Login with Amazon application on the Seller Central website. The Login with Amazon application contains business and technical information about your Login with Amazon account. The business information is displayed to Login with Amazon users when they are presented with login and consent forms. This includes the name of your business, your logo, and a link to your privacy policy. The technical information is used by Login with Amazon to ensure that incoming requests are returning to a pre-approved URL. This is a security feature to prevent attackers from imitating a valid request but capturing the return values on their own site. In this section, we show you how to create an Login with Amazon application. By the end of this section, you will have: A registration with Login with Amazon. A shared secret value that you will use when calling the Login with Amazon authorization service. Creating a Login with Amazon Application To create an Login with Amazon application, you must have a Seller Central account, and have added Login with Amazon to your account. For more information on how to do that, visit 11

15 Creating a New Application 1. On the Seller Central main screen, you will see a Create New Application button in the center of the page if you have not created an Login with Amazon application before. Otherwise, this button will appear on the right side of the page. Click the button to being creating a new Login with Amazon application. 2. On the Create Login with Amazon Application screen, enter the following the business information: a. Enter an Application Display Name. This name will be displayed on the consent screen when a user is asked to give your application permission to access their profile. It also appears on the list of active Login with Amazon websites in the Your Account section for Amazon users. b. Enter a Privacy Notice URL. This is a link that users can click to access your Privacy Notice (or Privacy Policy). It is also displayed on the consent screen. This URL must start with or c. Upload a Logo Image File. This logo is displayed on the consent screen to represent your business or website. The logo will be displayed as a 150x150 pixel image; if you upload a file of a different size it will be scaled to fit. 3. On the same screen, enter the Website Redirect URLs for your application. When a user clicks the Login with Amazon button on your website, they will be directed to Amazon.com. That request will include a Redirect URL to direct the user back to your website when they have logged in. If the Redirect URL on the request does not match one of the Redirect URLs registered with your application, the request will fail. Redirect URLs must start with You will be able to update this information later if you choose (for example, to add redirect URLs). 4. Once you have entered the information, click Save to save the application. Once you have created an Login with Amazon application, you will be assigned a client identifier and a client secret. Both of these values are used when your website calls Login with Amazon to get user consent or access user data. To view or edit these values, edit your Login with Amazon application. 12

16 Setting Up Your Website Editing your Login with Amazon application Once you have created an Login with Amazon application, you can change the settings at any time through Seller Central by clicking the View/Edit settings button. 1. From the Seller Central main screen, select your Login with Amazon application and choose View/Edit application settings. The View/Edit Application popup appears, allowing you to change values you previously entered, as well as view and reset your client identifier and client secret. 2. To change your business or technical information, edit the information and click the Save button. 3. To view your client secret, click Show under Client Secret. Setting Up Your Website There are a few steps you should take, and issues you should consider, before going live with Login with Amazon on your website. This includes loading the Javascript SDK, adding Login with Amazon graphics, and integrating new Amazon customers in your accounts database. Topics Loading the Javascript SDK (p. 13) Adding a Login with Amazon Button (p. 14) Making Database Changes (p. 15) Handling Authentication Responses (p. 15) Verifying the Response (p. 15) Find or Create a Local Account (p. 15) Mark the User as Authenticated (p. 15) Password reset pages (p. 16) Loading the Javascript SDK Login with Amazon provides an optional Javascript SDK that you can 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 code: <div id="amazon-root"></div> <script type="text/javascript"> window.onamazonloginready = function() { amazon.login.setclientid('your-client-id'); }; (function(d) { var a = d.createelement('script'); a.type = 'text/javascript'; a.async = true; a.id = 'amazon-login-sdk'; a.src = ' d.getelementbyid('amazon-root').appendchild(a); })(document); </script> Once the SDK has loaded, it will call window.onamazonloginready for initialization. Before using the SDK, you must call amazon.login.setclientid, passing your client identifier. If you do not know your client identifer, see Creating a New Application. 13

17 Adding a Login with Amazon Button The amazon-root tag The Javascript SDK requires the amazon-root element to be present in the page. The amazon-root element must not be hidden using display: none or visibility: hidden, or some parts of the SDK will not work property in Internet Explorer. The SDK inserts elements into amazon-root that expect to be positioned relative to the body or relative to an element close to the top of the page. It is best if the amazon-root element is not inside an element with position: absolute or position: relative settings. If you must place the amazon-root element inside of a positioned element, you should give it a position close to the top of the body or some parts of the SDK may not work properly. Adding a Login with Amazon Button Login with Amazon provides standard button graphics for the login button, as outlined in the table below. We encourage you to load the button graphic directly from our servers rather than hosting your own copy. We may change the button in the future and by loading the image from our servers the button would automatically be updated on your website. If you do load the graphics from our servers, please note that the HTTP and HTTPS URLs link to different servers. For HTTP links, use as your server. For example, For HTTPS links, use as your server. For example, Login with Amazon button graphics Image Location /images/g/01/iba/assets/images/loginwithamazon_gold_m.jpg /images/g/01/iba/assets/images/loginwithamazon_gold_m.png /images/g/01/iba/assets/images/loginwithamazon_gold_l.jpg /images/g/01/iba/assets/images/loginwithamazon_gold_l.png /images/g/01/iba/assets/images/loginwithamazon_tan_m.jpg /images/g/01/iba/assets/images/loginwithamazon_tan_m.png /images/g/01/iba/assets/images/loginwithamazon_tan_l.jpg /images/g/01/iba/assets/images/loginwithamazon_tan_l.png File size and type 137x24 JPG 137x24 PNG 165x27 JPG 165x27 PNG 137x24 JPG 137x24 PNG 165x27 JPG 165x27 PNG You should use these buttons without any modification. If you have a use case where the buttons we have provided do not fit, please contact us at <lwa-support@amazon.com> and we will work with you to find a solution. 14

18 Making Database Changes The Login with Amazon button should be placed wherever a login to your site is offered. This includes where you sign up new customers as well as the login prompt for existing customers. For ALT text, use "Login with Amazon". Making Database Changes You will need to modify your account database to record a mapping between Amazon account identifiers and your local accounts. This could take the form of a new field in your account table or a table that maps between Amazon account identifiers and your local account identifiers. Amazon account identifiers are returned as the CustomerID property, in the form amzn1.user.value. For example: amzn1.user.k2li23kl2lk2 Handling Authentication Responses When you receive an authentication response from Login with Amazon you should do the following: Verify the response to ensure that it was generated by Amazon and not intercepted or tampered with. Search for the user's Amazon identity within your user database to see if they have signed in before. If they have not, you will need to create a new account for them. Create cookies in the user's browser or otherwise record them as authenticated with your site. Verifying the Response When the user is redirected to your site after logging in, you cannot assume their authentication response is valid. The user can tamper with the return URL, or replay an old authentication response. One way to verify the authentication response is via the state parameter. See Cross-site Request Forgery for more information. Find or Create a Local Account The customer profile contains a value named CustomerID. This string permanently and uniquely identifies the Amazon account for the user. Amazon will always return this value for this user. You should search your database to see if this Amazon account has logged into your site before. If it has not, you should create a new entry in your account database and associate it with the Amazon customer ID for the next time they log in. The customer profile contains additional data, such as their address and location. You may copy this information into your account database as well when creating a new account or updating existing accounts. For example, if the user has changed their address since their last login. If you want to collect additional information from the user before creating an account, you will want to present a registration page.you can prefill the page with information you've already received from Amazon. Mark the User as Authenticated Once you have created or verified the user's local account, you can mark the user as authenticated. For example, you can set a cookie in their browser. This step can work exactly the same way as your current authentication system. 15

19 Password reset pages Password reset pages If your website's local account management includes resetting passwords, you may want to ensure that Login with Amazon users aren't confused about how that effects their Amazon account. That could mean hiding a "Reset Password" link if users are logged in via Login with Amazon; or a note on the password reset page directing them to if they want to change their password. Choosing an Authorization Grant The two mechanisms websites can use to obtain access tokens are the Implicit Grant and the Authorization Code Grant. Both authorization grants work by redirecting the user-agent (the user's browser) to Amazon.com for them to login. Once they have logged in, if the website requested an implicit grant, the access token is embedded as a fragment in a URI that redirects the user-agent back to the client website. The website then uses a script to obtain the data from the user-agent. If the website requests an authorization code, the user-agent is redirected back to the website and the authorization code is passed as a query string in that URI. The website then makes a secure HTTP call to Amazon behind the scenes to exchange the authorization code for an access token. Before you implement a Login with Amazon application, you must choose which authoriziation grant you will use. Which Grant Type is Right for Your Application? In general, the advantages of one authorization grant mirror the disadvantages of the other grant. The advantage of the authorization code grant is that it is more secure than the implicit grant. The user is not involved in the request for the access token, as that takes place directly between the client website and the authorization service. The authorization code grant also features refresh tokens, which gives the client website almost indefinite access to the customer profile data. The disadvantage to the authorization code grant is that it is harder to implement, and relies on server-side scripting. The authorization code grant also uses more round trips than the implicit grant. The advantage of the implicit grant is that it is relatively simple to implement, as it relies on the web browser to receive and store the access token. In fact, if the client architecture does not support server-side scripting, this is the only authorization grant that will work with the Login with Amazon authorization service. The implicit grant also makes fewer round trips than the authorization code grant. The disadvantage of the implicit grant is that because the user's browser makes the access token request, the user is exposed to the access token. From a strict security perspective, it is better to conceal this information. Also, in the implicit grant, when an access token expires, the user must re-authenticate to continue accessing the resources. The authorization code grant features refresh tokens that can be used to obtain a new access token without involving the user. If you cannot use server-side scripting, the implicit grant is your only choice. If you can use server-side scripting, we recommend choosing the authorization code grant over the implicit grant. Using the Implicit Grant Topics Authorization Request (p. 17) Authorization Response (p. 18) 16

20 Authorization Request Authorization Errors (p. 19) 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. Once 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, but stores the access token locally. The user-agent then processes a script on the website page that access the full redirection URI and passes the fragment information back to the client. For more information, see Implicit Grant. Authorization Request To request authorization, the client (website) must redirect the user-agent (browser) to make a secure HTTP call to with the following parameters: Parameter client_id scope response_type redirect_uri state Description REQUIRED. The client identifier. This is set when you register your website as a client. REQUIRED. The scope of the request. Must be profile, postal_code, or both, separated by a space or a plus sign (e.g. profile%20postal_code or profile+postal_code). For more information, see Customer Profile. REQUIRED. The type of response requested. Must be token for this scenario. OPTIONAL. The HTTP address where the authorization service should redirect the user. 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: &scope=profile &response_type=token &state= &redirect_uri= To make an authorization request using the Javascript SDK, you must fill out an options object, and call amazon.login.authorize. <script type="text/javascript"> document.getelementbyid('loginwithamazon').onclick = function() { settimeout(window.dologin, 1); return false; }; 17

21 Authorization Response 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('hello, ' + response.profile.name); alert('your address is ' + response.profile.primary ); alert('your unique ID is ' + response.profile.customerid); if ( window.console && window.console.log ) window.console.log(response); }); }); }; </script> 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, ' Note If you would like to use our Javascript SDK to request an Implicit grant, you must first have your page load the Javascript SDK. See Loading the Javascript SDK. Once the user has either approved or denied the request, the authorization server will redirect the user to the redirect_uri. The client will then receive an Authorization Response. 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/ Found Location: &state= &token_type=bearer &expires_in=3600 &scope=profile A successful response includes the following values: 18

22 Authorization Errors Parameter access_token token_type expires_in state scope Description The access token for the user account. The type of token returned. Should be bearer. The number of seconds before the access token becomes invalid. 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. For more information see Cross-site Request Forgery. The scope of the request. Should be profile, postal_code, or both. This can differ from the requested scope. 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 Javascript SDK, the above parameters are available in the response object provided by amazon.login.authorize. See Authorization Request for an example. Once you have obtained an access token, the next step is to use it to read a customer profile. See Using Access Tokens to Read a Customer Profile. Authorization Errors If the user did not grant the request for access, or some other error occurs, the authorization service will redirect the user-agent to a URI specified by the client. That URI will contain error parameters detailing the error. For example: HTTP/ Found Location: &state= The error parameters for a failed authorization request include: Error Parameter error error_description error_uri state Description An ASCII error code with an error code value. A human-readable ASCII string with information about the error, useful for client developers. A URI to a web page with human-readable information about the error, useful for client developers. The client state passed in the original authorization request. If you are using the Javascript SDK, the above parameters are available in the response object provided by amazon.login.authorize. See Authorization Request for an example. The following error codes can be returned as the value for error: 19

23 Using the Authorization Code Grant Error Code invalid_request unauthorized_client access_denied unsupported_response_type invalid_scope server_error temporarily_unavailable Description The request is missing a required parameter, has an invalid value, or is otherwise improperly formed. The client is not authorized to request an authorization code. The resource owner or authorization server denied this request. The request specified an unsupported response type. For this scenario, the response_type must be code. The client requested the wrong scope (it must be set to profile, postal_code, or both.). The authorization server encountered an unexpected error. (Treat as a 500 Internal Server HTTP error). The authorization server is currently unavailable due to a temporary overload or scheduled maintenance. (Treat as a 503 Service Unavailable HTTP error). Using the Authorization Code Grant Topics Authorization Request (p. 20) Authorization Response (p. 22) Access Token Request (p. 22) Access Token Response (p. 23) Access Token Errors (p. 24) Using Refresh Tokens (p. 24) An Authorization Code 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 the user's profile. Once the user approves the request, the client receives the authorization code and can trade that code for an access token and refresh token. Once the client has the access token, they can read the customer profile. For more information, see Authorization Code Grant If the user refuses the request, the client receives an error from the authorization service. Authorization Request To request authorization, the client (website) must redirect the user-agent (browser) to make a secure HTTP call to with the following parameters: Parameter client_id scope Description REQUIRED. The client identifier. This is set when you register your website as a client. For more information, see client identifier. REQUIRED. The scope of the request. Must be profile, postal_code, or both, separated by a space or a plus sign (e.g. profile%20postal_code or profile+postal_code). 20

24 Authorization Request Parameter response_type redirect_uri state Description REQUIRED. The type of response requested. Must be code for this scenario. OPTIONAL. The HTTP address where the authorization service should redirect the user. 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: &scope=profile &response_type=code &state= &redirect_uri= To make an authorization request using the Javascript SDK, you must fill out an options object, and call amazon.login.authorize. options = {}; options.scope = 'profile'; options.response_type = 'code'; amazon.login.authorize(options, function(response) { if ( response.error ) { alert('oauth error ' + response.error); return; } <!-- Pass response.code to your server, and use it to request an access token. The Javascript SDK does not support this step because it would expose the client secret. --> }); 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'; options.response_type = 'code'; amazon.login.authorize(options, ' Note If you would like to use our Javascript SDK to request an Authorization Code grant, you must first have your page load the Javascript SDK. See Loading the Javascript SDK. Once the user has either approved or denied the request, the authorization server will redirect the user to the redirect_uri. The client will then receive an Authorization Response. 21

25 Authorization Response 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 a code parameter containing the authorization code. For example: HTTP/ Found Location: &state= The authorization code can range from 18 to 128 characters. An authorization code is valid for 6 hours. The redirect also copies the state passed by the user-agent 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. For more information see Cross-site Request Forgery. If you are using the Javascript SDK, the above parameters are available in the response object provided by amazon.login.authorize. See Authorization Request for an example. Error responses for this request mirror those used for an implicit grant. See Authorization Errors. Access Token Request Once the client (website) receives an Authorization Response with a valid authorization code, it can use that code to obtain an access token. With an access token, the client can read a customer profile (see Access Token). To request an access token, the client makes a secure HTTP POST to with the following parameters: Parameter grant_type code client_id client_secret Description REQUIRED. The type of access grant requested. Must be authorization_code. REQUIRED. The code returned by the authorization request. REQUIRED. The client identifier. This is set when you register your website as a client. For more information, see client identifier. REQUIRED. The secret value assigned to the client during registration. For example: POST /ap/oatoken HTTP/1.1 Host: Authorization: Basic czzcagrsa3f0mzpnwdfmqmf0m2jw Content-Type: application/x-www-form-urlencoded;charset=utf-8 grant_type=authorization_code &code=splxlobezqqybys6wxsbia Note The client_id and client_secret may be passed in the Authorization header instead of using HTTP Basic authentication. For more information, see RFC

26 Access Token Response For example: POST /ap/oatoken HTTP/1.1 Host: Content-Type: application/x-www-form-urlencoded;charset=utf-8 grant_type=authorization_code &code=splxlobezqqybys6wxsbia &client_id=foodev &client_secret=y76sd12f The Javascript SDK does not contain a function for exchanging authorization codes for access tokens. This is because that exchange requires the client secret, which should not be stored in a script. As a result, your web server will need to make the exchange instead. If you use amazon.login.authorize to request an authorization code, you should pass the authorization code to your server, or use a redirect_uri that will be handled by server-side code. Access Token Response When a client (website) makes a secure HTTP POST Access Token Request, the authorization server immediately returns the access token or an error in the HTTP response. For example: HTTP/ OK Content-Type: application/json;charset=utf-8 Cache-Control: no-store Pragma: no-cache { "access_token":"2yotnfzfejr1zcsicmwpaa", "token_type":"bearer", "expires_in":900, "refresh_token":"tgzv3jokf0xg5qx2tlkwia" } A successful response includes the following values: Parameter access_token token_type expires_in refresh_token scope Description The access token for the user account. The type of token returned. Should be bearer. The number of seconds before the access token becomes invalid. A refresh token that can be used to request a new access token. The scope of the request. Should be profile, postal_code, or both. This can differ from the requested scope. Response parameters are encoded using the application/json media type. For more information, see RFC

27 Access Token Errors Access Token Errors For some errors, the authorization service may return an HTTP 401 (Unauthorized) status code. This includes cases where the client passed the client_id and client_secret values in the Authorization header and the client could not be authenticated. An unsuccessful response includes the following values: Error Parameter error error_description error_uri Description An ASCII error code with an error code value. A human-readable ASCII string with information about the error, useful for client developers. A URI to a web page with human-readable information about the error, useful for client developers. The following error codes can be returned as the value for error: Error Code invalid_request invalid_client invalid_grant unauthorized_client unsupported_grant_type invalid_scope server_error Description The request is missing a required parameter, has an invalid value, or is otherwise improperly formed. The client authentication failed. This is used in cases when the authorization service does not return an HTTP 401 (Unauthorized) status code. The authorization code is invalid, expired, revoked, or was issued to a different client_id. The client is not authorized to use authorization codes. The client specified the wrong token_type. The client requested the wrong scope (it must be set to profile, postal_code, or both). An error occurred on one of the Login with Amazon authorization service servers. Using Refresh Tokens Access tokens will expire after a set time period (normally returned in the expires_in parameter). When you obtain an access token, you will also receive a refresh token.you can use a refresh token to retrieve a new access token. To submit a refresh token, the client makes a secure HTTP POST to with the following parameters: Parameter grant_type Description REQUIRED. The type of access grant requested. Must be refresh_token. 24

28 Using Access Tokens to Read a Customer Profile Parameter refresh_token Description REQUIRED. The refresh token returned by the original Access Token Response. For example: POST /ap/oatoken HTTP/1.1 Host: Authorization: Basic czzcagrsa3f0mzpnwdfmqmf0m2jw Content-Type: application/x-www-form-urlencoded;charset=utf-8 grant_type=refresh_token &refresh_token=tgzv3jokf0xg5qx2tlkwia Note The client_id and client_secret may be passed in the Authorization header instead of using HTTP Basic authentication. For more information, see RFC2617. For example: POST /ap/oatoken HTTP/1.1 Host: Content-Type: application/x-www-form-urlencoded;charset=utf-8 grant_type=refresh_token &refresh_token=tgzv3jokf0xg5qx2tlkwia &client_id=foodev &client_secret=y76sd12f The response to a refresh token submission is an Access Token Response. Using Access Tokens to Read a Customer Profile Once the user grants your website access to their Amazon customer profile, you will receive an access token. To access customer data, you submit that access token to Login with Amazon using HTTPS. In response, Login with Amazon will return the customer profile data. The profile data you receive is determined by the scope you specified when requesting access. The access token reflects access permission for that scope. If you are using the Javascript SDK, use amazon.login.retrieveprofile to exchange an access token for a profile. For example: <script type="text/javascript"> document.getelementbyid('loginwithamazon').onclick = function() { settimeout(window.dologin, 1); return false; 25

29 Using Access Tokens to Read a Customer Profile }; 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('hello, ' + response.profile.name); alert('your address is ' + response.profile.primary ); alert('your unique ID is ' + response.profile.customerid); if ( window.console && window.console.log ) window.console.log(response); }); }); }; </script> The amazon.login.retrieveprofile function returns three parameters: success, error, and profile. success indicates whether the call was successful. error contains an error message if an error occurred. If there was no error, profile contains the user's profile. Note If you would like to use our Javascript SDK to request a customer profile, you must first have your page load the Javascript SDK. See Loading the Javascript SDK. If you are calling the endpoint directly, you can specify the access token in one of three ways: as a query parameter, as a bearer token, or using x-amz-access-token in the HTTP header. For example: GET /ap/user/profile HTTP/1.1 Host: Date: Wed, 01 Jun :00:00 GMT Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA GET /ap/user/profile HTTP/1.1 Host: Date: Wed, 01 Jun :00:00 GMT x-amz-access-token: 2YotnFZFEjr1zCsicMWpAA Login with Amazon only supports application/json as a content type and en-us as a content language. Login with Amazon uses this content type and language by default, even if they are not specified. GET /ap/user/profile HTTP/1.1 Host: Date: Wed, 01 Jun :00:00 GMT x-amz-access-token: : 2YotnFZFEjr1zCsicMWpAA 26

30 Customer Profile Response Accept: application/json Accept-Language: en-us Customer Profile Response If your access token is valid, you will receive the customer's profile data as an HTTP response in JSON. For example: HTTP/ OK Content-Type: application/json Content-Language: en-us Content-Length: 85 { "Profile": { "CustomerID": amzn1.user.k2li23kl2lk2, "Primary ":johndoe@gmail.com, "Name" : "Mr. John Doe" "Request-Id": bef0c2f8-e c fbd559df } } The Request-Id is for logging and can be ignored. If you are troubleshooting an issue with the Login with Amazon team you may be asked to supply the Request-Id. If there is a problem fulfilling your profile request, you will receive an HTTP error. The error codes for an access request include: Status Code Error Code Success MissingValue InvalidValue Unauthorized UserAuthorizationInvalid UserAuthorizationExpired Forbidden ResourceNotFound MethodNotAllowed ServerError TransientFailure Description Success One or more required parameters was missing. One or more required parameters was invalid. The access token is missing or the AWS client signature in the Authorization header is missing or invalid. The end-user authorization token in the x-amz-user-authz header is missing or invalid. The end-user authorization token in the x-amz-user-authz header has expired. The caller does not have access to this API. The specified resource does not exist. The HTTP method is not valid. For example, using POST instead of GET. The server encountered a runtime error. The server encountered a transient error. Please retry. 27

31 Customer Profile Response Status Code Error Code Description 503 ServiceUnavailable The service is temporarily overloaded or unavailable, please try again later. In addition to the error code, you may receive a JSON payload with more information. For example: HTTP/ Bad Request Content-Type: application/json;charset=utf-8 Content-Length: 74 { "Response" : { "Error": { "Code": machine-readable error code, "Type": Receiver -or- Sender, "Message": human-readable error description, "Detail": { Other data, in JSON, specific to the error } }, "RequestId": bef0c2f8-e c fbd559df } } 28

32 Cross-site Request Forgery Security Considerations Topics Cross-site Request Forgery (p. 29) Client Secret Rotation (p. 30) Open Redirectors (p. 30) Code Injection (p. 31) Handling Customer Data (p. 31) The customer information Login with Amazon provides to participating websites is valuable, and some precautions must be taken to ensure it stays confidential. The Login with Amazon protocol makes extensive use of HTTPS to protect communications between the user and Amazon, and between your website and Amazon. This section explains any security threats that go beyond using HTTPS, and explains how you can prevent attackers from gaining valuable customer information. Cross-site Request Forgery Cross-site Request Forgery happens when an attacker induces a user to click on a malicious link, where the link goes to a site where the user is authenticated. Any commands embedded in that 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 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. 29