Login with Amazon How-to Guide

Transcription

1 PDF last generated: August 28, 2017 Login with Amazon How-to Guide Version 3.02 Last generated: August 28, 2017 Login with Amazon How-to Guide Page 1

2 PDF last generated: August 28, 2017 Copyright 2017 Amazon, Inc. and/or its affiliates. All rights reserved. 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. Login with Amazon How-to Guide Page 2

3 Table of Contents PDF last generated: August 28, 2017 Table of Contents Login with Amazon Overview...5 Documentation Overview... 6 Release Notes... 8 Frequently Asked Questions Glossary LWA for Websites...19 LWA for Websites Overview Step 1: Register your Website Step 2: Add a LWA Button Step 3: Add the LWA SDK for JavaScript Step 4: Choose an Authorization Grant Authorization Grant Options Implicit Grant Authorization Code Grant Step 5: Dynamically Redirect Users Step 6: Obtain Customer Profile Information Step 7: Log out Users Step 8: Integrate with your Existing Account System Reference LWA SDK Docs for JavaScript LWA for ios Apps...60 LWA for ios Apps Overview Customer Experience in ios Apps Step 1: Install the SDK for ios Step 2: Run the Sample app Step 3: Register your ios app with LWA Step 4: Create a LWA Project Step 5: Add a LWA Button to your App Step 6: Use the SDK for ios APIs Step 7: Integrate with your Existing Account System Upgrade your ios SDK LWA for Android and Fire Apps...97 LWA for Android and Fire Apps Overview Customer Experience in Android and Fire Apps Step 1: Install the SDK for Android Step 2: Run the Sample app Login with Amazon How-to Guide Page 3

4 Table of Contents PDF last generated: August 28, 2017 Step 3: Register your Android/Fire app Step 4: Create a LWA Project Step 5: Add a LWA Button to your app Step 6: Use the SDK for Android APIs Step 7: Integrate with your Existing Account System Upgrade your Android SDK Understanding LWA LWA Conceptual Overview Access Tokens Authorization Code Refresh Tokens Customer Profile Authorization Grants Security Profile Security Considerations Cross-site Request Forgery Impersonating a Resource Owner Open Redirectors Code Injections Resources for Buttons, Styles, Providers Button Guidelines Style Guidelines Solution Providers Older Documentation Use the Login with Amazon SDK for Android APIs (v2.0.2 and below) Use the Login with Amazon SDK for ios APIs (v2.1.2 and below) Login with Amazon How-to Guide Page 4

5 Overview PDF last generated: August 28, 2017 Overview Documentation Overview... 6 Release Notes... 8 Frequently Asked Questions Glossary Login with Amazon How-to Guide Page 5

6 Login with Amazon Documentation PDF last generated: August 28, 2017 Login with Amazon Documentation With Login with Amazon, you can secure customer information by leveraging the same user authentication system used by Amazon.com. Login with Amazon is based on OAuth 2.0, which has been broadly adopted for user authorized exchanges across sites. For more high-level details, see the Login with Amazon product overview page. For more workflow details, see the Conceptual Overview (page 135). Note: This documentation is currently available in two places online: The Developer Portal (this site) and another site called login.amazon.com/documentation. The latter site is an older site that will be retired in The two sites mostly have the same information, but the information here is more current. Integrate Login with Amazon with your App To integrate Login with Amazon with your app, see the following: Login with Amazon for Websites (page 20) Login with Amazon for ios mobile apps (page 61) Login with Amazon for Android/Fire apps (page 98) Understanding Login with Amazon The following topics show how Login with Amazon uses access tokens to allow websites to login customers and access their customer profiles. Login with Amazon Conceptual Overview (page 135) Access Token (page 138) Authorization Code (page 139) Refresh Token (page 140) Customer Profile (page 141) Authorization Grants (page 143) Security Profile (page 147) Security Considerations The customer information Login with Amazon provides to participating websites is valuable, and 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. These topics explain any security threats that go beyond using HTTPS, and explains how you can prevent attackers from gaining valuable customer information. Cross-site Request Forgery (page 149) Impersonating a Resource Owner in Implicit Flow (page 151) Open Redirectors (page 150) Code Injection (page 152) Login with Amazon How-to Guide Page 6

7 Login with Amazon Documentation PDF last generated: August 28, 2017 Login with Amazon for TVs, Game Consoles, and Other Devices Login with Amazon is currently available for websites, native ios mobile apps (page 61), and native Android mobile/fire apps (page 98). We currently do not support Login with Amazon for sign-in on devices such as Smart TVs (including Android TV), gaming consoles, watches, or any other device that is unable to launch a web browser. Login with Amazon for WordPress To integrate Login with Amazon for a WordPress site, see the following blog posts: Using the Login with Amazon WordPress Plugin Troubleshooting the Login with Amazon WordPress Plugin Reference SDK Documentation The reference docs are not included in the PDF here. To access the reference SDK documentation, go to the following links online: Reference SDK Docs for LWA ios Reference LWA SDK Docs for Android Support and Questions If you have questions about whether Login with Amazon is available for your platform, or if you d like to be notified when support for additional platforms becomes available, contact us. For suppose, see the Login with Amazon area in the Developer Forums. Login with Amazon How-to Guide Page 7

8 Release Notes PDF last generated: August 28, 2017 Release Notes The Login with Amazon SDK is bundled as part of the Amazon Apps & Services SDK. You can download the most recent version of these SDKs here. Below are the release notes specific to the Login with Amazon SDKs for Android/Fire and ios. SDK for Android Version Release Date Notes (current) Mar 20, 2017 Updates to.jar file Backwards compatible to version 2.x and 1.x Feb 21, 2017 Bug fixes for Fire phone and Kindle devices. Support for server side logout. Bug fixes for getclientid and getredirecturi APIs. Backwards compatible to version 2.x and 1.x 3.0 Nov 03, 2016 Introduced new set of APIs with reduced amount of integration effort. Support interactive strategy to allow end user define whether to show, always show, or never show SignIn flow when calling the authorize API. Support grant type to allow end user define whether to request for authorization code or OAuth access token (default) when calling the authorize API. Return user profile data (if requested) and OAuth access token (if requested) in result of the authorize API call. Support calling regionalized endpoints in Europe and Japan. Support independent integration with the Amazon Pay SDK. Backwards compatible to version 2.x and 1.x If you are using an older version of the Login with Amazon SDK for Android, see our migration guide (page 128) for instructions on upgrading to the current version. SDK for ios Version Release Date Notes Login with Amazon How-to Guide Page 8

9 Release Notes PDF last generated: August 28, 2017 Version Release Date Notes (current) Mar 28, 2017 Fixed app crashing issue caused by [AMZNScopeFactory scopewithname:] method Backwards compatible to version 2.x and 1.x Dec 21, 2016 Fixed issue that the redirecturi property of AMZNAuthorizeResult class returns invalid content. Backwards compatible to version 2.x and 1.x 3.0 Nov 03, 2016 Introduced new set of APIs with reduced amount of integration effort. Support interactive strategy to allow end user define whether to either show, always show, or never show SignIn flow when calling the authorize API. Support grant type to allow end user define whether to request for authorization code or OAuth access token (default) when calling the authorize API. Return User profile data (if requested) and OAuth access token (if requested) in result of the authorize API call. Support calling regionalized endpoints in Europe and Japan. Support independent integration with the Amazon Pay SDK. Backwards compatible to version 2.x and 1.x If you are using an older version of the Login with Amazon SDK for ios, see our migration guide (page 91) for instructions on upgrading to the current version. Login with Amazon How-to Guide Page 9

10 FAQ PDF last generated: August 28, 2017 FAQ The following are frequently asked questions about Login with Amazon. General Login with Amazon Questions What is Login with Amazon? Login with Amazon allows Amazon customers to login to registered third-party websites or mobile apps ( clients ) using their Amazon user name and password. Clients may ask the customers to share some personal information from their Amazon profile, including name, address, and zip code. Who uses Login with Amazon? Developers who integrate with Login with Amazon to reduce registration and authentication friction, and Amazon customers who use Login with Amazon to login to websites and mobile apps with their Amazon credentials instead of creating a new password. Why would a website or app use Login with Amazon? Login with Amazon is a free service that allows developers to quickly and easily integrate a login solution to their websites and mobile apps. The service makes it convenient for over 250 million Amazon customers to login to these websites and mobile apps securely, and without hassles, using their Amazon account. It also allows customers to seamlessly share profile data, such as their address, with a client. After you ve implemented Login with Amazon, your customers will have one less username and password to remember in an environment where password reuse can compromise their information on multiple sites if an attacker finds a vulnerability in just one of them. Why did Amazon create Login with Amazon? Login with Amazon helps introduce sellers and developers to other Amazon services. Amazon has a suite of services for sellers and developers to build, monetize and market their websites and mobile apps (learn more about them in our Developer Portal). Login with Amazon also addresses the customer pain of forgotten passwords by enabling them to use the credentials they use almost every day across the web. Using Login with Amazon How do Amazon customers use Login with Amazon to login to a website or mobile app? Users will see a Login with Amazon button that starts the login process. After clicking the button, the user will be presented a secure login screen (hosted by Amazon) to enter their and password. After authentication, they will then be asked to consent to share the data requested by the website or mobile app, which can include their name, address and zip code. The consent screen will inform the user of what information was requested and what will be shared. Login with Amazon How-to Guide Page 10

11 FAQ PDF last generated: August 28, 2017 If they do not consent, they will be redirected back to the website or app. If they do consent, they will be redirected back to the website or app and the client will receive a token or code to access authorized user data. In using the Login with Amazon SDKs for ios and Android, you can also provide your users with a single sign-on experience, allowing them to skip the login screen if they are already authenticated to Amazon. To learn more, see Customer Experience Overview for Android/Fire apps (page 100), and Customer Experience Overview for ios apps (page 63). Can I use Login with Amazon on Internet of Things (IoT) devices or apps? Yes, you can use Login with Amazon as an authentication gateway for any IoT device or app capable of integrating with one of our SDKs. In fact, Login with Amazon currently provides a secure and scalable authentication gateway for the Amazon Echo and Dash Buttons. The exception to this is any device which is not capable of launching a web browser, such as smart TVs and watches. Login with Amazon is not currently available to these types of devices. If you have questions about whether Login with Amazon is available for your platform, or if you d like to be notified when support for additional platforms becomes available, contact us. Can I use Login with Amazon on Fire TV and Fire tablet apps? Yes, the Login with Amazon for Android (page 98) instructions can also be used to add Login with Amazon to Fire TV and Fire tablet applications. Learn more about creating apps for Amazon Fire TV and Amazon Fire Tablets at developer.amazon.com. How do Amazon customers see information on sites they have logged into? Users can visit the Manage Login with Amazon section of the Your Account page on Amazon.com to view the list of websites or mobile apps they ve consented to share data with. What if an Amazon customer no longer wishes to share information with a third-party website or app via Login with Amazon? Users can remove the third-party site s access to their information from the Manage Login with Amazon section of the Your Account page on Amazon.com. Removing permissions only prevents the third-party from accessing updates to the information already shared. The third-party may retain the information already shared, and the usage of that information is subject to that site s privacy policy. If a third-party site using Login with Amazon is a subsidiary of Amazon, we may continue to share the information with the third-party site as described in the Amazon.com privacy policy. Setting up Login with Amazon How do I sign up for Login with Amazon? Before you can use Login with Amazon on a website, you must either register a Security Profile through the Developer Console, or register an application through the App Console (one or the other). Login with Amazon How-to Guide Page 11

12 FAQ PDF last generated: August 28, 2017 If you plan to implement Amazon Pay at launch, register through the App Console using these instructions provided by Amazon Pay. If you don t plan to use Amazon Pay at launch, register through the Developer Console. Next, use our instructions for Websites (page 20), ios (page 61), and, Android (page 98) to finish setting up Login with Amazon. If you re not sure whether you ll use Amazon Pay now or in the future, we recommend registering through the Developer Console. You can always register through the App Console later if you decide to use Amazon Pay, and then contact our team to link the two accounts (see the next question for details). I have websites and/or mobile apps registered in both Seller Central (App Console) and the Developer Portal. Can I manage all my websites/apps in one place? You can link your App Console and Developer Portal accounts to get a consolidated view of all your Login with Amazon websites and/or mobile apps in both places. With the accounts linked, you get the flexibility of visiting either the App Console or the Developer Portal to manage all your websites and/ or mobile apps. Through the App Console, you get the additional benefit of viewing Amazon-captured metrics (sign in success, consent denied, consent revoked, etc.) for your applications, which aren t available in the Developer Portal. For example, you ll want to link accounts if you ve enabled Login with Amazon on an Android/Kindle application distributed through the Amazon AppStore (as these must be registered through the Developer Portal), and also on the website version of the same application registered through the App Console in Seller Central. In this example, the website registered through Seller Central won t appear in the Developer Portal, and the Android/Kindle app registered in the Developer Portal won t appear in Seller Central. In addition, because the application is registered in two different places, your customers would need to provide consent twice once when they Login with Amazon through the website, and a second time when they Login with Amazon through the Android/Kindle app. Linking your App Console and Developer Portal accounts enables a more seamless experience for your customers, as they ll only need to provide their consent once per application. Although linking your accounts is not required, it is highly recommended to ensure you receive the best experience and most accurate metrics from Login with Amazon. To link your accounts, contact Login with Amazon support (lwa-support@amazon.com) and include the address you used in both Seller Central and the Developer Portal. What should I do if I have multiple versions of the same app (e.g. free vs paid)? If you have multiple versions of the same app, open the ios or Kindle/Android settings for the app in your Developer Console, then click the Add an API Key button at the bottom right. After you register the new settings, you can use the resulting API Key value for the other version of the app. This will prevent your users from having to consent to Login with Amazon on multiple versions of the same app. Remember to label your new settings appropriately so you can tell them apart. Login with Amazon How-to Guide Page 12

13 FAQ PDF last generated: August 28, 2017 Can I use one developer account for multiple websites and mobile apps? Yes, Amazon s Developer Console allows you to add and manage multiple Login with Amazon application for Web, ios and Android/Kindle. You can also register Login with Amazon applications via the App Console on login.amazon.com. If you ve registered applications on both the App Console and the Developer Portal, and would like to manage them all in one place, review our the earlier FAQ ( I have websites and/or mobile apps registered in both ). What profile information can Amazon users share with me? Customers can consent to share their name, address, and ZIP Code when using Login with Amazon. If the customer uses Login & Pay with Amazon, they can also share their shipping address. About Amazon Pay What is Amazon Pay? Amazon Pay is a service that provides customers with the ability to send and receive payments for goods or services by using the payment methods already stored in their Amazon.com account. To make a payment, they can use a credit card, bank account, or Amazon Pay Account balance. Amazon Pay is available for websites only. Learn more. What is Login and Pay with Amazon? Login and Pay with Amazon combines Amazon Pay with Login with Amazon. It allows hundreds of millions of Amazon buyers to login and pay on your website with the information already stored in their Amazon account. It s fast, easy and trusted. It can help you add new customers, increase sales and turn browsers into buyers. Leverage the trust of Amazon to grow your business. Learn more. How do I add Amazon Pay to my website? Review the Amazon Pay documentation for step-by-step instructions. Technical Questions & Troubleshooting Does Login with Amazon use the OAuth protocol? Yes, Login with Amazon uses the OAuth 2.0 protocol for authorizing access to customer profile data. More extensive documentation of our Oauth implementation is available in the Understanding Login with Amazon section of our Login with Amazon for Websites (page 20) documentation. Why does the Allowed Return URL for my website need to be secure (https)? When you register your website for Login with Amazon, you ll be asked to enter either Allowed Return URLs or Allowed JavaScript Origins. The Return URL protocol must be HTTPS. There is a security risk in allowing HTTP return URLs if you are using the Implicit Grant (learn more (page 143)). A man-in-the-middle would have the ability to view Access Tokens (page 138) passing between the Login with Amazon How-to Guide Page 13

14 FAQ PDF last generated: August 28, 2017 redirect URL and the user s browser, allowing an attacker to illegitimately obtain customer profile data using those Access Tokens. If you do not have HTTPS available on your site, you can use the Authorization Code Grant (page 143) to query Amazon s customer profile endpoint directly from your server. This communication will be over HTTPS and will be authorized with your client identifier and client secret for authentication. There is sample code available in our Getting Started Guide for Web (page 20) to show you how to use the Authorization Code Grant. We highly recommend that sites that will have authenticated customer sessions also have the ability to communicate over HTTPS to avoid eavesdropping attacks which may result in credentials being stolen and replayed by an attacker. All secure data, including tokens, should pass over an HTTPS connection. I m seeing an error in the Developer Portal when I enter an Allowed JavaScript Origin: One of your Allowed JavaScript Origins is invalid. Login with Amazon today supports origin URLs to be a combination of protocol, domain name and port (for example One common reason for encountering this error is due to using an unsupported top-level domain. Login with Amazon currently supports all original, infrastructure, and country code top-level domains. If you need to register an unsupported URL for your application, contact us for assistance. I ve added the Login with Amazon button to my website, but am getting an error when I click it: 400 Bad Request - the domain on which you are using the JavaScript SDK has not been whitelisted for your application. The URL of the webpage that invokes the Login with Amazon JavaScript SDK needs to be listed as an Allowed JavaScript Origin in the Web Settings of your application. Open your security profile in the Developer Console, hover over the icon, select Web Settings, and then click Edit to add Allowed JavaScript Origins. Make sure the URL exactly matches the one that invokes the SDK, including the protocol (http vs https). Login with Amazon How-to Guide Page 14

15 Glossary PDF last generated: August 28, 2017 Glossary access scope An access scope defines the type of user profile data the client is requesting. The first time a user logs in, they see a list of the items in the access scope and must agree to provide the data to the client in order to proceed. access token An access token is granted by the authorization server when a user logs in to a site. An access token is specific to a client, a user, and an access scope (page 15). Access tokens have a maximum size of 2048 bytes. A client must use an access token to retrieve customer profile (page 17) data. See Access Tokens (page 138) for more details. allowed Javascript origins A JavaScript origin is the combination of protocol, domain, and port where a JavaScript call originates. By default, web browsers block JavaScript calls from one origin that try to call script on another origin. The Login with Amazon SDK for JavaScript allows calls from other origins if they are specified as part of an application (page 15). When registering a website for Login with Amazon, enter the scheme, domain, and optionally the port, of the webpage which includes the Login with Amazon SDK for JavaScript (for example, or ). allowed return URL A return URL is an address on a website that uses Login with Amazon. The authorization service (page 16) redirects users to this address when they complete login. See also redirect URL (page 17). API key This is an identifier that Login with Amazon SDKs use to identify a mobile app to the authorization service (page 16). API keys are generated when you register a mobile app. application An application is the registration that contains information the authorization service (page 16) needs to verify a client before that client can access customer profile (page 17). It also contains basic information about your business that is displayed to users when they first login to one of your apps and are asked to share information with you. appstore ID An AppStore ID uniquely identifies a mobile app in the Amazon AppStore. Login with Amazon How-to Guide Page 15

16 Glossary PDF last generated: August 28, 2017 authorization code An authorization code is a value used by the Authorization Code grant (page 16) to allow a website to request an access token (page 15). See Authorization Code (page 139) for more details. authorization code grant An Authorization Code grant is an authorization grant (page 16) that uses server-based processing to request an access token (page 15). Using the authorization code grant, the server receives an authorization code (page 16) as a query parameter after the user logs in. The server exchanges the authorization code, client identifier (page 16), and client secret (page 16) for an access token and a refresh token (page 18). authorization grant An authorization grant is the process where the authorization service (page 16) verifies a client website s request for access to a customer profile (page 17). An authorization grant requires a client identifier (page 16) and an access scope (page 15), and may require a client secret (page 16). If the process succeeds, the website is granted an access token (page 15). There are two types of authorization grants, an implicit grant (page 17) and an authorization grant (page 16). authorization service The Login with Amazon authorization service is the collection of endpoints provided by Amazon that allows a client to login a user through Authorization Code grant (page 16). The authorization service presents the login screen and the permissions screen to users. It provides access tokens (page 15), refresh token (page 18), and customer profile (page 17) data to Login with Amazon clients. bundle identifier The bundle identifier is a unique identifier for an ios app. They normally take the form of com.companyname.appname. client A client is a website or mobile app that uses Login with Amazon. client identifier The client identifier is a value assigned to the client when they register with Login with Amazon. It has a maximum size of 100 bytes. The client identifier is used in conjunction with the client secret to verify the identity of the client when they request an authorization grant from the authorization service (page 16). The client identifier is not secret. client secret The client secret, like the client identifier (page 16), is a value assigned to the client when they register with Login with Amazon. It has a maximum size of 64 bytes. The client secret is used in conjunction with the client identifier to verify the identity of the client when they request an authorization grant Login with Amazon How-to Guide Page 16

17 Glossary PDF last generated: August 28, 2017 (page 16) from the authorization service (page 16). The client secret must be kept confidential. consent screen When a user logs into a website or mobile app for the first time, they are presented with a consent screen if the app requests profile data. The consent screen shows the name, logo image file (page 17), and privacy notice URL (page 17) associated with app, along with the access scope (page 15) the app is requesting. customer profile A customer profile contains information about the Login with Amazon customer, including their name, address, postal code, and a unique identifier. A website must obtain an access token (page 15) before they can obtain a customer profile. The kind of profile data returned is determined by the access scope (page 15). See Customer Profile (page 141) for more details. implicit grant An Implicit Grant is an authorization grant (page 16) that can be completed using only the user s web browser. Using the implicit grant, the browser receives an access token (page 15) as a URI fragment. An implicit grant requires a client identifier (page 16) and an access scope (page 15). The implicit grant does not return a refresh token (page 18). login screen The login screen is an HTML page presented to users when they try to login to a website or mobile app using Login with Amazon. Users can enter an existing Amazon account or create a new one from this page. logo image file A PNG file provided by the client when setting up an application (page 15). This is displayed on the permissions screen if the user has not granted access to the client website. The logo represents the client website. package name A package name is a unique identifier for an Android app. They normally take the form of com.companyname.appname. privacy notice URL A URL provided by the client when setting up an application (page 15). This is displayed on the consent screen if the user has not granted access to the client website. The URL should direct users to the privacy policy for the client website. redirect URL A URL provided by the client to the authorization service (page 16). After the user logs in, the service Login with Amazon How-to Guide Page 17

18 Glossary PDF last generated: August 28, 2017 will redirect the user s browser to this addresss. See also allowed return URL (page 15). refresh token A refresh token is granted by the authorization service (page 16) when the client uses the authorization grant (page 16). A client can use a refresh token to request a new access token (page 15) when the current access token expires. Refresh tokens have a maximum size of 2048 bytes. See Refresh Tokens (page 140) for more details. signature A signature is a hash value embedded in a mobile app that verifies the identity of the app. Signatures may be MD5 or SHA-256 values, and normally take the following form. MD5: 01:23:45:67:89:ab:cd:ef:01:23:45:67:89:ab:cd:ef. SHA-256: 01:23:45:67:89:ab:cd:ef:01:23:45:67:89:ab:cd:ef:01:23:45:67:89:ab:cd:ef:01:23:45:67:89:ab:cd:ef </li></u user A user is a person who visits a client website and tries to log in using Login with Amazon. version A version is a particular type of Login with Amazon client registered to an application (page 15). A Login with Amazon application can have multiple versions, each supporting either Android, ios, or web. Login with Amazon How-to Guide Page 18

19 Login with Amazon for Websites PDF last generated: August 28, 2017 Login with Amazon for Websites LWA for Websites Overview Step 1: Register your Website Step 2: Add a LWA Button Step 3: Add the LWA SDK for JavaScript Step 4: Choose an Authorization Grant Step 5: Dynamically Redirect Users Step 6: Obtain Customer Profile Information Step 7: Log out Users Step 8: Integrate with your Existing Account System Reference LWA SDK Docs for JavaScript Login with Amazon How-to Guide Page 19

20 Login with Amazon for Websites PDF last generated: August 28, 2017 Login with Amazon for Websites Getting Started These topics will show you how to add Login with Amazon to your website or web service. After completing these steps you should have a working Login with Amazon button on your website to allow users to log in with their Amazon credentials. For more details on the methods, parameters, and classes mentioned in these instructions, see our Login with Amazon SDK for JavaScript Reference Guide (page 51). 1. Register Your Application (page 21) 2. Add a Login with Amazon Button (page 23) 3. Add the Login with Amazon SDK for JavaScript (page 24) 4. Choose an Authorization Grant (page 26) Implicit Grant (page 28) Authorization Code Grant (page 34) 5. Dynamically Redirect Users (page 42) 6. Obtain Profile Information (page 43) 7. Log Out Users (page 48) 8. Integrate with Your Existing Account System (page 49) Login with Amazon How-to Guide Page 20

21 Register for Login with Amazon PDF last generated: August 28, 2017 Register for Login with Amazon Before you can use Login with Amazon on a website, you must register a Security Profile through the Developer Console. During registration, you ll be asked to provide the name of your application, your logo, and a link to your privacy policy. Users will see this information each time they use Login with Amazon on your website or mobile app. Register your Security Profile If this is your first time using the Developer Console, you will need to create a security profile for your website or mobile app. 1. Visit You will be asked to login to the Developer Console, which handles application registration for Login with Amazon. If this is your first time using the Developer Console, you will be asked to set up an account. 2. Click Create a New Security Profile. This will take you to the Security Profile Management page. 1. Enter a Name and a Description for your security profile. A security profile associates user data and security credentials with one or more related apps. 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. 2. You must enter a Consent Privacy Notice URL for your application now. The Privacy Notice URL is the location of your company or application s privacy policy (for example, ). This link is displayed to users on the consent screen. 3. If you want to add a Consent Logo Image for your application, click Upload Image. This logo is displayed on the sign-in and consent screen to represent your business or website. 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. 3. Click Save. Your security profile should look similar to this: After your basic security profile is saved, you can associate specific websites and mobile apps with this security profile. Login with Amazon How-to Guide Page 21

22 Register for Login with Amazon PDF last generated: August 28, 2017 Add your Website to your Security Profile After creating a security profile on the Developer Console, you can add settings for specific websites and mobile apps that will use Login with Amazon with that profile. Follow these steps to add a website to your profile: 1. Visit 2. Go to the Web Settings of the security profile that you want to use for your app. 1. Locate the security profile you want to modify from the table. 2. Hover over the button shown in the Manage column. 3. Select the Web Settings menu item. Note: If your desired security profile is not shown in the table, it is not yet enabled for Login with Amazon. In this case, use the dropdown menu above the table to Select a Security Profile, then click Confirm. You ll be required to enter a Consent Privacy Notice URL and optionally select a Consent Logo Image, both of which will be displayed on the sign-in and consent screens. If you don t have an existing security profile for your app, see Register Your Security Profile (above). 3. Click Edit. 4. To use Login with Amazon with a website, you must specify either Allowed Origins or Allowed Return URLs. Specify Allowed Origins to provide a popup authentication experience to your users, or Allowed Return URLs to provide a redirect authentication experience. If your website will use the Login with Amazon SDK for JavaScript, add your website origin to Allowed Origins. An origin is the combination of protocol, domain name, and port (for example, 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, Adding your domain here allows the Login with Amazon SDK for JavaScript to communicate with your website directly during the login process. Web browsers normally block crossorigin communication between scripts unless the script specifically allows it. If your website will be making HTTPS calls to the Login with Amazon authorization service and specifying a redirect_uri for replies, add those redirect URIs to Allowed Return URLs. The return URL includes the protocol, domain, path, and query string(s) (for example, 5. Click Save. Delete your Security Profile If needed, you can delete any security profile not associated with an app distributed through the Amazon Appstore. Navigate to the Security Profile Management page, select a profile, and then click Delete Security Profile. A confirmation form appears. Type the word delete into the text field then click Delete to confirm the action. If a security profile is mistakenly deleted, it s fully recoverable from the Security Profile Management page. Click the Show Deleted Security Profiles button, click on the name of the profile you d like to restore, then click Restore Security Profile. A confirmation form appears. Click the Restore button to recover the security profile, including its Web, Android/Kindle, and ios settings. Login with Amazon How-to Guide Page 22

23 Add a Login with Amazon Button to Your Website PDF last generated: August 28, 2017 Add a Login with Amazon Button to Your Website Next, add the Login with Amazon button to your website. You can pick from a variety of buttons and choose the image that best fits your website. See the Login with Amazon Style Guidelines (page 160) for best practices and a list of images to choose from. 1. Add the following code to your website where you would like the button to appear. For the purposes of this guide, this must be an HTTPS website: <a href id="loginwithamazon"> <img border="0" alt="login with Amazon" src=" btnlwa_gold_156x32.png" width="156" height="32" /> </a> 2. Optional. To use one of our other buttons (found here (page 155)), replace the https link in the code above with the https link for your desired button. Modify the width and height of the button to best suit your website. 3. Refresh the page to confirm that the button now appears on your website. Login with Amazon How-to Guide Page 23

24 Add the Login with Amazon SDK for JavaScript PDF last generated: August 28, 2017 Add 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. The Login with Amazon SDK for JavaScript will handle all of the difficult parts of integrating Login with Amazon into your website. Before you can make an access grant call or retrieve a profile, the SDK must load itself from Amazon s content delivery network. The Login with Amazon SDK for JavaScript 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 properly 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. 1. Add the following code after the opening <body> in your page to load the Login with Amazon SDK for JavaScript, and the amazon-root tag, into your page: <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> 2. After 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. 3. Replace YOUR-CLIENT-ID with the Client ID generated when you Registered Your Application (page 21). 4. Add the following JavaScript after the Login with Amazon button on your site to return an AuthorizeRequest object. After the request is complete, the object will contain properties detailing the response (such as an access token or authorization code, which you can use to obtain customer profile information (page 43)): Login with Amazon How-to Guide Page 24

25 Add the Login with Amazon SDK for JavaScript PDF last generated: August 28, 2017 <script type="text/javascript"> document.getelementbyid('loginwithamazon').onclick = function() { options = { scope : 'profile' ; amazon.login.authorize(options, ' return false; ; </script> 5. Replace with the domain of your website. Tip: By default, the SDK will display the login screen in a popup window. You can set the popup property of the options parameter to false to instead redirect customers to a new page to login. Popup windows are not supported in native ios apps. We recommend implementing a redirected login experience if your customers will use Login with Amazon from a native ios app. Review the Login with Amazon SDK for JavaScript Reference Guide (page 51) for information on customizing the options parameter. After the user has logged in and consented to share the specified data, the current window will be redirected to the given URI and the authorization response will be added to the query string. The URI must use the HTTPS protocol and be on the same domain as the current window. For more information on the methods described above, see the Login with Amazon SDK for JavaScript Reference (page 51). Login with Amazon How-to Guide Page 25

26 Choose an Authorization Grant PDF last generated: August 28, 2017 Choose an Authorization Grant The two mechanisms websites can use to obtain access tokens are the Implicit Grant (page 143) and the Authorization Code Grant (page 143). Both authorization grants work by redirecting the user-agent (the user s browser) to Amazon.com for them to login. After they have logged in, if the website requested an Implicit Grant, the access token (page 138) 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 (page 139), 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 authorization grant you will use. Which grant type is right for your application? In general, the advantages of one grant mirror the disadvantages of the other grant. The advantage of the Authorization Code Grant is that it can be 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 user s profile data. The disadvantage to the Authorization Code Grant is that it can be harder to implement, and it 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. 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 can be preferable 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. Login with Amazon How-to Guide Page 26

27 Authorization Grant Options PDF last generated: August 28, 2017 Authorization Grant Options Implicit Grant Authorization Code Grant Login with Amazon How-to Guide Page 27

28 Implicit Grant PDF last generated: August 28, 2017 Implicit Grant 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 (page 141). After the user approves the request, the user-agent is redirected back to the website using a URI that contains an access token (page 138) 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 (page 143). 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 Description client_id REQUIRED. The client identifier. This is provided when you register your website (page 21) 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 (page 141). 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 (page 149). For example: Login with Amazon How-to Guide Page 28

29 Implicit Grant PDF last generated: August 28, &scope=profile &response_type=token &state= &redirect_uri= 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, ' 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 (page 24). 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). Login with Amazon How-to Guide Page 29

30 Implicit Grant PDF last generated: August 28, 2017 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/l.l 302 Found Location: IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR... &state= ll0975l93l2l59l &token_type=bearer &expires_in=3600 &scope=profile A successful response includes the following values: Parameter Description access_token The access token (page 138) 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 (page 149). 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: Login with Amazon How-to Guide Page 30

31 Implicit Grant PDF last generated: August 28, 2017 HTTP/l.l 302 Found Location: &state=' ll0975l93l2l59l ' 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. 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). 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). Login with Amazon How-to Guide Page 31

32 Implicit Grant PDF last generated: August 28, 2017 Error Code Description 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 passing the access token you wish to verify. You can specify the access token as a query parameter. For example: IQEBLjAsAhRmHjNgH pi0u-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/l.l 200 OK Date: Fri, 31 May :22:10 GMT x-amzn-requestid: eb5be423-ca48-lle2-84ad-5775f45l4b09 Content-Type: application/python Content-Length: 247 { "iss":" "user_id": "amznl.account.k2li23kl2lk2", "aud": "amznl.oa2-client.asfwdfbrn", "app_id": "amznl.application dfhdh", "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: Login with Amazon How-to Guide Page 32

33 Implicit Grant PDF last generated: August 28, 2017 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. 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). 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/l.l 400 Bad Request Date: Fri, 31 May :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, Login with Amazon How-to Guide Page 33

34 Authorization Code Grant PDF last generated: August 28, 2017 Authorization Code Grant 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. After the user approves the request, the client receives the authorization code and can trade that code for an access token (page 138) and refresh token (page 140). After the client has the access token, they can read the customer profile (page 141). For more details on the customer experience, see Authorization Grants (page 143). 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 Description client_id REQUIRED. The client identifier. This is provided when you register your website (page 21) 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 (page 141). response_type REQUIRED. The type of response requested. Must be `code` 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 (page 149). For example: Login with Amazon How-to Guide Page 34

35 Authorization Code Grant PDF last generated: August 28, &scope=profile &response_type=code &state= ll0975l93l2l59l &redirect_uri= 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. 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, ' Tip: If you would like to use the Login with Amazon SDK for JavaScript to request an Authorization Code grant, you must first have your page load the Login with Amazon SDK for JavaScript. See Installing the JavaScript SDK. (page 24) 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 a code parameter containing the authorization code (page 139). For example: Login with Amazon How-to Guide Page 35

36 Authorization Code Grant PDF last generated: August 28, 2017 HTTP/l.l 302 Found Location: &state= ll0975l93l2l59l The authorization code can range from 18 to 128 characters. An authorization code is valid for 5 minutes. 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 (page 149). 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/l.l 302 Found Location: &state= ll0975l93l2l59l The error parameters for a failed authorization request include: Error Parameters 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. 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). The following error codes can be returned as the value for error : Error Code Description Login with Amazon How-to Guide Page 36

37 Authorization Code Grant PDF last generated: August 28, 2017 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). Access Token Request After 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. To request an access token, the client makes a secure HTTP POST to with the following parameters: Parameter Description grant_type REQUIRED. The type of access grant requested. Must be Authorization_code. code REQUIRED. The code returned by the authorization request. redirect_uri REQUIRED. If you provided a redirect_uri for the authorization request, you must pass the same redirect_uri here. If you used the Login with Amazon SDK for JavaScript for the authorization request, you do not need to pass a redirect_uri here. Login with Amazon How-to Guide Page 37

38 Authorization Code Grant PDF last generated: August 28, 2017 Parameter Description client_id REQUIRED. The client identifier. This is set when you register your website as a client. For more information, see Client Identifier (page 147). client_secret REQUIRED. The secret value assigned to the client during registration. For example: POST /auth/o2/token HTTP/l.l Host: api.amazon.com Content-Type: application/x-www-form-urlencoded;charset=utf-8 grant_type=authorization_code &code=splxlobezqqybys6wxsbia &client_id=foodev &client_secret=y76sdl2f Note: The client_id and client_secret may be passed in the Authorization header instead, using HTTP Basic authentication. For more information, see RFC2617. For example: POST /auth/o2/token HTTP/l.l Host: api.amazon.com Authorization: Basic czzcagrsa3f0mzpnwdfmqmf0m2jw Content-Type: application/x-www-form-urlencoded;charset=utf-8 grant_type=authorization_code &code=splxlobezqqybys6wxsbia The Login with Amazon SDK for JavaScript 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 Authorization Request, the authorization server immediately returns the access token or an error in the HTTP response. For example: Login with Amazon How-to Guide Page 38

39 Authorization Code Grant PDF last generated: August 28, 2017 HTTP/l.l 200 OK Content-Type: application/json;charset UTF-8 Cache-Control: no-store Pragma: no-cache { "access_token":"atza IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR...", "token_type":"bearer", "expires_in":3600, "refresh_token":"atzr IQEBLzAtAhRPpMJxdwVz2Nn6f2y-tpJX2DeX..." 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. refresh_token A refresh token (page 140) that can be used to request a new access token. Maximum size of 2048 bytes. scope The scope of the request. Must be profile, profile:user_id, postal_code, or some combination. Response parameters are encoded using the application/json media type. For more information, see RFC4627. 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 Description error An ASCII error code with an error code value. Login with Amazon How-to Guide Page 39

40 Authorization Code Grant PDF last generated: August 28, 2017 Error Parameter Description 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. 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. invalid_client The client authentication failed. This is used in cases when the authorization service does not return an HTTP 401 (Unauthorized) status code. invalid_grant The authorization code is invalid, expired, revoked, or was issued to a different client_id. unauthorized_client The client is not authorized to use authorization codes. unsupported_grant_type The client specified the wrong token_type. ServerError The server encountered a runtime error. 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 token with the following parameters: Parameter Description grant_type REQUIRED. The type of access grant requested. Must be refresh_token. Login with Amazon How-to Guide Page 40

41 Authorization Code Grant PDF last generated: August 28, 2017 Parameter Description refresh_token REQUIRED. The refresh token returned by the original Access Token Response (described above). For example: POST /auth/o2/token HTTP/l.l Host: api.amazon.com Authorization: Basic czzcagrsa3f0mzpnwdfmqmf0m2jw Content-Type: application/x-www-form-urlencoded;charset=utf-8 grant_type=refresh_token &refresh_token=atzr IQEBLzAtAhRPpMJxdwVz2Nn6f2y-tpJX2DeX... Note: The client_id and client_secret may be passed in the Authorization header instead, using HTTP Basic authentication. For more information, see RFC2617. For example: POST /auth/o2/token HTTP/l.l Host: api.amazon.com Content-Type: application/x-www-form-urlencoded;charset=utf-8 grant_type=refresh_token &refresh_token=atzr IQEBLzAtAhRPpMJxdwVz2Nn6f2y-tpJX2DeX... &client_id=foodev &client_secret=y76sdl2f The response to a refresh token submission is an Access Token Response (page 38). Login with Amazon How-to Guide Page 41

42 Dynamically Redirect Users PDF last generated: August 28, 2017 Dynamically Redirect Users After users Login with Amazon, they can only be redirected back to the static pages you specified as Allowed Return URLs when you registered your app (page 21). To instead redirect users dynamically to various different URLs after authentication, when you make the authorization request, populate the state parameter with a value that can be used to generate the desired redirect URL. For example, if you ultimately want users redirected back to the Item Description page they were viewing prior to authentication, populate the state parameter in your request with the unique portion of the Item Description page URL. After authentication, Login with Amazon sends back an authorization response to the client that includes the same state parameter value you specified in the request. The user is sent to the Allowed Return URL. Use the state parameter value to dynamically generate the URL associated with the page you d like the user to land on ultimately, then immediately redirect them there from the static page. If the dynamic URL contains sensitive information, we recommend encrypting, then base64-encoding it, before assigning it to the state parameter. When the information is returned in the authorization response, decrypt and decode it to generate the dynamic URL. In addition, we strongly recommend to anyone using redirect authentication to protect users from crosssite request forgery (page 149) login-with-amazon/cross-site-request-forgery (page 149) attacks. Do this by assigning a unique value (a csrf token) to the state parameter in each authentication request, and later validate it in the authentication response. Consider assigning both this unique csrf token and the redirect URL to the state parameter using concatenation. For example: <csrf-token> + "" + <dynamic-url> For more information on creating a csrf token, see Cross-site Request Forgery (page 149). Important: This information can be disregarded if your app does not redirect users to a separate page for authentication. Login with Amazon How-to Guide Page 42

43 Obtain Customer Profile Information PDF last generated: August 28, 2017 Obtain Customer Profile Information After the user grants your website access to their Amazon customer profile, you will receive an access token (page 138). If you re using server-side scripting to request an access token via the Authorization Code Grant (page 143), the access token is returned in the access token response (page 38). If you re using the Implicit grant (page 143), the access token is returned in the authorization response (page 30) as a URI fragment. To access the authorized customer data, you submit that access token to Login with Amazon using HTTPS. In response, Login with Amazon will return the appropriate customer profile (page 141) 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. Use the Login with Amazon SDK for JavaScript If you are using the Login with Amazon SDK for JavaScript, 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, 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(respon se) { alert('hello, ' + response.profile.name); alert('your address is ' + response.profile.primaryemai l); 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. For more information on this method and its parameters, see the Login with Amazon SDK for JavaScript Reference (page 51). Login with Amazon How-to Guide Page 43

44 Obtain Customer Profile Information PDF last generated: August 28, 2017 Tip: If you would like to use the Login with Amazon SDK for JavaScript to request a customer profile, you must first have your page load the Login with Amazon SDK for JavaScript (page 24). Call the profile Endpoint Server-side If you are calling the profile 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: me37rr6cuupsr... GET /user/profile HTTP/l.l Host: api.amazon.com Date: Wed, 0l Jun 20ll l2:00:00 GMT Authorization: Bearer Atza IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR... GET /user/profile HTTP/l.l Host: api.amazon.com Date: Wed, 0l Jun 20ll l2:00:00 GMT x-amz-access-token: Atza IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR... Tip: 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. 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 /user/profile HTTP/l.l Host: api.amazon.com Date: Wed, 0l Jun 20ll l2:00:00 GMT x-amz-access-token: Atza IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR... Accept: application/json Accept-Language: en-us Detailed code samples are available in the following languages: PHP Python Java Ruby PHP Sample In your server-side application, handle the request made to `/handle_login.php`, and obtain profile information using the access token and the Profile REST API. If you use the following code sample, replace YOUR-CLIENT-ID with your Client ID from the Register Your Application section above. **Note**: You must download the [pycurl]( library to use this sample code. Login with Amazon How-to Guide Page 44

45 Obtain Customer Profile Information PDF last generated: August 28, 2017 import pycurl import urllib import json import StringIO... b = StringIO.StringIO() # verify that the access token belongs to us c = pycurl.curl() c.setopt(pycurl.url, " + urllib.quot c.setopt(pycurl.ssl_verifypeer, 1) c.setopt(pycurl.writefunction, b.write) c.perform() d = json.loads(b.getvalue()) if d['aud']!= 'YOUR-CLIENT-ID' : # the access token does not belong to us raise BaseException("Invalid Token") # exchange the access token for user profile b = StringIO.StringIO() c = pycurl.curl() c.setopt(pycurl.url, " c.setopt(pycurl.httpheader, ["Authorization: bearer " + access_token]) c.setopt(pycurl.ssl_verifypeer, 1) c.setopt(pycurl.writefunction, b.write) c.perform() d = json.loads(b.getvalue()) print "%s %s %s"%(d['name'], d[' '], d['user_id']) 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: Login with Amazon How-to Guide Page 45

46 Obtain Customer Profile Information PDF last generated: August 28, 2017 HTTP/l.l 200 OK x-amzn-requestid: 0f6bef6d-705c-lle2-aacb-93e6bf26930l Content-Type: application/json Content-Language: en-us Content-Length: 85 { "user_id": "amznl.account.k2li23kl2lk2", " ":"mhashimoto-04@plaxo.com", "name" :"Mork Hashimoto", "postal_code": "98052" 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 Error code Description 200 Success The request was successful. 400 invalid_request The request is missing a required parameter or otherwise malformed. 400 invalid_token The access token provided is expired, revoked, malformed, or invalid for other reasons. 401 insufficient_scope The access token provided does not have access to the required scope. 500 ServerError The server encountered a runtime error. In addition to the error code, you may receive a JSON payload with more information. For example: HTTP/l.l 400 Bad Request Content-Type: application/json;charset=utf-8 Content-Length: 74 { "error": "machine-readable error code", "error_description": "human-readable error description", "request_id": "bef0c2f8-e292-4l96-8c fbd559df" Login with Amazon How-to Guide Page 46

47 Obtain Customer Profile Information PDF last generated: August 28, 2017 Get Customer Information to your Server You can get customer profile information obtained from Amazon on your backend server to identify the signed-in user on your server, or to create a more personalized account for the user. To do so securely, send the access token from your client to your server using HTTPS. Then, from server-side, call the profile endpoint using that access token. See Call the profile endpoint server-side (page 44) for details and code samples in multiple languages. Login with Amazon will return a customer profile response with values (such as user_id, , name, and/or postal_code ) you can keep on your server. Taking this step will ensure the profile data you save to your server belongs to the customer who is signed into your client. See our guide on Integrating with your Existing Account System (page 49) for more information on combining and managing user accounts in your backend. Login with Amazon How-to Guide Page 47

48 Log Out Users PDF last generated: August 28, 2017 Log Out Users Your website should provide a way for users to log out once they have logged in. Add the following link to your website where you would like a Logout prompt to appear: <a id="logout">logout</a> After they select the logout option, you should delete any access tokens and refresh tokens associated with that user, and remove their profile information from the website. Your website should then present a login option. If you are using the Login with Amazon SDK for JavaScript, you can call the amazon.login.logout method to delete any cached tokens. For example: Subsequent calls to amazon.login.authorize will present the login screen by default. <script type="text/javascript"> document.getelementbyid('logout').onclick function() { amazon.login.logout(); ; </script> Login with Amazon How-to Guide Page 48

49 Integrate with Your Existing Account System PDF last generated: August 28, 2017 Integrate with Your Existing Account System In this section, we ll discuss how to integrate customer profile data from Login with Amazon user accounts with a website that already has an account management system. You will learn how to enable your site or app to let users log in using their Amazon accounts, and how to let existing users attach their Amazon identity so they can log in with their Amazon credentials. Prerequisites This guide assumes you have previously signed up for Login with Amazon, registered your website as a Login with Amazon application, and have the appropriate SDK or server-side methods to communicate with the Login with Amazon service. This guide also assumes your website currently has these features: 1. An account database where you record information about each user account. Users have some kind of unique identifier. Users currently sign in using their username/password. 2. A sign-in page for registered users. 3. A registration page for registering new users by taking in profile information (name, , and so on). 4. Some mechanism for managing authentication state after the user successfully signs in so that the next page knows that the user is currently signed in (for example, storing that info in cookies or a back-end database). Make 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 user_id property, in the form amzn1.accountvalue. For example: amzn1.account.k2li23kl2lk2 Set up Login with Amazon Using the relevant SDK or server-side methods for your website, provide a method for the user to log in with their Amazon credentials. This includes making changes to the UI of your sign-in and registration pages. Your sign-in page will need to have an option for users to select the Login with Amazon button to authenticate using their Amazon credentials. For more information, see websites]login-with-amazon/webdocs (page 20). Obtain and Secure Amazon Customer Profile Data Once the user has interacted with the Login with Amazon service to sign in (and, on the first visit, authorize data sharing), you will receive an authorization response from Login with Amazon. When you receive an authorization response you should: 1. Send the access token in your authorization response to your server using HTTPS. 2. From server-side, call the profile endpoint using the access token. See our developer guide Login with Amazon How-to Guide Page 49

50 Integrate with Your Existing Account System PDF last generated: August 28, 2017 (page 43) for details on calling the profile endpoint, including code samples in multiple languages. Login with Amazon will return a customer profile response with values (such as user_id, , name, and/or postal_code ) you can keep on your server. Taking this step will ensure the profile data you save to your server belongs to the customer who is signed into your client. 3. Search for the user s Amazon account identifier within your user database to see if they have signed in before. If they have not then you will need to create a new account for them. 4. Search for the user s address in your account system. If they have a local account with that address, prompt them to enter their local credentials to allow Login with Amazon to log in that account. 5. Create cookies in the user s browser or otherwise record them as authenticated with your site or app. Find or Create a Local Account The user profile response will always contain a parameter named user_id. The value of this parameter is a string which permanently and uniquely identifies the Amazon account to which the user has signed in. Amazon will always return the same identifier for each user. You should search your user database to see if this Amazon account has previously signed in to your site or app. If you have not seen the Amazon account before, and it doesn t match an existing account, you will need to create a new entry in your local account database and associate it with the Amazon account identifier for the next time they sign in. If the Amazon account does match an existing local account, prompt the user for their local password to link the two accounts. The authentication response may contain additional user data. For example, the user s name and address. You can copy this information into your local account database when creating new accounts or to update existing accounts (for example, the user could have changed their address on Amazon since the last time they signed in). If you need to collect additional information from the user before creating an account then this is where you will want to display a registration page. You can prefill it with the information you received in the authentication response or you can show just the additional fields that you require. Tip: If your local account management includes resetting passwords, you might want to ensure that Login with Amazon users do not get confused about how that affects 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. Mark the User as Authenticated After you have have received a valid authentication response and found or created a corresponding account in your own account database, mark the user has having authenticated. This step can work exactly the same as in your current authentication system. Login with Amazon How-to Guide Page 50

51 Login with Amazon SDK for JavaScript Reference Guide PDF last generated: August 28, 2017 Login with Amazon SDK for JavaScript Reference Guide This is the Login with Amazon SDK for JavaScript Reference. This documents contains reference information for the Login with Amazon SDK for JavaScript, as well as information about how to load the SDK. Login with Amazon is a web service that enables Amazon customers to login to your web or mobile app using their Amazon credentials. After they have logged in, your app can access some information from their Amazon profile. amazon.login Methods All of the functions in login.js are found in the amazon.login namespace. These functions allow you to identify your client application, request an access token, and exchange an access token for customer profile information. authorize (page 51) getclientid (page 53) logout (page 53) retrieveprofile (page 53) setclientid (page 55) setsandboxmode (page 56) setsitedomain (page 56) setusecookie (page 57) authorize AuthorizeRequest authorize(options, next); Requests authorization according to options then redirects or calls next. Depending on the options set, a popup window will open to allow the user to login, or the window will redirect to the login page. You must call setclientid prior to calling authorize. You must call authorize prior to calling retrieveprofile. This method returns an AuthorizeRequest object. Call oncomplete on that object to register a callback function or redirect URI, similar to the next parameter. After the request is complete, the object will contain properties detailing the response (such as an access token or authorization code). Parameters: options - required - ( Object ). options can contain the following properties: interactive - (String) Specifies when to show a login screen to the user. auto will attempt to use a cached token. If the cached token fails or does not exist, the user will be presented with a login screen. always does not use the cached token and always presents a login screen. never will used the cached token; if the token does not work, authorize will return invalid_grant. Defaults to auto. popup - (Boolean) true to use a popup window for login, false to redirect the current browser window to the authorization dialog. Defaults to true. If false, the next parameter MUST be a redirect URL. Popup windows are not supported in native ios apps. response_type - (String) The grant type requested. Specify token to request an Login with Amazon How-to Guide Page 51

52 Login with Amazon SDK for JavaScript Reference Guide PDF last generated: August 28, 2017 Implicit grant or code to request an Authorization Code grant. Defaults to token. scope - required - ( String or Array[String] ) The access scope requested. Must be profile, profile:user_id, postal_code, or some combination. state - (String) A state parameter. An opaque value used by the client to maintain state between this request and the response. The Login with Amazon 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 (page 149). next ( Function or String ) A URI to redirect the browser response, or a JavaScript function to call with the authorization response. About the next parameter If next is a URI, once the user logs in the current window will be redirected to the URI and the authorization response will be added to the query string. The URI must use the HTTPS protocol and belong to the same domain as the current window. options = { scope: 'profile' ; amazon.login.authorize(options, ' // on success the current window will redirect to: // // on failure the current window will redirect to: // If next is a callback function, it will be invoked with a response object containing the fields of the authorization response. options = { scope: 'profile' ; amazon.login.authorize(options, function(response) { if ( response.error ) { alert('oauth error ' + response.error); return; alert('success: ' + response.access_token); ); Response Caching When authorize receives a valid access token response, it automatically caches the token and associated metadata for reuse. This cache persists across page reloads and browser sessions. If a subsequent authorize call can be fulfilled by the cached token response, the SDK will reuse that token instead of requesting a new authorization. Use options.interactive to override this behavior. Interactivity Modes The options.interactive setting allows you to choose between three interactivity modes. They are: auto : Attempt to authorize the user using the cached token. If that fails, initiate a new authorization, showing the login and consent screen if necessary. always : Initiate a new authorization, showing the login screen and ignoring any cached token. never : Attempt to authorize the user using the cached token. If that fails, return an invalid_grant error. Login with Amazon How-to Guide Page 52

53 Login with Amazon SDK for JavaScript Reference Guide PDF last generated: August 28, 2017 Returns An AuthorizeRequest object. AuthorizeRequest allows callers to register a callback function or redirect URL to use when the login request is complete. It also allows callers to get the current status of the request. When the request is complete, new properties are added to AuthorizeRequest based on the type of authorization request. If the request fails, error properties are added to the object. getclientid getclientid(); Gets the client identifier that will be used to request authorization. You must call setclientid before calling this function. Parameters None. Returns clientid - (String). The client ID assigned to your application. Maximum size of 100 bytes. See Also setclientid (page 55) logout logout(); Logs out the current user after a call to authorize. Parameters None. Returns None. Examples: <script type="text/javascript"> document.getelementbyid('logout').onclick = function() { amazon.login.logout(); ; </script> See Also authorize (page 51) retrieveprofile retrieveprofile(accesstoken, callback); Retrieves the customer profile and passes it to a callback function. Uses an access token provided by authorize. Login with Amazon How-to Guide Page 53

54 Login with Amazon SDK for JavaScript Reference Guide PDF last generated: August 28, 2017 Parameters accesstoken - optional - ( String ) An access token. If this parameter is omitted, retrieveprofile will call authorize, requesting the profile scope. Callback (callback) function(response); Called with the profile data or an error string. Callback Parameters response - (Object) success - (Boolean) true if the request was successful, otherwise false. error - (String) Included if the request failed, and contains an error message. profile - (Object) Included if the request was successful, and contains profile information. CustomerId - (String) An identifier that uniquely identifies the logged-in user for this caller. Only present if the profile or profile:user_id scopes are requested andgranted. Name - (String) The customer s name. Only present if the profile scope is requested and granted. PostalCode - (String) The postal code of the customer s primary address. Only present if the postal_code scope is requested and granted. Primary - (String) The primary address for the customer. Only present if the profile scope is requested and granted. Note: If the accesstoken is omitted, retrieveprofile only requests the profile scope. To get access to the postal_code scope without passing an access token, you can call authorize yourself: amazon.login.authorize({ scope: 'postal_code profile', function () { amazon.login.retrieveprofile(function (response) { // Display profile information. ); ); Example 1: Login with Amazon How-to Guide Page 54

55 Login with Amazon SDK for JavaScript Reference Guide PDF last generated: August 28, 2017 <script type="text/javascript"> document.getelementbyid('loginwithamazon').onclick = function() { settimeout(window.dologin, 1); 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('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> Example 2: var access_token = 'Atza EKdsnskdna '; // obtained from authorization respon se amazon.login.retrieveprofile(access_token, function(response) { if ( response.success ) { alert('hello, ' + response.profile.name); alert('your address is ' + response.profile.primary ); alert('your unique ID is ' + response.profile.customerid); else { alert('oh no! An error happened: ' + response.error); ); See Also authorize (page 51) setclientid setclientid(clientid); Sets the client identifier that will be used to request authorization. You must call this function before calling authorize. Login with Amazon How-to Guide Page 55

56 Login with Amazon SDK for JavaScript Reference Guide PDF last generated: August 28, 2017 Parameters clientid - Required - ( String ). The client ID assigned to your application. Returns None. Example: window.onamazonloginready = function() { amazon.login.setclientid('your-client-id'); ; setsandboxmode setsandboxmode(sandboxmode); Determines whether or not Login with Amazon should use the Amazon Pay sandbox for requests. To use the Amazon Pay sandbox, call setsandboxmode(true) before calling authorize. Parameters Returns None. See Also sandboxmode - Required - (boolean). true to use the Amazon Pay sandbox to process requests, otherwise false. authorize (page 51) Testing your integration with the Sandbox environment setsitedomain setsitedomain(sitedomain); Sets the domain to use for saving cookies.the domain must match the origin of the current page. Defaults to the full domain for the current page.for example, if you have two pages using the Login with Amazon SDK for JavaScript, site1.example.com and site2.example.com, you would set the site domain to example.com in the header of each site. This will ensure that the cookies on both sites have access to the same cached tokens. Parameters Returns None. See Also sitedomain - Required - ( String ). The site to store Login with Amazon cookies. Must share the origin of the current page. setusecookie (page 57) Login with Amazon How-to Guide Page 56

57 Login with Amazon SDK for JavaScript Reference Guide PDF last generated: August 28, 2017 setusecookie setusecookie(usecookie); Determines whether or not Login with Amazon should use access tokens written to the amazon_login_accesstoken cookie. You can use this value to share an access token with another page. Access tokens will still only grant access to the registered account for whom they were created. When true, the Login with Amazon SDK for JavaScript will check this cookie for cached tokens, and store newly granted tokens in that cookie. Parameters Returns None. See Also usecookie - Required - ( boolean ). true to store the access token from authorizein a cookie, otherwise false. authorize (page 51) setsitedomain (page 56) amazon.login Classes AuthorizeRequest The AuthorizeRequest class is used in response to an authorize (page 51) call. AuthorizeRequestM allows callers to register a callback function or redirect URL to use when the login request is complete. It also allows callers to get the current status of the request. When the request is complete, AuthorizeRequest adds new properties based on the type of authorization request. If the request fails, error properties provide information on the failure. The following table details which properties are added for each response type: Response Type Properties Authorization Response code (page 58) and state (page 59) Access Token Response access_token (page 58), token_type (page 59), expires_in (page 59), and scope (page 59) Error Response error (page 58), error_description (page 58), and error_uri (page 58) oncomplete oncomplete(next); Login with Amazon How-to Guide Page 57

58 Login with Amazon SDK for JavaScript Reference Guide PDF last generated: August 28, 2017 Registers a callback function or sets a redirect URI to call when the authorization request is complete. If this function is called after the request is complete, the function or redirect will happen immediately. If a callback function is used, the AuthorizeRequest will be the first parameter. If a redirect URI is used, the browser will redirect to that URI with the OAuth 2 response parameters included in the query string. If multiple redirect URLs are set, AuthorizeRequest uses the most recent one. Parameters next - (Function or String) A URI to redirect the browser response, or a JavaScript function to call with the authorization response. access_token access_token - (String) The access token issued by the authorization server. code code - (String) An authorization code that can be exchanged for an access token. error error - (String) A short error code indicating why the authorization failed. It can be one of the following: Error Description access_denied The customer or authorization server denied the request. invalid_grant The authorization server denied the request due to inability to use a cached token. invalid_request The request is missing a required parameter, has an invalid value, or is otherwise malformed. invalid_scope One or more of the requested scopes are invalid. server_error The authorization server encountered an unexpected error. This is analogous to a 500 HTTP status code. temporarily_unavailable The authorization server is current unavailable due to a temporary condition. This is analogous to a 503 HTTP status code. unauthorized_client The client is not authorized to perform this request. error_description error_description - (String) A human-readable description of the error. error_uri error_uri - (String) A URI for a web page with more information on the error. Login with Amazon How-to Guide Page 58

59 Login with Amazon SDK for JavaScript Reference Guide PDF last generated: August 28, 2017 expires_in expires_in - (Number) The number of seconds until the access token expires. scope scope - (String) The scope granted by the authorization server for the access token. Must be profile, profile:user_id, postal_code, or some combination. state state - (String) The state value provided to authorize using the options object. status status - (String) The current status of the request. One of queued, in progress, or complete. token_type token_type - (String) The type of token issued. Must be bearer. Login with Amazon How-to Guide Page 59

60 Login with Amazon for ios Apps PDF last generated: August 28, 2017 Login with Amazon for ios Apps LWA for ios Apps Overview Customer Experience in ios Apps Step 1: Install the SDK for ios Step 2: Run the Sample app Step 3: Register your ios app with LWA Step 4: Create a LWA Project Step 5: Add a LWA Button to your App Step 6: Use the SDK for ios APIs Step 7: Integrate with your Existing Account System Reference SDK Docs for LWA ios... 0 Upgrade your ios SDK Login with Amazon How-to Guide Page 60

61 Login with Amazon for ios PDF last generated: August 28, 2017 Login with Amazon for ios Using the Login with Amazon SDK for ios benefits you and your customers: Get started with ease: The instructions below will walk you through using the SDK APIs to integrate Login with Amazon to your ios app as quickly as possible. Let Amazon do the heavy lifting: The SDK APIs handle the entire login flow, from validating login credentials to redirecting your customers back to your app, so you don t have to. Provide your customers with the best login experience: The SDK automatically displays the login and consent screens as best suited for your customers, based on the ios device they use to access your app (learn more (page 63)). Requirements The Login with Amazon SDK for ios is provided by Amazon to help you add Login with Amazon to your ios application. The SDK is intended to be used with the Xcode development environment. The SDK supports apps running on ios 7.0 and later using ARMv7, ARMv7s, ARM64, i386, and x86_64. You can install Xcode from After installing Xcode, you can use the Getting Started steps below to integrate with Login with Amazon. Upgrade your Login with Amazon SDK for ios Use these instructions (page 91) to quickly upgrade an older version of the Login with Amazon SDK for ios to the current version (3.x). Getting Started These topics will show you how to add Login with Amazon to your ios app. After completing these steps you should have a working Login with Amazon button in your app to allow users to log in with their Amazon credentials. 1. Install the Login with Amazon SDK for ios (page 72) 2. Run the Sample App (page 73) 3. Register with Login with Amazon (page 74) 4. Create a Login with Amazon Project (page 77) 5. Add a Login with Amazon Button to Your App (page 81) 6. Use the SDK for ios APIs (page 83) 7. Integrate with Your Existing Account System (page 89) Reference API Reference SDK Release Notes Release Notes (page 8) Login with Amazon How-to Guide Page 61

62 Login with Amazon for ios PDF last generated: August 28, 2017 Older Documentation Using the Login with Amazon SDK for ios APIs (v2.1.2 and below) (page 174) Login with Amazon How-to Guide Page 62

63 Customer Experience in ios apps PDF last generated: August 28, 2017 Customer Experience in ios apps In this section, you will learn about the login flow your customers will experience when they use Login with Amazon within your ios app. The Login with Amazon SDK for ios handles the entire login flow from signing in, to obtaining customer consent, to sharing profile information (if you requested it), to finally redirecting the customer back to your ios app. Note: This information applies to ios apps using the Login with Amazon SDK for ios version 2.1 and above. If you re using an older version of the SDK, use these instructions (page 91) to upgrade. Step 1: The Login with Amazon Button The login flow always begins when your customer clicks a Login with Amazon button in your ios app. We recommend placing these branded buttons on your app s sign in and registration screens. You can also place Login with Amazon buttons in your app s header or footer to enable a quick way for your customers to login to your app using their Amazon credentials. Login with Amazon How-to Guide Page 63

64 Customer Experience in ios apps PDF last generated: August 28, 2017 Login with Amazon How-to Guide Page 64

65 Customer Experience in ios apps PDF last generated: August 28, 2017 For instructions on implementing Login with Amazon buttons, see our Getting Started Guide for ios (page 61). Step 2: The Login Flow The Login with Amazon SDK for ios will automatically provide each of your customers with one of the login flows below: Single Sign-On (SSO) flow (page 65): if the customer is signed into the Amazon Mobile Shopping app on their ios device Safari View Controller (SVC) flow (page 65): if the customer is using ios 9 and above, and is not signed into the Amazon Mobile Shopping app System browser flow (page 66): if the customer is using ios 8 and below, and is not signed into the Amazon Mobile Shopping app Single Sign-on flow If your customer is already signed into the Amazon Mobile Shopping app on their ios device when they click the Login with Amazon button, they will not be prompted to enter their Amazon account credentials. Instead, the Login with Amazon SDK for ios will recognize the customer s authentication to the Amazon Mobile Shopping app, and use that same account information to log them into your ios app. The customer will only need to provide one-time consent to share their profile information with your app (if your app is requesting it). In SSO flow, a user visits your ios app (A). They click the Login with Amazon button (B) and get redirected to a secure, branded page within the Amazon Mobile Shopping app which requests their consent (page 69) (C) to allow your app access to their profile data. If they have already consented, or if your app is not requesting a scope which requires consent, this step will be skipped. Amazon then redirects the user from the consent screen back to your app (D). Safari View Controller flow (ios 9 and above) If your customer does not have the Amazon Mobile Shopping app installed to the device, or they aren t signed into it, Login with Amazon will provide them with a secure, branded screen where they can enter their Amazon account credentials to login to your app. If the customer is using a device with ios 9 or Login with Amazon How-to Guide Page 65

66 Customer Experience in ios apps PDF last generated: August 28, 2017 above, the login screen is displayed securely within your app in Safari View Controller (SVC). After successfully signing in, the customer will need to provide one-time consent (page 69) to share their profile information with your app (if your app is requesting it). Apple introduced SVC in ios 9, and it enables apps to launch external web content in a miniature, in-app version of Safari. SVC is ideal for a login experience, as it does not require your customers to launch other apps or their browser (navigating away from your app in the process) to sign in, and it does not require you to build your own in-app web view to handle the content (which is both time consuming, and a potential security risk, as the native web view has control over sensitive information entered by customers). In SVC flow, a user visits your ios app (A). They click the Login with Amazon button (B) and get redirected to a login screen (page 67) in an SVC window within your app (C). After entering their Amazon account credentials, the SVC window updates and requests consent (page 69) to allow your app access to their profile data (D). If they have already consented, or if your app is not requesting a scope which requires consent, this step will be skipped. Amazon then closes the SVC window so the user can proceed in your app (E). System browser flow (ios 8 and below) If your customer does not have the Amazon Moile Shopping app installed to their device, or they aren t signed into it, Login with Amazon will provide them with a secure, branded screen where they can enter their Amazon account credentials to login to your app. If the customer is using a device with ios 8 or below, the login screen is displayed securely in their system web browser (generally Safari). After successfully signing in, the customer will need to provide one-time consent (page 69) to share their profile information with your app (if your app is requesting it). In system browser flow, a user visits your ios app (A). They click the Login with Amazon button (B) and get redirected out of the app and into a secure, Amazon-branded login screen (page 67) in their system browser (C). After entering their Amazon account credentials, another secure, Amazon-branded page opens in their system browser and requests consent (page 69) to allow your app access to their profile data (D). If they have already consented, or if your app is not requesting a scope which requires consent, this step will be skipped. Amazon then redirects the user from their browser window back to your app (E). Login with Amazon How-to Guide Page 66

67 Customer Experience in ios apps PDF last generated: August 28, 2017 Step 3: The Login Screen In both SVC and system browser flow, the Amazon customer will see the login screen immediately after clicking a Login with Amazon button. Note: The login screen is not shown during single sign-on flow. Login with Amazon How-to Guide Page 67

68 Customer Experience in ios apps PDF last generated: August 28, 2017 The Amazon-branded login screen consists of the following: The app name you select when you register with Login with Amazon (page 74). A Forgot your password? link the customer can click to reset their Amazon.com password. Fields for the customer to enter in their Amazon.com account credentials. A Show password checkbox the customer can select to display the password they re typing in. By default, the password will be shown. A Keep me signed in checkbox the customer can select to skip the login and consent screens the next time they visit your app and use Login with Amazon. Instead, the next time they log in to your app they will see an acknowledgement screen (below), where they can click Continue to login to your app with their Amazon account credentials. Login with Amazon How-to Guide Page 68

69 Customer Experience in ios apps PDF last generated: August 28, 2017 A secure Sign in button the customer can click when they re ready to authenticate to Amazon using their account credentials. Clicking Sign in will redirect the customer to the consent screen, or to your app, as described in the Login Flows (page 65) sections above. A Create a new Amazon account button the customer can click to create a new account, then sign into your app. A list of benefits for using Login with Amazon, and a Learn More link the customer can click for more details. Links to the Conditions of Use and Privacy Notice relevant to their usage of Login with Amazon. Step 4: The Consent Screen If your app requests access to a customer s profile (page 141) information (such as their name, address, or postal code), the customer will be made aware of this via the consent screen. Login with Amazon How-to Guide Page 69

70 Customer Experience in ios apps PDF last generated: August 28, 2017 The Amazon-branded consent screen consists of the following: A drop-down list showing the customer s name in the upper, right corner. Clicking the drop-down arrow will allow the customer to choose another Amazon account to authenticate with. Note: This link is not shown in SSO flow. SSO flow will always automatically use the Amazon account already authenticated to the Amazon Mobile Shopping app. The app name and logo you provide when you register with Login with Amazon (page 74). A list of each permission requested by your app. An I agree button the customer can click if they agree to share their information. Clicking I agree will redirect the customer back to your app as described in the Login Flows (page 65) sections Login with Amazon How-to Guide Page 70

71 Customer Experience in ios apps PDF last generated: August 28, 2017 above. Note: A customer only needs to provide their consent once per app, per device. After they have consented to sharing their information with your ios app once, they will not be asked again, unless they intentionally remove their permissions from the Your Account link. A Cancel button the customer can click if they do not agree to share their information. Clicking Cancel will bring the customer back to your app unauthenticated. A Your Account link the customer can click to remove permissions they ve granted to apps via Login with Amazon. A link to the privacy policy for your app that you provide when you register with Login with Amazon (page 74). Step 5: Success! After a customer has completed the login flow, they are automatically redirected back to your ios app. Login with Amazon How-to Guide Page 71

72 Install the Login with Amazon SDK for ios PDF last generated: August 28, 2017 Install the Login with Amazon SDK for ios The Login with Amazon SDK for ios includes the framework, supporting documentation, and a sample application that allows a user to login and view their profile data. If you have not installed Xcode, you can get it from 1. Download the Amazon Mobile App SDK for ios and extract the files to a directory on your hard drive. 2. You should see a LoginWithAmazon.framework directory in the LoginWithAmazon parent directory. This contains the Login with Amazon library. 3. Open docs/contents/resources/documents/index.html to view the Login with Amazon ios API Reference. 4. See Install the Login with Amazon Library (page 77) for instructions on how to add the library to an ios project. After the Login with Amazon SDK for ios is installed, you can Create a New Login with Amazon Project (page 77) after you Register with Login with Amazon (page 74). Login with Amazon How-to Guide Page 72

73 Run the Sample App PDF last generated: August 28, 2017 Run the Sample App To run the sample application, open the sample in Xcode. 1. Download the Amazon Mobile App SDK for ios and extract the files to a directory on your hard drive. 2. Start Xcode. If the Welcome to Xcode dialog pops up, click Open Other. Otherwise, from the main menu, click File and select Open. 3. Navigate to the folder where you downloaded the SDK, and select LoginWithAmazon/ examples/sampleloginwithamazonapp/loginwithamazonsample/ LoginWithAmazonSample.xcodeproj. Click Open. 4. The sample project should now load. When it is finished, choose Product from the main menu and select Run. Login with Amazon How-to Guide Page 73

74 Register with Login with Amazon PDF last generated: August 28, 2017 Register with Login with Amazon Before you can use Login with Amazon in your ios app, you must register the application with Login with Amazon. Your Login with Amazon application registration 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 websites and 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 your ios app for use with Login with Amazon. Register your Security Profile If this is your first time using the Developer Console, you will need to create a security profile for your website or mobile app. 1. Visit You will be asked to login to the Developer Console, which handles application registration for Login with Amazon. If this is your first time using the Developer Console, you will be asked to set up an account. 2. Click Create a New Security Profile. This will take you to the Security Profile Management page. 1. Enter a Name and a Description for your security profile. A security profile associates user data and security credentials with one or more related apps. 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. 2. You must enter a Consent Privacy Notice URL for your application now. The Privacy Notice URL is the location of your company or application s privacy policy (for example, ). This link is displayed to users on the consent screen. 3. If you want to add a Consent Logo Image for your application, click Upload Image. This logo is displayed on the sign-in and consent screen to represent your business or website. 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. 3. Click Save. Your security profile should look similar to this: Login with Amazon How-to Guide Page 74

75 Register with Login with Amazon PDF last generated: August 28, 2017 After your basic security profile is saved, you can associate specific websites and mobile apps with this security profile. Add your ios App to your Security Profile After creating a security profile on the Developer Console, you can add settings for specific websites and mobile apps that will use Login with Amazon with that profile. To register a new ios app, you have to specify the package name and signature for the app project. Login with Amazon will use these values to generate an API key. The API key will grant your app access to the Login with Amazon authorization service. Follow these steps to add an ios app to your profile: 1. Visit 2. Go to the security profile that you want to use for your app. 1. Locate the security profile you want to modify from the table. 2. Hover over the button shown in the Manage column. 3. Select the ios Settings menu item. Note: If your desired security profile is not shown in the table, it is not yet enabled for Login with Amazon. In this case, use the drop-down menu above the table to Select a Security Profile, then click Confirm. You ll be required to enter a Consent Privacy Notice URL and optionally select a Consent Logo Image, both of which will be displayed on the sign-in and consent screens. If you don t have an existing security profile for your app, see Register Your Security Profile (page 74). 3. Enter the API Key Name that your app will use to authenticate with Login with Amazon. This does not have to be the official name of your app. It simply identifies this particular ios app among the apps and websites registered to your security profile. 4. Enter your Bundle ID. This must match the bundle identifier of your ios project. To determine your bundle identifier, open the project in Xcode. Open the properties list for the project ( <project>-info.plist ) in the Project Navigator. The Bundle identifier is one of the properties in the list. 5. Click Generate New Key. If different versions of your app have different bundle IDs, such as for one or more testing versions and a production version, each version requires its own API Key. From the ios Settings of your app, click the Add an API Key button to create additional keys for your app (one per version). ios Bundle ID and API Keys The Bundle identifier is unique to every ios app. Login with Amazon uses the Bundle ID to construct your API Key. The API Key enables the Login with Amazon authorization service to recognize your app. Determining a Bundle Identifier for an ios App 1. Open your app project in Xcode. 2. Open the Information Property List for the project ( <project>-info.plist ) in the Project Navigator. 3. Find Bundle identifier in the list of properties. Retrieving an ios API Key After you have associated an ios app with a security profile, you can retrieve the API key from the ios Settings tab in your security profile. You will need to place that API key into your project. Until you do, the app will not be authorized to communicate with the Login with Amazon authorization service. Login with Amazon How-to Guide Page 75

76 Register with Login with Amazon PDF last generated: August 28, Visit 2. Go to the security profile that you want to use for your app: Locate the security profile you want to modify from the table. Hover over the button shown in the Manage column. Select the ios Settings menu item. 3. Find the API Key Name for the key on the list, then click Show in the associated Key column. Copy the API Key that appears in the popup window. Note: The API Key is based, in part, on the time it is generated. Thus, subsequent API Keys you generate may differ from the original. You can use any of these API Keys in your app as they are all valid. You can also delete or edit any of your keys by hovering over the icon and selecting Edit or Delete. Any mistakenly deleted keys can be restored by clicking Show Deleted API Keys, then clicking Restore next to the name of the key you d like to recover. 4. See Add Your API Key to Your App Property List (page 79) for instructions on adding the API key to your app. Delete your Security Profile If needed, you can delete any security profile not associated with an app distributed through the Amazon Appstore. Navigate to the Security Profile Management page, select a profile, and then click Delete Security Profile. A confirmation form appears. Type the word delete into the text field then click Delete to confirm the action. If a security profile is mistakenly deleted, it s fully recoverable from the Security Profile Management page. Click the Show Deleted Security Profiles button, click on the name of the profile you d like to restore, then click Restore Security Profile. A confirmation form appears. Click the Restore button to recover the security profile, including its Web, Android/Kindle, and ios settings. Login with Amazon How-to Guide Page 76

77 Create a Login with Amazon Project PDF last generated: August 28, 2017 Create a Login with Amazon Project If you do not yet have an app project for using Login with Amazon, you should create one now. If you have an existing app, skip to Install the Login with Amazon Library (page 77) below. Create a New Project in Xcode 1. Launch Xcode. 2. If you are presented with a Welcome to Xcode dialog, select Create a New Xcode Project. Otherwise, in the File menu, select New and Project. 3. Select the type of project you wish to create and click Next. 4. Enter a Product Name and a Company Identifier. Note your Bundle Identifier, and click Next. 5. Select a location to store your project and click Create. You will now have a new project that you can use to call Login with Amazon. Install the Login with Amazon Library If you have not yet downloaded the Login with Amazon SDK for ios, see Install the Login with Amazon SDK for ios (page 72). A Login with Amazon project must link the LoginWithAmazon.framework and Security.framework libraries. You will also need to configure the framework search path to find the Login with Amazon headers. 1. With your project open in Xcode, select the Frameworks folder, then click File from the main menu and select Add Files to project. 2. In the dialog, select LoginWithAmazon.framework and click Add. If you used the Login with Amazon 1.0 library, delete the login-with-amazon-sdk directory and login-with-amazonsdk.a from the Frameworks. Click Edit from the main menu and select Delete. 3. Select the name of your project in the Project Navigator. The Project Editor will appear in the editor area of the Xcode workspace. 4. Click your project name under Targets, and select Build Phases. Expand Link Binary with Libraries and click the plus sign to add a library. 5. In the search box, type Security.framework. Select Security.framework and click Add. 6. In the search box, type SafariServices.framework. Select SafariServices.framework and click Add. 7. In the search box, type CoreGraphics.framework. Select CoreGraphics.framework and click Add. Login with Amazon How-to Guide Page 77

78 Create a Login with Amazon Project PDF last generated: August 28, Select Build Settings. Click All to view all settings. 9. Under Search Paths, ensure that the LoginWithAmazon.framework directory is in the Framework Search Paths. For example: If you used the Login with Amazon 1.0 library, you can remove any references to the 1.0 library path in the Header Search Paths or Library Search Paths. 10. In the main menu, click Product and select Build. The build should complete successfully. Before building your project, if you used the Login with Amazon 1.0 library, replace #import "AIMobileLib.h", #import "AIAuthenticationDelegate.h", or #import "AIError.h" in your source files with #import <LoginWithAmazon/LoginWithAmazon.h>. Login with Amazon How-to Guide Page 78

79 Create a Login with Amazon Project PDF last generated: August 28, 2017 LoginWithAmazon.h includes all the Login with Amazon headers at once. Add your API Key to your App Property List When you register your ios application with Login with Amazon, you are assigned an API key. This is an identifier that the Amazon Mobile Library will use to identify your application to the Login with Amazon authorization service. The Amazon Mobile Library loads this value at runtime from the APIKey property value in your application s Information Property List. 1. With your project open, select the Supporting Files folder, then select the <project>- Info.plist file (where <project> is the name of your project). This should open the property list for editing: 2. Make sure none of the entries are selected. Then, in the main menu, click Editor, and Add Item. Type APIKey and press Enter. 3. Double-click under the Value column to add a value. Paste your API Key as the value. Add a URL Scheme to Your App Property List When the user logs in, they will be presented with an Amazon login page. In order for your app to receive confirmation of their login, you must add a URL scheme so the web page can redirect back to your app. The URL scheme must be declared as amzn-<bundleid> (for example, amzn-com.example.app ). For more information, see Using URL Schemes to Communicate with Apps on developer.apple.com. 1. With your project open, select the Supporting Files folder, then select the <project>- Info.plist file (where <project> is the name of your project). This should open the property list for editing: Login with Amazon How-to Guide Page 79

80 Create a Login with Amazon Project PDF last generated: August 28, Make sure none of the entries are selected. Then, in the main menu, click Editor, and Add Item. Type or select URL types and press Enter. 3. Expand URL types to reveal Item 0. Select Item 0 and, from the main menu, click Editor and Add Item. Type or select URL Identifier and press Enter. 4. Select Item 0 under URL Identifier and double-click under the Value column to add a value. The value is your bundle ID. You can find your bundle ID listed as Bundle identifier in the property list. 5. Select Item 0 under URL types and, from the main menu, click Editor and Add Item. Type or select URL Schemes and press Enter. 6. Select Item 0 under URL Schemes and double-click under the Value column to add a value. The value is your bundle ID with amzn- prepended (for example, amzn-com.example.app). You can find your bundle ID listed as Bundle identifier in the property list. Login with Amazon How-to Guide Page 80

81 Add a Login with Amazon Button to Your App PDF last generated: August 28, 2017 Add a Login with Amazon Button to Your App Login with Amazon provides several standard buttons you can use to prompt users to login from your app. This section gives steps for downloading an official Login with Amazon image and pairing it with an ios UIButton. 1. Add a standard UIButton to your app. For a tutorial on how to add a button to an app, see Creating and Configuring View Objects and Start Developing ios Apps Today on developer.apple.com. 2. Add the Touch Up Inside event for the button to a method named onloginbuttonclicked. Leave the implementation blank for now. The Creating and Configuring View Objects and Start Developing ios Apps Today on developer.apple.com tutorial includes steps on adding a button event. 3. Choose a button image. Consult our Login with Amazon Style Guidelines (page 154) for a list of buttons you can use in your app. From there, you can download a copy of the LWA_for_iOS.zip file. Find your preferred button in both the 1x and 2x directories and extract them from the zip. Extract the _Pressed version of your button if you want to show the button in a Selected state. 4. Add the images to your project. 1. In Xcode, with your project loaded, click File from the main menu and select Add Files to project. 2. In the dialog, select the button image file(s) you downloaded and click Add. 3. The buttons should now be in the project under your project directory. Move them to the Supporting Files folder. 5. Add the image to your button. To enable the image for your button, you can modify the button attribute or use the setimage:forstate method on the UIButton object. Follow these steps to modify the image attribute for your button: 1. Open the storyboard for your app. 2. Select the button in your storyboard by clicking on it or selecting it from the View Controller Scene tree. 3. In the Utilities window, open the Attributes Inspector. Login with Amazon How-to Guide Page 81

82 Add a Login with Amazon Button to Your App PDF last generated: August 28, At the top of the Attribute Inspector, set the Type of button to System. 5. In the second group of settings, select Default for State Config. 6. In the second group of settings, drop down the Image setting. 7. Select the Login with Amazon button graphic you added to the project. Do not select the 2x version: it will be loaded automatically on high density display (Retina) devices. 8. Set the same image for the Background setting. 9. If you want to specify a pressed version of the button, select Selected for State Config, and set the Image to the _Pressed version of your button. 10. On the storyboard, adjust the size of your button to accommodate the image, if necessary. Login with Amazon How-to Guide Page 82

83 Use the Login with Amazon SDK for ios APIs PDF last generated: August 28, 2017 Use the Login with Amazon SDK for ios APIs Connect the AppDelegate Implement application:openurl:options: in the class in your project that handles the UIApplicationDelegate protocol. By default, this will be the AppDelegate class. When a user successfully logs into your app using Login with Amazon, they will be redirected from the Amazon login screen back to your app based on the URL Scheme (page 79) you added to your App Property List earlier. In order to handle this redirect, you must implement the application:openurl:options: method, which returns YES if the URL is successfully handled. The Login with Amazon SDK for ios provides a library function, handleopenurl:sourceapplication: which handles any redirect URL sent from Amazon pages. It returns YES if the URL is successfully handled by the SDK. Call this method within the application:openurl:options: method. To invoke this method, you will need to import <LoginWithAmazon/LoginWithAmazon.h>. import AppDelegate - (BOOL)application:(UIApplication *)application openurl:(nsurl *) url options:(nsdictionary<uiapplicationopenurloptionskey,id> *)optio ns { return [AMZNAuthorizationManager handleopenurl:url sourceapplication:options[uiapplicationopenurloptionssourceappli Handle the Login Button and Get Profile Data This section explains how to call the authorize:withhandler: API to login a user. This includes creating an onloginbuttonclicked: listener for your Login with Amazon button. 1. Add Login with Amazon to your ios project. For instructions, see Create a Login with Amazon Project (page 77). 2. Import the Login with Amazon API to your source file. To import the Login with Amazon API, add the following #import statements to your source file: #import <LoginWithAmazon/LoginWithAmazon.h> 3. Call authorize:withhandler: in onloginbuttonclicked. Login with Amazon How-to Guide Page 83

84 Use the Login with Amazon SDK for ios APIs PDF last generated: August 28, 2017 If you followed the steps in Add a Login with Amazon Button to Your App, you should have an onloginbuttonclicked: method linked to a Login with Amazon button. In that method, call authorize:withhandler: to prompt the user to login and authorize your application. This method will enable the user to sign in and consent to the requested information in one of the following ways: 1. Switches to web view in a secure context (if the Amazon Shopping app is installed to the device) 2. Switches to Safari View Controller (on ios 9 and later) 3. Switches to the system browser (on ios 8 and earlier) The secure context for the first option is available when the Amazon Shopping app is installed to the device. If the user is already signed in to the Amazon Shopping app, this API will skip the sign in page, leading to a Single Sign-On (SSO) experience. See Customer Experience for ios apps (page 63) to learn more. The first parameter to authorize:withhandler: is an AMZNAuthorizeRequest object that indicates what scope your application is requesting authorization for. A scope encompasses the user data you are requesting from Login with Amazon. The first time a user logs in to your app, they will be presented with a list of the data you are requesting and asked for approval. Login with Amazon currently supports the following scopes: profile (gives access to the user s name, address, and Amazon account ID), profile:user_id (gives access to the user s Amazon account ID only), and postal_code (gives access to the user s zip/postal code on file for their Amazon account). Use the methods defined in AMZNProfileScope to get a scope object and add it to your AMZNAuthorizeRequest object. See the sample code below for details. The second parameter to authorize:withhandler: is AMZNAuthorizationRequestHandler, described in the next step. 4. Create an AMZNAuthorizationRequestHandler block object. AMZNAuthorizationRequestHandler processes the result of the authorize:withhandler: call. To learn more about objective-c blocks, see Working with Blocks on developer.apple.com. The first parameter of AMZNAuthorizationRequestHandler is an AMZNAuthorizeResult object. After a user is authorized successfully, AMZNAuthorizeResult will contain an access token which can be used to access a user s profile data, and an AMZNUser object, which contains the user s profile data. The second parameter of AMZNAuthorizationRequestHandler is a Boolean called userdidcancel. This parameter will be set to true if the user: Closes the Safari View Controller during login and authorization (on ios 9 and later) Closes the sign in or consent screens from the web view in the Amazon Shopping app Cancels the login or rejects authorization The third parameter of AMZNAuthorizationRequestHandler is an NSError object which contains error details if the login and authorization fails due to the SDK or authorization server. Login with Amazon How-to Guide Page 84

85 Use the Login with Amazon SDK for ios APIs PDF last generated: August 28, (IBAction)onLogInButtonClicked:(id)sender { // Build an authorize request. AMZNAuthorizeRequest *request = [[AMZNAuthorizeRequest alloc] i nit]; request.scopes = [NSArray arraywithobjects: // [AMZNProfileScope userid], [AMZNProfileScope profile], [AMZNProfileScope postalcode]]; // Make an Authorize call to the Login with Amazon SDK. [[AMZNAuthorizationManager sharedmanager] authorize:request withhandler:^(amznauthorizeresult *result, BOOL userdidcancel, NSError *error) { if (error) { // Handle errors from the SDK or authorizat ion server. else if (userdidcancel) { // Handle errors caused when user cancels l ogin. else { // Authentication was successful. // Obtain the access token and user profil e data. NSString *accesstoken = result.token; AMZNUser *user = result.user; NSString *userid = user.userid; ]; Fetch User Profile Data As long as a user is logged in and authorized to your app, you can fetch their user profile data at any time. This section explains how to use the fetch: method of the AMZNUser class to retrieve the most up-todate user profile data for users who are currently authorized. The profile data you can retrieve is based on the scope indicated in the authorize call. 1. Call AMZNUser fetch:. This method will fetch profile data via an AMZNUserFetchRequestHandler block object. The first parameter to AMZNUserRequestHandler is an AMZNUser object. The AMZNUser object can include a userid, name, , and postalcode, depending on the requested scope. Login with Amazon How-to Guide Page 85

86 Use the Login with Amazon SDK for ios APIs PDF last generated: August 28, 2017 [AMZNUser fetch:^(amznuser *user, NSError *error) { if (error) { // Error from the SDK, or no user has authorized to the app. else if (user) { NSString *userid = user.userid; //NSString *name = user.name; //NSString * = user. ; //NSString *postalcode = user.postalcode; ]; Check for User Login at Startup If a user logs into your app, closes the app, and restarts the app later, the app is still authorized to retrieve data. The user is not logged out automatically. At startup, you can show the user as logged in if your app is still authorized. This section explains how to use authorize:withhandler: to see if the app is still authorized. 1. Create an AMZNAuthorizeRequest object and specify scopes that indicate the user data your application is requesting authorization for. For more information on scopes, see Handle the Login Button and Get Profile Data above. 2. Set AMZNAuthorizeRequest.interactiveStrategy to AMZNInteractiveStrategyNever. AMZNAuthorizeRequest supports multiple strategies for prompting user login: AMZNInteractiveStrategyAuto (default): The SDK looks for a locally stored authorization grant from previous authorize:withhandler: responses. If one is available, valid, and contains all requested scopes, the SDK will return a successful response via AMZNAuthorizationRequestHandler, and will not prompt the user to login. Otherwise, the user will be prompted to login. AMZNInteractiveStrategyAlways: The SDK will always prompt the user to login regardless of whether they have previously been authorized to use the app. When the user is prompted, the SDK will remove all locally cached authorization grants for the app. AMZNInteractiveStrategyNever: The SDK looks for a locally stored authorization grant from previous authorize:withhandler responses. If one is available, valid, and contains all requested scopes, the SDK will return an AMZNAuthorizeResult object that contains an access token and user profile data. Otherwise, it will return an NSError object via AMZNAuthorizationRequestHandler. Login with Amazon How-to Guide Page 86

87 Use the Login with Amazon SDK for ios APIs PDF last generated: August 28, 2017 // Build an authorize request. AMZNAuthorizeRequest *request = [[AMZNAuthorizeRequest alloc] init]; request.scopes = [NSArray arraywithobjects: // [AMZNProfileScope userid], [AMZNProfileScope profile], [AMZNProfileScope postalcode]]; request.interactivestrategy = AMZNInteractiveStrategyNever; [[AMZNAuthorizationManager sharedmanager] authorize:request withhandler:^(amznauthorizeresult *result, BOOL userdidcancel, NSError *error) { if (error) { // Error from the SDK, indicating the user was not p reviously authorized to your app for the requested scopes. else { // The user was previously authorized to your app. // Obtain the access token and user profile data. NSString *accesstoken = result.token; AMZNUser *user = result.user; NSString *userid = user.userid; ]; Clear Authorization Data and Log Out Users This section explains how to use the signout method to clear the user s authorization data from both the AIMobileLib local data store, and the authorization server. The user will have to login again in order for the app to retrieve profile data. Use this method to log out a user, or to troubleshoot login problems in the app. 1. Implement a logout mechanism. When a user has successfully logged in, you should provide a logout mechanism so they can clear their profile data and previously authorized scopes. Your mechanism might be a hyperlink, button, or a menu item. 2. Call signout:. Call signout: in your logout handler to remove a user s authorization data (access tokens, profile) from the local store, and their authentication state from the server. The input parameter to signout is an AMZNAuthorizationRequestHandler block object. The block should detect and handle NSError objects, which are returned when signout: fails. Login with Amazon How-to Guide Page 87

88 Use the Login with Amazon SDK for ios APIs PDF last generated: August 28, 2017 [[AMZNAuthorizationManager sharedmanager] signout:^(nserror * _Nu llable error) { if (!error) { // error from the SDK or Login with Amazon authorization serv er. ]; Test your Integration Launch your app in an ios device or simulator and confirm you can log in with your Amazon.com credentials. Important: When testing on ios10 simulators, you may see the error message APIKey for the Application is invalid for an authorizeuserforscopes request, or Unknown Error Code for an clearauthorizationstate request. This is a known bug with Apple which occurs when the SDK tries to access the keychain. Until Apple resolves the bug, you can work around it by enabling Keychain Sharing for your app under the Capabilities tab of your app s target. This bug only impacts simulators. You can test on actual ios10 devices without using any workaround. Login with Amazon How-to Guide Page 88

89 Integrate with Your Existing Account System PDF last generated: August 28, 2017 Integrate with Your Existing Account System In this section, we ll discuss how to integrate customer profile data from Login with Amazon user accounts with a mobile app that already has an account management system. You will learn how to enable your site or app to let users log in using their Amazon accounts, and how to let existing users attach their Amazon identity so they can log in with their Amazon credentials. Prerequisites This guide assumes you have previously signed up for Login with Amazon, registered your mobile app as a Login with Amazon application, and have the appropriate SDK or server-side methods to communicate with the Login with Amazon service. This guide also assumes your mobile app currently has these features: 1. An account database where you record information about each user account. Users have some kind of unique identifier. Users currently sign in using their username/password. 2. A sign-in page for registered users. 3. A registration page for registering new users by taking in profile information (name, , and so on). 4. Some mechanism for managing authentication state after the user successfully signs in so that the next page knows that the user is currently signed in (for example, storing that info in cookies or a back-end database). Make 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 user_id property, in the form amzn1.accountvalue. For example: amzn1.account.k2li23kl2lk2 Set up Login with Amazon Using the relevant SDK or server-side methods for your mobile app, provide a method for the user to log in with their Amazon credentials. This includes making changes to the UI of your sign-in and registration pages. Your sign-in page will need to have an option for users to select the Login with Amazon button to authenticate using their Amazon credentials. For more information, see ios (page 61). Obtain and Secure Amazon Customer Profile Data Once the user has interacted with the Login with Amazon service to sign in (and, on the first visit, authorize data sharing), you will receive an authorization response from Login with Amazon. When you receive an authorization response you should: 1. Send the access token in your authorization response to your server using HTTPS. 2. From server-side, call the profile endpoint using the access token. See our developer guide (page 43) for details on calling the profile endpoint, including code samples in multiple Login with Amazon How-to Guide Page 89

90 Integrate with Your Existing Account System PDF last generated: August 28, 2017 languages. Login with Amazon will return a customer profile response with values (such as user_id, , name, and/or postal_code ) you can keep on your server. Taking this step will ensure the profile data you save to your server belongs to the customer who is signed into your client. 3. Search for the user s Amazon account identifier within your user database to see if they have signed in before. If they have not then you will need to create a new account for them. 4. Search for the user s address in your account system. If they have a local account with that address, prompt them to enter their local credentials to allow Login with Amazon to log in that account. 5. Create cookies in the user s browser or otherwise record them as authenticated with your site or app. Find or Create a Local Account The user profile response will always contain a parameter named user_id. The value of this parameter is a string which permanently and uniquely identifies the Amazon account to which the user has signed in. Amazon will always return the same identifier for each user. You should search your user database to see if this Amazon account has previously signed in to your site or app. If you have not seen the Amazon account before, and it doesn t match an existing account, you will need to create a new entry in your local account database and associate it with the Amazon account identifier for the next time they sign in. If the Amazon account does match an existing local account, prompt the user for their local password to link the two accounts. The authentication response may contain additional user data. For example, the user s name and address. You can copy this information into your local account database when creating new accounts or to update existing accounts (for example, the user could have changed their address on Amazon since the last time they signed in). If you need to collect additional information from the user before creating an account then this is where you will want to display a registration page. You can prefill it with the information you received in the authentication response or you can show just the additional fields that you require. Tip: If your local account management includes resetting passwords, you might want to ensure that Login with Amazon users do not get confused about how that affects 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. Mark the User as Authenticated After you have have received a valid authentication response and found or created a corresponding account in your own account database, mark the user has having authenticated. This step can work exactly the same as in your current authentication system. Login with Amazon How-to Guide Page 90

91 Login with Amazon SDK for ios 3.x Migration Guide PDF last generated: August 28, 2017 Login with Amazon SDK for ios 3.x Migration Guide This guide explains how to migrate your app from using the Login with Amazon SDK for ios v2.1.2 (or lower) to the Login with Amazon SDK for ios v3.x. You will need to migrate from using APIs under the AIMobileLib class to new APIs under AMZNAuthorizationManager or AMZNUser. If you ve not yet integrated Login with Amazon into your app, review the full set of instructions in our Getting Started Guide for ios (page 61). How to Upgrade 1. Download the latest version of the Amazon Apps & Games Services SDK for ios. 2. Extract the files to a directory on your hard drive. 3. Update libraries and frameworks, then build the project (for more detailed instructions, see Creating a Login with Amazon Project (page 77)): 1. If you used the Login with Amazon 1.0 or 2.0 library, delete the login-with-amazonsdk directory and login-with-amazonsdk.a from the Frameworks folder. Click Edit from the main menu and select Delete. Also, remove any reference to old versions of LoginWithAmazon.framework if your project was using one. 2. With your project open in Xcode, select the Frameworks folder, click File from the main menu, and then select Add files to <project>. In the dialog, select LoginWithAmazon.framework (v3.0.x) and click Add. 3. In the Build Phases section of your project, expand Link Binary with Libraries and click the plus sign to add the following frameworks to your project: Security.framework, SafariServices.framework, CoreGraphics.framework. 4. Select Build Settings, then click All. Ensure the LoginWithAmazon.framework directory is in the Framework Search Paths. If you used the Login with Amazon 1.0 or 2.0 library, you can remove any references to the 1.0 or 2.0 library paths in the Header Search Paths or Library Search Paths. 5. From the main menu, click Product and select Build. The build should complete successfully. Before building your project, if you used the Login with Amazon 1.0 or 2.0 library, replace #import "AIMobileLib.h", #import "AIAuthenticationDelegate.h", or #import "AIError.h" in your source files with #import <LoginWithAmazon/LoginWithAmazon.h>. LoginWithAmazon.h includes all of the Login with Amazon headers at once. 4. Migrate to the new APIs introduced in the Login with Amazon 3.0 library as instructed below. Handle the Login Button and Get User Profile Data Call the authorize:withhandler method. In the new LWA SDK for ios, instead of calling authorizeuserforscopes:delegate:options:, switch to call authorize:withhandler:. To call this new API, you need to define an AMZNAuthorizeRequest object. This request object allows you to customize input parameters to the authorize:withhandler: API. Some properties commonly passed to the AMZNAuthorizeRequest class are: scopes : Defines what scopes to request authorization for. The AMZNProfileScope class defines scopes provided by Login with Amazon. If you are using APIs for other Amazon products, Login with Amazon How-to Guide Page 91

92 Login with Amazon SDK for ios 3.x Migration Guide PDF last generated: August 28, 2017 you will find scopes supported by those products included in their own documentation. interactivestrategy : This is a newly-defined property that determines whether to prompt users to sign in when authorize:withhandler: is called. The LWA SDK currently supports following strategies for prompting user sign in: AMZNInteractiveStrategyAuto (default): The SDK looks for a locally stored authorization grant from previous authorize:withhandler: responses. If one is available, valid, and contains all requested scopes, the SDK will return a successful response via AMZNAuthorizationRequestHandler, and will not prompt the user to login. Otherwise, the user will be prompted to login. AMZNInteractiveStrategyAlways : The SDK will always prompt the user to login regardless of whether they have previously been authorized to use the app. When the user is prompted, the SDK will remove all locally cached authorization grants for the app. AMZNInteractiveStrategyNever : The SDK looks for a locally stored authorization grant from previous authorize:withhandler responses. If one is available, valid, and contains all requested scopes, the SDK will return an AMZNAuthorizeResult object that contains an access token and user profile data. Otherwise, it will return an NSError object via AMZNAuthorizationRequestHandler. For a full list of properties in the AMZNAuthorizeRequest object, see the class reference in the SDK documentation. Add scopes to AMZNAuthorizeRequest. In the new LWA SDK for ios, we use the AMZNScope object to represent a scope. To request scopes, you will need to add AMZNScope objects to your AMZNAuthorizeRequest. There are two options: To request customer profile scopes provided by Login with Amazon, use the methods defined in the AMZNProfileScope class: Scope name Method in AMZNProfileScope class profile [AMZNProfileScope profile] postal_code [AMZNProfileScope postalcode] profile:user_id [AMZNProfileScope userid] Alternatively, you can create an AMZNScope object using AMZNScopeFactory : [AMZNScopeFactory scopewithname:@"profile"] Use this alternate method to request scopes provided by other Amazon products. Use a block object to handle the callback. Instead of using delegate methods, the new LWA SDK for ios changes to use objective-c block objects to handle callback functions. This change eliminates the need to implement two delegate methods (one for requestdidsucceed: and one for requestdidfail: ). Instead, implement a single Login with Amazon How-to Guide Page 92

93 Login with Amazon SDK for ios 3.x Migration Guide PDF last generated: August 28, 2017 AMZNAuthorizationRequestHandler block object to process the result of the authorize:withhandler: call. The AMZNAuthorizationRequestHandler block contains three arguments: 1. result : An AMZNAuthorizeResult object that contains the response from the Login with Amazon authorization server when the authorize:withhandler: call succeeds. The result may include: token : If you requested an access token (occurs by default), the LWA authorization server returns an access token in the result object. You no longer need to request tokens by making a separate call to the getaccesstokenforscopes:withoverrideparams:delegate: API in the success delegate method of the authorizeuserforscopes:delegate: API (a requirement in previous versions of the LWA SDK for ios). user : If you requested a profile scope, the result object contains an AMZNUser object with the requested customer profile data. You no longer need to call getprofile: from the success delegate method of authorizeuserforscopes:delegate: (a requirement in previous versions of the LWA SDK for ios). See the class reference for AMZNUser to find more information about obtaining profile data. 2. userdidcancel : A boolean flag set to true if the customer chooses to cancel during the login flow. 3. error : An NSError object returned when internal errors occurred in the LWA SDK for ios while processing the authorize:withhandler: request. Login with Amazon How-to Guide Page 93

94 Login with Amazon SDK for ios 3.x Migration Guide PDF last generated: August 28, (IBAction)onLogInButtonClicked:(id)sender { // Build an authorize request. AMZNAuthorizeRequest *request = [[AMZNAuthorizeRequest allo c] init]; request.scopes = [NSArray arraywithobjects: // [AMZNProfileScope userid], [AMZNProfileScope profile], [AMZNProfileScope postalcode]]; n server. in. ata. // Make an Authorize call to the Login with Amazon SDK. [[AMZNAuthorizationManager sharedmanager] authorize:request withhandler:^(amznauthorizeresult *result, BOOL userdidcancel, NSError *error) { if (error) { // Handle errors from the SDK or authorizatio ]; else if (userdidcancel) { // Handle errors caused when user cancels log else { // Authentication was successful. // Obtain the access token and user profile d NSString *accesstoken = result.token; AMZNUser *user = result.user; NSString *userid = user.userid; Fetch User Profile Data As long as a user is logged in and authorized to your app, you can fetch their user profile data at any time. The new LWA ios SDK for ios introduces the AMZNUser class to help you better manage customer profile data. Some of the commonly used customer profile data is defined as properties in this class: 1. userid : the unique identifier of an customer. 2. name : the name of the customer the address of the customer. 4. postalcode : the postal code of the customer. 5. profiledata : A dictionary that contains all available profile data of the customer. Note: To obtain this customer data, you will first need to request authorization for one or more profile scopes as described above. The new LWA SDK for ios provides you two new options to request customer profile data, which replace calls to the getprofile: API required by previous versions of the SDK: 1. When the customer is not signed in to your app, call authorize:withhandler: to retrieve an Login with Amazon How-to Guide Page 94

95 Login with Amazon SDK for ios 3.x Migration Guide PDF last generated: August 28, 2017 AMZNUser object in the result object of your AMZNAuthorizationRequestHandler block. 2. If the customer is currently signed in to your app, call the fetch: API in the AMZNUser class to get the most up-to-date customer profile data. he app. [AMZNUser fetch:^(amznuser *user, NSError *error) { if (error) { // Error from the SDK, or no user has authorized to t else if (user) { NSString *userid = user.userid; //NSString *name = user.name; //NSString * = user. ; //NSString *postalcode = user.postalcode; nary ]; // To get all available user profile data in a dictio NSDictionary *profiledata = user.profiledata Check for User Login at Startup In the new LWA SDK for ios, you no longer need to call getaccesstokenforscopes:withoverrideparams:delegate:. Instead, switch to call the authorize:withhandler: API to detect whether your app is still authorized. Set AMZNAuthorizeRequest.interactiveStrategy to AMZNInteractiveStrategyNever and the SDK will look for a locally stored authorization grant from previous authorize:withhandler responses. If one is available, valid, and contains all requested scopes, the SDK will return an AMZNAuthorizeResult object that contains an access token and user profile data. Otherwise, it will return an NSError object via AMZNAuthorizationRequestHandler. Login with Amazon How-to Guide Page 95

96 Login with Amazon SDK for ios 3.x Migration Guide PDF last generated: August 28, 2017 // Build an authorize request. AMZNAuthorizeRequest *request = [[AMZNAuthorizeRequest alloc] init]; request.scopes = [NSArray arraywithobjects: // [AMZNProfileScope userid], [AMZNProfileScope profile], [AMZNProfileScope postalcode]]; request.interactivestrategy = AMZNInteractiveStrategyNever; [[AMZNAuthorizationManager sharedmanager] authorize:request withhandler:^(amznauthorizeresult *result, BOOL userdidcancel, NSError *error) { if (error) { // Error from the SDK, indicating the user was not previously author ized to your app for the requested scopes. else { // The user was previously authorized to your app. // Obtain the access token and user profile data. NSString *accesstoken = result.token; AMZNUser *user = result.user; NSString *userid = user.userid; ]; Clear Authorization Data and Log Out a User Use the new signout: API provided by the new LWA SDK for ios, which replaces clearauthorizationstate:. [[AMZNAuthorizationManager sharedmanager] signout:^(nserror * _Nullable erro r) { if (!error) { // error from the SDK or Login with Amazon authorization server. ]; Login with Amazon How-to Guide Page 96

97 Login with Amazon for Android and Fire Apps PDF last generated: August 28, 2017 Login with Amazon for Android and Fire Apps LWA for Android and Fire Apps Overview Customer Experience in Android and Fire Apps Step 1: Install the SDK for Android Step 2: Run the Sample app Step 3: Register your Android/Fire app Step 4: Create a LWA Project Step 5: Add a LWA Button to your app Step 6: Use the SDK for Android APIs Step 7: Integrate with your Existing Account System Reference LWA SDK Docs for Android... 0 Upgrade your Android SDK Login with Amazon How-to Guide Page 97

98 Login with Amazon for Android PDF last generated: August 28, 2017 Login with Amazon for Android Using the Login with Amazon SDK for Android benefits you and your customers: Requirements The Login with Amazon SDK for Android will help you add Login with Amazon to your Android, Fire TV, and Fire tablet applications. We recommend you use the Login with Amazon SDK for Android with Android Studio. For steps on how to install Android Studio and on getting the Android SDK set up, see Get the Android SDK on developer.android.com When the Android SDK is installed, find the SDK Manager application in your android installation. To develop for Login with Amazon, you must use the SDK Manager to install the SDK Platform for Android 2.2 or higher (API version 8). See Adding SDK Packages on developer.android.com for more information on using SDK Manager. After installing the SDK, set up an Android Virtual Device (AVD) for running your apps. See Managing Virtual Devices on developer.android.com for instructions on setting up a virtual device. When your development environment is set up, you can Install the Login with Amazon SDK for Android (page 108) or Run the Sample App (page 109). Upgrade your Login with Amazon SDK for Android Use these instructions (page 128) to quickly upgrade an older version of the Login with Amazon SDK for Android to the current version (3.x). Getting Started These topics will show you how to add Login with Amazon to your Android app. After completing these steps you should have a working Login with Amazon button in your app to allow users to log in with their Amazon credentials. 1. Install the Login with Amazon SDK for Android (page 108) 2. Run the Sample App (page 109) 3. Register with Login with Amazon (page 110) 4. Create a Login with Amazon Project (page 114) 5. Add a Login with Amazon Button to Your App (page 118) 6. Use the SDK for Android APIs (page 119) 7. Integrate with your Existing Account System (page 126) Reference API Reference SDK Release Notes Release Notes (page 8) Login with Amazon How-to Guide Page 98

99 Login with Amazon for Android PDF last generated: August 28, 2017 Older Documentation Using the Login with Amazon SDK for Android APIs (v2.0.2 and below) (page 166) Login with Amazon How-to Guide Page 99

100 Customer Experience in Android/Fire apps PDF last generated: August 28, 2017 Customer Experience in Android/Fire apps In this section, you will learn about the login flow your customers will experience when they use Login with Amazon within your Android app. The Login with Amazon SDK for Android handles the entire login flow from signing in, to obtaining customer consent, to sharing profile information (if you requested it), to finally redirecting the customer back to your Android app. Note: This information applies to Android apps using the Login with Amazon SDK for Android version 2.0 and above. If you re using an older version of the SDK, use these instructions (page 128) to upgrade. Step 1: The Login with Amazon Button The login flow always begins when your customer clicks a Login with Amazon button in your Android app. We recommend placing these branded buttons on your app s sign in and registration screens. You can also place Login with Amazon buttons in your app s header or footer to enable a quick way for your customers to login to your app using their Amazon credentials. Login with Amazon How-to Guide Page 100

101 Customer Experience in Android/Fire apps PDF last generated: August 28, 2017 Login with Amazon How-to Guide Page 101

102 Customer Experience in Android/Fire apps PDF last generated: August 28, 2017 For instructions on implementing Login with Amazon buttons, see our Getting Started Guide for Android (page 98). Step 2: The Login Flow The Login with Amazon SDK for Android will automatically provide each of your customers with one of the login flows below: Single Sign-On (SSO) flow (page 102): if the customer is signed into the Amazon Mobile Shopping app on their Android device, or they are using an Amazon-branded device running Fire OS. System browser flow (page 102): if the customer is not signed into the Amazon Mobile Shopping app on their Android device, and are not using an Amazon device running Fire OS. Single Sign-on flow If your customer is already signed into the Amazon Mobile Shopping app on their Android device when they click the Login with Amazon button, they will not be prompted to enter their Amazon account credentials. Instead, the Login with Amazon SDK for Android will recognize the customer s authentication to the Amazon Mobile Shopping app or the Amazon device, and use that same account information to log them into your Android app. The customer will only need to provide one-time consent to share their profile information with your app (if your app is requesting it). In SSO flow, a user visits your Android app (A). They click the Login with Amazon button (B) and get redirected to a secure, branded WebView within the Amazon Mobile Shopping app which requests their consent (page 106) (C) to allow your app access to their profile data. If they have already consented, or if your app is not requesting a scope which requires consent, this step will be skipped. Amazon then redirects the user from the consent screen back to your app (D). System browser flow If your customer is not signed into the Amazon Mobile Shopping app on their Android device, Login with Amazon will redirect them to their system browser and provide them with a secure, branded screen where they can enter their Amazon account credentials to login to your app. After successfully signing in, the customer will need to provide one-time consent (page 106) to share their profile information with your app (if your app is requesting it). Login with Amazon How-to Guide Page 102

103 Customer Experience in Android/Fire apps PDF last generated: August 28, 2017 In system browser flow, a user visits your Android app (A). They click the Login with Amazon button (B) and get redirected out of the app and into a secure, Amazon-branded login screen (page 104) in their system browser (C). After entering their Amazon account credentials, another secure, Amazon-branded page opens in their system browser and requests consent (page 106) to allow your app access to their profile data (D). If they have already consented, or if your app is not requesting a scope which requires consent, this step will be skipped. Amazon then redirects the user from their browser window back to your app (E). Note: If the customer chooses the Keep me signed in option on the login screen, they will skip steps B, C, and D the next time they visit your app and use Login with Amazon. Instead, the will see an acknowledgement screen (below), where they can click Continue to login to your app with their Amazon account credentials. Login with Amazon How-to Guide Page 103

104 Customer Experience in Android/Fire apps PDF last generated: August 28, 2017 Step 3: The Login Screen In system browser flow, the Amazon customer will see the login screen immediately after clicking a Login with Amazon button. Note: The login screen is not shown during single sign-on flow. Login with Amazon How-to Guide Page 104

105 Customer Experience in Android/Fire apps PDF last generated: August 28, 2017 The Amazon-branded login screen consists of the following: The app name you select when you register with Login with Amazon (page 110). A Forgot your password? link the customer can click to reset their Amazon.com password. Fields for the customer to enter in their Amazon.com account credentials. A Show password checkbox the customer can select to display the password they re typing in. By default, the password will be shown. A Keep me signed in checkbox the customer can select to skip the login and consent screens the next time they visit your app and use Login with Amazon. Instead, the next time they log in to your app they will see an acknowledgement screen (shown above), where they can click Continue to login to your app with their Amazon account credentials. A secure Sign in button the customer can click when they re ready to authenticate to Amazon using their account credentials. Clicking Sign in will redirect the customer to the consent screen, or to your app, as described in the Login Flows (page 102) sections above. A Create a new Amazon account button the customer can click to create a new account, then Login with Amazon How-to Guide Page 105

106 Customer Experience in Android/Fire apps PDF last generated: August 28, 2017 sign into your app. A list of benefits for using Login with Amazon, and a Learn More link the customer can click for more details. Links to the Conditions of Use and Privacy Notice relevant to their usage of Login with Amazon. Step 4: The Consent Screen If your app requests access to a customer s profile (page 141) information (such as their name, address, or postal code), the customer will be made aware of this via the consent screen. The Amazon-branded consent screen consists of the following: A drop-down list showing the customer s name in the upper, right corner. Clicking the drop-down Login with Amazon How-to Guide Page 106

107 Customer Experience in Android/Fire apps PDF last generated: August 28, 2017 arrow will allow the customer to choose another Amazon account to authenticate with. Note: This link is not shown in SSO flow. SSO flow will always automatically use the Amazon account already authenticated to the device or to the Amazon Mobile Shopping app. The app name and logo you provide when you register with Login with Amazon (page 110). A list of each permission requested by your app. An I agree button the customer can click if they agree to share their information. Clicking I agree will redirect the customer back to your app as described in the Login Flows (page 102) sections above. Note: A customer only needs to provide their consent once per app, per device. After they have consented to sharing their information with your Android app once, they will not be asked again, unless they intentionally remove their permissions from the Your Account link. A Cancel button the customer can click if they do not agree to share their information. Clicking Cancel will bring the customer back to your app unauthenticated. A Your Account link the customer can click to remove permissions they ve granted to apps via Login with Amazon. A link to the privacy policy for your app that you provide when you register with Login with Amazon (page 110). Step 5: Success! After a customer has completed the login flow, they are automatically redirected back to your Android app. Login with Amazon How-to Guide Page 107

108 Install the Login with Amazon SDK for Android PDF last generated: August 28, 2017 Install the Login with Amazon SDK for Android The Login with Amazon SDK for Android includes the library, supporting documentation, and a sample application that allows a user to login and view their profile data. If you have not installed the Android SDK or the Android Development Tools, see Requirements on Login with Amazon for Android (page 98). 1. Download the Amazon Mobile App SDK and extract the files to a directory on your hard drive. 2. You should see a login-with-amazon.jar file in the LoginWithAmazon parent directory. 3. Open docs/index.html to view the Login with Amazon Android API Reference. 4. See Install the Login with Amazon Library (page 114) for instructions on how to add the library and documentation to an Android project. Login with Amazon How-to Guide Page 108

109 Run the Sample App PDF last generated: August 28, 2017 Run the Sample App To run the sample application, import the sample into an AndroidStudio workspace. 1. Download SampleLoginWithAmazonAppForAndroid-src.zip and extract the files to a directory on your hard drive. 2. Start Android Studio and select Open an existing Android Studio project. 3. Browse to the SampleLoginWithAmazonApp directory obtained after extracting the downloaded zip file in Step From the Build menu, click Make Project, and wait for the project to finish building. 5. From the Run menu, click Run and then click the SampleLoginWithAmazonApp. 6. Select the emulator or connected Android device and click Run. Login with Amazon How-to Guide Page 109

110 Register for Login with Amazon PDF last generated: August 28, 2017 Register for Login with Amazon Before you can use Login with Amazon in your Android app, you must register the application with Login with Amazon. Your Login with Amazon application registration 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 websites and mobile app. Users will see the name of your application, your logo, and a link to your privacy policy. Register your Security Profile If this is your first time using the Developer Console, you will need to create a security profile for your website or mobile app. 1. Visit You will be asked to login to the Developer Console, which handles application registration for Login with Amazon. If this is your first time using the Developer Console, you will be asked to set up an account. 2. Click Create a New Security Profile. This will take you to the Security Profile Management page. 1. Enter a Name and a Description for your security profile. A security profile associates user data and security credentials with one or more related apps. 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. 2. You must enter a Consent Privacy Notice URL for your application now. The Privacy Notice URL is the location of your company or application s privacy policy (for example, ). This link is displayed to users on the consent screen. 3. If you want to add a Consent Logo Image for your application, click Upload Image. This logo is displayed on the sign-in and consent screen to represent your business or website. 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. 3. Click Save. Your security profile should look similar to this: After your basic security profile is saved, you can associate specific websites and mobile apps with this security profile. Login with Amazon How-to Guide Page 110

111 Register for Login with Amazon PDF last generated: August 28, 2017 Add a Registered AppStore or Developer Console app to your Security Profile If you have already registered your apps at you can add them to your security profile to enable them for Login with Amazon. Otherwise, you can skip this step and proceed to Add Android Settings to your Security Profile (page 111). 1. Visit 2. Select your app from the list. This will take you to the General Information tab for your app. 3. Click Login with Amazon from the list of tabs at the top. 4. Associate the app with your security profile by selecting it from the drop-down menu. Click Confirm. Add Android Settings to your Security Profile After creating a security profile on the Developer Console, you can add settings for specific websites and mobile apps that will use Login with Amazon with that profile. To enable Login with Amazon for Android, you have to specify the package name and signature for the app project. Login with Amazon will use these values to generate an API key. The API key will grant your app access to the Login with Amazon authorization service. Follow these steps to add Android settings to your profile: 1. Visit 2. Go to the security profile that you want to use for your app. 1. Locate the security profile you want to modify from the table. 2. Hover over the button shown in the Manage column. 3. Select the Kindle/Android Settings menu item. Note: If your desired security profile is not shown in the table, it is not yet enabled for Login with Amazon. In this case, use the drop-down menu above the table to Select a Security Profile, then click Confirm. You ll be required to enter a Consent Privacy Notice URL and optionally select a Consent Logo Image, both of which will be displayed on the sign-in and consent screens. If you don t have an existing security profile for your app, see Register Your Security Profile (page 110). 3. Enter the API Key Name that your app will use to authenticate with Login with Amazon.This does not have to be the official name of your app. It simply identifies this particular Android app among the apps and websites registered to your security profile. 4. Enter your Package Name.This must match the package name of your Android project. To determine the package name of your Android Project, open the project in Android Studio. Double-click AndroidManifest.XML in the Project View to open the file, and select the Manifest tab. The Package name is at the top. 5. Enter the app Signatures.This includes both the MD5 and SHA-256 hash values used to verify your application. The MD5 signature must be in the form of 16 hexadecimal pairs separated by colons (for example: 01:23:45:67:89:ab:cd:ef:01:23:45:67:89:ab:cd:ef ) and the SHA-256 signature must be in the form of 32 hexadecimal pairs separated by colons (for Login with Amazon How-to Guide Page 111

112 Register for Login with Amazon PDF last generated: August 28, 2017 example: 01:23:45:67:89:ab:cd:ef:01:23:45:67:89:ab:cd:ef:01:23:45:67:89:ab:cd:ef:01:23:45:67:89:ab:cd:ef ). See Android App Signatures and API Keys (page 112) for steps you can use to extract the signature from your project. 6. Click Generate New Key. Tip: If different versions of your app have different signatures or package names, such as for one or more testing versions and a production version, each version requires its own API Key. From the Android/Kindle Settings of your app, click the Add an API Key button to create additional keys for your app (one per version). Android App Signatures and API Keys The app signature is a hash value that is applied to every Android app when it is built. Amazon uses both the MD5 and SHA-256 app signatures to construct your API Key. The API Key enables Amazon services to recognize your app. If you use the Amazon Appstore to sign your app, the API key is provided automatically. If you are not using the Amazon Appstore, you will need to manage your API key manually. App signatures are stored in a keystore. Generally for Android apps there is a debug keystore and a release keystore. To find the location of the debug keystore in Android Studio, open the Build menu, select Edit Build Types, then go to the Signing tab, and locate the debug keystore in the Store File field. A release keystore is normally created when you export your Android app to create a signed APK file. Through the export process, if you are creating a new release keystore you will select its location. By default it will be placed in the same location as your default debug keystore. If you have registered your app using the debug signature during development, you will have to add a new Android setting to your application when you are ready to release the app. The new app setting must use the signature from the release keystore. See Signing Your Applications on developer.android.com for more information. Determining an Android App Signature 1. If you have a signed APK file: 1. Unzip the APK file and extract CERT.RSA. (You can rename the APK extension to ZIP if necessary). 2. From the command line, run: keytool -printcert -file CERT.RSA Keytool is located in the bin directory of your Java installation. 2. If you have a keystore file: 1. From the command line, run: keytool -list -v -alias <alias> -keystore <keystore.filename> Keytool is located in the bin directory of your Java installation. The alias is the name of the key used to sign the app. 2. Enter the password for the key and press Enter. Login with Amazon How-to Guide Page 112

113 Register for Login with Amazon PDF last generated: August 28, Under Certificate Fingerprints, copy both the MD5 and SHA-256 values. Retrieving an Android API Key After you have registered an Android setting and provided an app signature, you can retrieve the API key from the registration page for your Login with Amazon application. You will need to place that API key into a file in your Android project. Until you do, the app will not be authorized to communicate with the Login with Amazon authorization service. 1. Visit 2. Go to the security profile that you want to use for your app: 1. Locate the security profile you want to modify from the table. 2. Hover over the button shown in the Manage column. 3. Select the Kindle/Android Settings menu item. 3. Find the API Key Name for the key on the list, then click Show in the associated Key column. Copy the API Key that appears in the popup window. Note: The API Key is based, in part, on the time it is generated. Thus, subsequent API Keys you generate may differ from the original. You can use any of these API Keys in your app as they are all valid. You can also delete or edit any of your keys by hovering over the icon and selecting Edit or Delete. Any mistakenly deleted keys can be restored by clicking Show Deleted API Keys, then clicking Restore next to the name of the key you d like to recover. 4. See Add Your API Key to Your Project (page 115) for instructions on adding the API key to your Android app. Delete your Security Profile If needed, you can delete any security profile not associated with an app distributed through the Amazon Appstore. Navigate to the Security Profile Management page, select a profile, and then click Delete Security Profile. A confirmation form appears. Type the word delete into the text field then click Delete to confirm the action. If a security profile is mistakenly deleted, it s fully recoverable from the Security Profile Management page. Click the Show Deleted Security Profiles button, click on the name of the profile you d like to restore, then click Restore Security Profile. A confirmation form appears. Click the Restore button to recover the security profile, including its Web, Android/Kindle, and ios settings. Login with Amazon How-to Guide Page 113

114 Create a Login with Amazon Project PDF last generated: August 28, 2017 Create a Login with Amazon Project In this section, you will learn how to create a new Android project for Login with Amazon, configure the project, and add code to the project to sign in a user with Login with Amazon. If you do not yet have an app project for using Login with Amazon, you should create one now using the instructions below for Android Studio. If you have an existing app, skip to Install the Login with Amazon Library (page 114). Create a New Project in Android Studio Note: As Google no longer supports the Android plugin for the Eclipse IDE, we recommend using Android Studio. 1. Launch Android Studio. 2. From the File menu, select New and Project. 3. Enter an Application Name and Company Name for your app. 4. Enter the Application and Company Name corresponding to the package name that you chose when you registered your app with Login with Amazon. If you haven t registered your app yet, choose a Package Name and then follow the instructions at Register with Login with Amazon (page 110) after you create your project. If the package name of your app does not match the registered package name, your Login with Amazon calls will not succeed. 5. Select a Minimum Required SDK of API 11: Android 3.0 (Honeycomb) or higher and click Next. You can alternatively use a Minimum Required SDK of API 8: Android 2.2 (Froyo) or higher when using the v4 Android Support Library. 6. Select the type of activity you want to create and click Next. 7. Fill the relevant details and click Finish. You will now have a new project in your workspace that you can use to call Login with Amazon. Install the Login with Amazon Library If you have not yet downloaded the Login with Amazon SDK for Android, see Install the Login with Amazon SDK for Android (page 108). 1. Using the file system on your computer, find the login-with-amazon-sdk.jar file within the Login with Amazon SDK for Android. Copy it to the clipboard. 2. With your project open in Android Studio, open the Project View. 3. Right-click on the parent directory for your project/app in the Project View and select Paste. 4. Right-click login-with-amazon-sdk.jar in the Project View and select Add As Library. Set Network Permissions for Your Project In order for your app to use Login with Amazon, it must access the Internet and access network state information. Your app must assert these permissions in your Android manifest, if it doesn t already. 1. From the Project View, double-click AndroidManifest.xml to open it. 2. Copy the lines of code below and paste them into the file, outside of the application block: Login with Amazon How-to Guide Page 114

115 Create a Login with Amazon Project PDF last generated: August 28, 2017 <uses-permission android:name="android.permission.internet"/> <uses-permission android:name="android.permission.access_network_stat E"/> Example: Add Your API Key to Your Project When you register your Android application with Login with Amazon, you are assigned an API key. This is an identifier that the Amazon Authorization Manager will use to identify your application to the Login with Amazon authorization service. If you are using the Amazon Appstore to sign your app, the Appstore will provide the API key automatically. If you are not using the Amazon Appstore, the Amazon Authorization Manager loads this value at runtime from the api_key.txt file in the assets directory. 1. If you do not have your API Key yet, see Android App Signatures and API Keys (page 112) and follow the instructions under Retrieving an Android API Key. 2. From the Project View in Android Studio, right-click the assets folder, then click New > File. If you don t have an assets folder, right-click the parent directory for your project then select New > Folder > Assets Folder. 3. Name the file api_key.txt. 4. You should now have an editor window for a text file named api_key.txt. Add your API Key to the Login with Amazon How-to Guide Page 115

116 Create a Login with Amazon Project PDF last generated: August 28, 2017 text file. 5. In the File menu, click Save. Tip: If a text editor adds extra characters to your api_key.txt file (such as a Byte Order Mark), you may see ERROR_ACCESS_DENIED when you try to connect to the Login with Amazon authorization service. If this occurs, try removing any leading or trailing spaces, line feeds, or suspicious characters. (For example, an editor using Byte Order Mark might add 0xEF 0xBB 0xBF or other hexadecimal sequences to the start of your api_key.txt file). You can also try retrieving a new API key. Handle Configuration Changes for Your Activity If the user changes the screen orientation or changes the keyboard state of the device while they are logging in, it will prompt a restart of the current activity. This restart will dismiss the login screen unexpectedly. To prevent this, you should set the activity that uses the authorize method to handle those configuration changes manually. This will prevent a restart of the activity. 1. In Project View, double-click AndroidManifest.xml to open the file. 2. In the Application block, find the activity that will handle Login with Amazon (for example, MainActivity). 3. Add the following attribute to the activity you located in Step 2: android:configchanges="keyboard keyboardhidden orientation" or for API 13 or greater: android:configchanges="keyboard keyboardhidden orientation screensiz e" 4. From the File menu, click Save. Now, when a keyboard or device orientation change happens, Android will call the onconfigurationchanged method for your activity. You do not need to implement this function unless there is an aspect of these configuration changes you want to handle for your app. Add a WorkflowActivity to Your Project When the user clicks the Login with Amazon button, the API will launch a web browser to present a login and consent page to the user. In order for this browser activity to work, you must add the WorkflowActivity to your manifest. If you have previously integrated with the Login with Amazon SDK or you have the com.amazon.identity.auth.device.authorization.authorizationactivity activity declared in your AndroidManifest.xml, it must be removed and replaced with the WorkflowActivity. 1. In Project View, double-click AndroidManifest.xml to open the file. 2. In the Application block, add the following code: Login with Amazon How-to Guide Page 116

117 Create a Login with Amazon Project PDF last generated: August 28, 2017 <activity android:name="com.amazon.identity.auth.device.workflow.work flowactivity" android:theme="@android:style/theme.nodisplay" android:allowtaskreparenting="true" android:launchmode="singletask"> <intent-filter> <action android:name="android.intent.action.view"/> <category android:name="android.intent.category.defaul T"/> <category android:name="android.intent.category.browsabl E"/> <!-- android:host must use the full package name found i n Manifest General Attributes --> <data android:host="${applicationid" android:scheme="amz n"/> </intent-filter> </activity> Important: If you are not using the Gradle build system, replace ${applicationid with your package name for this app. Login with Amazon How-to Guide Page 117

118 Add a Login with Amazon Button to your app PDF last generated: August 28, 2017 Add a Login with Amazon Button to your app Login with Amazon provides several standard buttons you can use to prompt users to login from your app. This section gives steps for downloading an official Login with Amazon image and pairing it with an Android ImageButton. 1. Add a standard ImageButton to your app. For more information on Android buttons and the ImageButton class, see Buttons on developer.android.com. 2. Give your button an id. In the button XML declaration, set the android:id attribute login_with_amazon. For example: android:id="@+id/login_with_amazon" 3. Choose a button image. Consult our Login with Amazon Button Guidelines (page 154) for a list of buttons you can use in your app. Download a copy of the LWA_Android.zip file. Extract a copy of your preferred button for each screen density your app supports (xxhdpi, xhdpi, hdpi, mdpi, or tvdpi). For more information on supporting multiple screen densities in Android, see Alternative Layouts in the Supporting Multiple Screens topic on developer.android.com. 4. Copy the appropriate button image files to your project. For each screen density you support (xhdpi, hdpi, mdpi, or ldpi), copy the downloaded button to the res/drawable directory for that screen density. 5. Declare the button image. In the button XML declaration, set the android:src attribute to the name of the button you have chosen. For example: android:src="@drawable/btnlwa_gold_loginwithamazon.png" 6. Load your app, and verify that the button now has a Login with Amazon image. You should verify the button displays properly for each screen density you support. Login with Amazon How-to Guide Page 118

119 Use the Login with Amazon SDK for Android APIs PDF last generated: August 28, 2017 Use the Login with Amazon SDK for Android APIs Handle the Login Button and Get Profile Data This section explains how to call the authorize API to login a user. This includes creating an onclick listener for your Login with Amazon button in the oncreate method of your app. 1. Add Login with Amazon to your Android project (page 114). 2. Initialize RequestContext. You will need to declare a RequestContext variable and create a new instance of the class. The best place to initialize RequestContext is in the oncreate method of your Android activity or fragment. For example: private RequestContext protected void oncreate(bundle savedinstancestate) { super.oncreate(s avedinstancestate); requestcontext = RequestContext.create(this); 3. Create an AuthorizeListener. AuthorizeListener will process the result of the authorize call. It contains three methods: onsuccess, onerror, and oncancel. Create the AuthorizeListener interface in-line with a registerlistener call in the oncreate method of your Android activity or fragment. Login with Amazon How-to Guide Page 119

120 Use the Login with Amazon SDK for Android APIs PDF last generated: August 28, protected void oncreate(bundle savedinstancestate) { super.oncreate(savedinstancestate); requestcontext = RequestContext.create(this); requestcontext.registerlistener(new AuthorizeListener() { /* Authorization was completed successfully. public void onsuccess(authorizeresult result) { /* Your app is now authorized for the requested scopes */ /* There was an error during the attempt to authorize the application. public void onerror(autherror ae) { /* Inform the user of the error */ /* Authorization was cancelled before it could be completed. public void oncancel(authcancellation cancellation) { /* Reset the UI to a ready-to-login state */ ); Tip: If you re using a fragment and capturing references to View objects in your AuthorizeListener implementation, create AuthorizeListener in the oncreateview method instead of oncreate. This ensures the View object references are set when the call to authorize finishes. 4. Implement onsuccess, onerror, and oncancel for your AuthorizeListener. Because the authorization process presents a login screen (and possibly a consent screen ) to the user in a web browser (or a WebView), the user will have an opportunity to cancel the login or navigate away. If they explicitly cancel the login process, oncancel is called, and you will want to reset your user interface. If the user navigates away from the login screen in the browser or WebView, then switches back to your app, the SDK will not detect that the login was not completed. If you detect user activity in your app before login is completed, you can assume they have navigated away from the browser and react accordingly. 5. Call RequestContext.onResume. Login with Amazon How-to Guide Page 120

121 Use the Login with Amazon SDK for Android APIs PDF last generated: August 28, 2017 In order to accommodate the Android application lifecycle, implement the onresume method in your activity or fragment. This will trigger all listeners registered with registerlistener in the event that your app is closed by the operating system before the user completes an authorization protected void onresume() { super.onresume(); requestcontext.onresume(); 6. Call AuthorizationManager.authorize. In the onclick handler for your Login with Amazon button, call authorize to prompt the user to login and authorize your application. This method will enable the user to sign in and consent to the requested information in one of the following ways: 1. Switches to the system browser 2. Switches to WebView in a secure context (if the Amazon Shopping app is installed to the device) The secure context for the second option is available when the Amazon Shopping app is installed to the device. Amazon-created devices running Fire OS (for example Kindle Fire, Fire Phone, and Fire TV) always use this option even if there is no Amazon Shopping app on the device. Because of this, if the user is already signed in to the Amazon Shopping app, this API will skip the sign in page, leading to a Single Sign-On experience for the user. See Customer Experience for Android/Fire apps (page 100) apps to learn more. When your application is authorized, it is authorized for one or more data sets known as scopes. A scope encompasses the user data you are requesting from Login with Amazon. The first time a user logs in to your app, they will be presented with a list of the data you are requesting and asked for approval. Login with Amazon currently supports the following scopes: profile (gives access to the user s name, address, and Amazon account ID), profile:user_id (gives access to the user s Amazon account ID only), and postal_code (gives access to the user s zip/postal code on file for their Amazon account). AuthorizationManager.authorize is an asynchronous call, so you do not have to block the UI thread or create a worker thread of your own. To call authorize, pass an AuthorizeRequest object that can be built using AuthorizeRequest.Builder : Login with Amazon How-to Guide Page 121

122 Use the Login with Amazon SDK for Android APIs PDF last generated: August 28, protected void oncreate(bundle savedinstancestate) { super.oncreate(s avedinstancestate); /* Previous oncreate declarations omitted */ // Find the button with the login_with_amazon ID // and set up a click handler View loginbutton = findviewbyid(r.id.login_with_amazon); loginbutto n.setonclicklistener(new View.OnClickListener() public void onclick(view v) { AuthorizationManager.authorize(new AuthorizeRequest.Builder(requestContext).addScopes(ProfileScope.profile(), ProfileScope.postalCode()).build()); ); Fetch User Profile Data This section explains how to use the User API to retriever a user s profile data after they ve been authorized. The profile data you can retrieve is based on the scope indicated in the authorize:withhandler: call. 1. Call User.fetch. User.fetch returns the user s profile data to you through the Listener<User, AuthError> callback. Listener<User, AuthError> contains two methods: onsuccess and onerror (it does not support oncancel because there is no way to cancel a User.fetch call). onsuccess receives a User object with profile data, while onerror receives an AuthError object with information on the error. updateprofiledata is an example of a function your app could implement to display profile data in the user interface. Login with Amazon How-to Guide Page 122

123 Use the Login with Amazon SDK for Android APIs PDF last generated: August 28, 2017 private void fetchuserprofile() { User.fetch(this, new Listener<User,AuthError>() { /* fetch completed successfully. public void onsuccess(user user) { final String name = user.getusername(); final String = user.getuser (); final String account = user.getuserid(); final String zipcode = user.getuserpostalcode(); runonuithread(new Runnable() public void run() { updateprofiledata(name, , account, zipcode); ); /* There was an error during the attempt to get the profile. public void onerror(autherror ae) { /* Retry or inform the user of the error */ ); Note: User.getUserPostalCode is only returned if you request the ProfileScope.postalCode() scope. Check for User Login at Startup If a user logs into your app, closes the app, and restarts the app later, the app is still authorized to retrieve data. The user is not logged out automatically. At startup, you can show the user as logged in if your app is still authorized. This section explains how to use gettoken to see if the app is still authorized. 1. Call gettoken. In the onstart method of your activity or fragment, call gettoken to see if the application is still authorized. gettoken retrieves the raw access token that the AuthorizationManager uses to access a user profile. If the token value is not null, then the app is still authorized and you can proceed to fetch user profile data. gettoken requires the same scopes you requested in your call to authorize. gettoken supports asynchronous calls in the same manner as User.fetch, so you do not have to block the UI thread or create a worker thread of your own. To call gettoken asynchronously, pass an object that supports the Listener<AuthorizeRequest, AuthError> interface as the last parameter. 2. Declare a Listener<AuthorizeResult, AuthError>. Login with Amazon How-to Guide Page 123

124 Use the Login with Amazon SDK for Android APIs PDF last generated: August 28, 2017 Your implementation of the Listener<AuthorizeResult, AuthError> interface processes the result of the gettoken call. Listener contains two methods: onsuccess and onerror (it does not support oncancel because there is no way to cancel a gettoken call). 3. Implement onsuccess and onerror for your Listener<AuthorizeResult, AuthError>. onsuccess receives an AuthorizeResult object with an access token, while onerror receives an AuthError object with information on the protected void onstart(){ super.onstart(); Scope[] scopes = { ProfileScope.profile(), ProfileScope.postalCode() ; AuthorizationManager.getToken(this, scopes, new Listener<AuthorizeRes ult, AuthError>() public void onsuccess(authorizeresult result) { if (result.getaccesstoken()!= null) { /* The user is signed in */ else { /* The user is not signed in public void onerror(autherror ae) { /* The user is not signed in */ ); Clear Authorization Data and Log Out Users This section explains how to use the signout method to clear the user s authorization data from the AuthorizationManager local data store. The user will have to login again in order for the app to retrieve profile data. Use this method to log out a user, or to troubleshoot login problems in the app. 1. Implement a logout mechanism. When a user has successfully logged in, you should provide a logout mechanism so they can clear their profile data and previously authorized scopes. Your mechanism might be a hyperlink, button, or a menu item. For this example, we will create an onclick method for a button. 2. Call signout. Call signout in your logout handler to remove a user s authorization data (access tokens, profile) from the local store. signout takes an Android context and a Listener<Void, AuthError> to handle success or failure. 3. Declare an anonymous Listener<Void, AuthError>. Login with Amazon How-to Guide Page 124

125 Use the Login with Amazon SDK for Android APIs PDF last generated: August 28, 2017 Your implementation of Listener<Void, AuthError> processes the result of the signout call. Anonymous classes are useful for capturing variables from the enclosing scope. See Handle the Login Button and Authorize the User for an example that declares listener classes. 4. Implement onsuccess and onerror for your Listener<Void, AuthError>. When signout succeeds you should update your UI to remove references to the user, and provide a login mechanism users can use to login again. If signout returns an error, you can let the user try to log out protected void oncreate(bundle savedinstancestate) { super.oncreate(savedinstancestate); /* Previous oncreate declarations omitted */ // Find the button with the logout ID and set up a click handler Vie w logoutbutton = findviewbyid(r.id.logout); logoutbutton.setonclickli stener(new View.OnClickListener() public void onclick(view v) { AuthorizationManager.signOut(getApplicationContext(), new Listener<Vo id, AuthError>() public void onsuccess(void response) { // Set logged out state in public void onerror(autherror autherror) { // Log the error ); ); Login with Amazon How-to Guide Page 125

126 Integrate with Your Existing Account System PDF last generated: August 28, 2017 Integrate with Your Existing Account System In this section, we ll discuss how to integrate customer profile data from Login with Amazon user accounts with a mobile app that already has an account management system. You will learn how to enable your site or app to let users log in using their Amazon accounts, and how to let existing users attach their Amazon identity so they can log in with their Amazon credentials. Prerequisites This guide assumes you have previously signed up for Login with Amazon, registered your mobile app as a Login with Amazon application, and have the appropriate SDK or server-side methods to communicate with the Login with Amazon service. This guide also assumes your mobile app currently has these features: 1. An account database where you record information about each user account. Users have some kind of unique identifier. Users currently sign in using their username/password. 2. A sign-in page for registered users. 3. A registration page for registering new users by taking in profile information (name, , and so on). 4. Some mechanism for managing authentication state after the user successfully signs in so that the next page knows that the user is currently signed in (for example, storing that info in cookies or a back-end database). Make 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 user_id property, in the form amzn1.accountvalue. For example: amzn1.account.k2li23kl2lk2 Set up Login with Amazon Using the relevant SDK or server-side methods for your mobile app, provide a method for the user to log in with their Amazon credentials. This includes making changes to the UI of your sign-in and registration pages. Your sign-in page will need to have an option for users to select the Login with Amazon button to authenticate using their Amazon credentials. For more information, see Android (page 98). Obtain and Secure Amazon Customer Profile Data Once the user has interacted with the Login with Amazon service to sign in (and, on the first visit, authorize data sharing), you will receive an authorization response from Login with Amazon. When you receive an authorization response you should: 1. Send the access token in your authorization response to your server using HTTPS. 2. From server-side, call the profile endpoint using the access token. See our developer guide (page 43) for details on calling the profile endpoint, including code samples in multiple Login with Amazon How-to Guide Page 126

127 Integrate with Your Existing Account System PDF last generated: August 28, 2017 languages. Login with Amazon will return a customer profile response with values (such as user_id, , name, and/or postal_code ) you can keep on your server. Taking this step will ensure the profile data you save to your server belongs to the customer who is signed into your client. 3. Search for the user s Amazon account identifier within your user database to see if they have signed in before. If they have not then you will need to create a new account for them. 4. Search for the user s address in your account system. If they have a local account with that address, prompt them to enter their local credentials to allow Login with Amazon to log in that account. 5. Create cookies in the user s browser or otherwise record them as authenticated with your site or app. Find or Create a Local Account The user profile response will always contain a parameter named user_id. The value of this parameter is a string which permanently and uniquely identifies the Amazon account to which the user has signed in. Amazon will always return the same identifier for each user. You should search your user database to see if this Amazon account has previously signed in to your site or app. If you have not seen the Amazon account before, and it doesn t match an existing account, you will need to create a new entry in your local account database and associate it with the Amazon account identifier for the next time they sign in. If the Amazon account does match an existing local account, prompt the user for their local password to link the two accounts. The authentication response may contain additional user data. For example, the user s name and address. You can copy this information into your local account database when creating new accounts or to update existing accounts (for example, the user could have changed their address on Amazon since the last time they signed in). If you need to collect additional information from the user before creating an account then this is where you will want to display a registration page. You can prefill it with the information you received in the authentication response or you can show just the additional fields that you require. Tip: If your local account management includes resetting passwords, you might want to ensure that Login with Amazon users do not get confused about how that affects 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. Mark the User as Authenticated After you have have received a valid authentication response and found or created a corresponding account in your own account database, mark the user has having authenticated. This step can work exactly the same as in your current authentication system. Login with Amazon How-to Guide Page 127

128 Login with Amazon SDK for Android 3.x Migration Guide PDF last generated: August 28, 2017 Login with Amazon SDK for Android 3.x Migration Guide This guide explains how to migrate your app from using the Login with Amazon SDK for Android v2.0.2 (or lower) to the Login with Amazon Android for Android v3.x. If you ve not yet integrated Login with Amazon into your app, review the full set of instructions in our Getting Started Guide for Android (page 98). What version of the Login with Amazon SDK for Android is my app using? To determine the version of the Login with Amazon SDK for Android your app is using: 1. Open a Mac/Unix terminal. 2. Navigate to the folder containing the Login with Amazon SDK for Android (login-with-amazonsdk.jar) in your Android app. Typically, this is the root directory of your project. 3. Run the following command to print the version number of the SDK: `javap -classpath./login-with-amazon-sdk.jar -constants com.amazon.i dentity.auth.map.device.utils.mapversioninfo grep -o "LWA_VERSION =.*"` How to Upgrade 1. Download the latest version of the Login with Amazon SDK for Android. 2. Extract the files to a directory on your hard drive and navigate to the LoginWithAmazon folder. 3. Use the login-with-amazon-sdk.jar in this folder to replace the older SDK.jar file in your Android app. You can do this by copying the new.jar file to your clipboard, then pasting it into the folder of your Android project where the old.jar file is stored (typically the root directory of your project). 4. Migrate to the new APIs introduced in the Login with Amazon 3.0 library as instructed below. Handle the Login Button and Get User Profile Data Initialize RequestContext and registerlistener. The new LWA SDK for Android no longer requires you to initialize an AuthorizationManager instance. Instead, you will need to declare a RequestContext variable and create a new instance of the class. The best place to initialize RequestContext is in the oncreate method of your Android activity or fragment. After the RequestContext instance is created, create the AuthorizeListener interface in-line with a registerlistener call. Get customer profile data in the onsuccess() method of the AuthorizeListener(). The onsuccess() method of the new AuthorizeListener class has changed its input argument type to AuthorizeResult. An AuthorizeResult object contains the response from the LWA authorization server when the AuthorizationManager.authorize call succeeds: 1. user : If you requested a profile scope, the AuthorizeResult object contains a User Login with Amazon How-to Guide Page 128

129 Login with Amazon SDK for Android 3.x Migration Guide PDF last generated: August 28, 2017 object that includes the requested profile data from a customer. You no longer need to call AuthorizationManager.getProfile from within the onsuccess method of AuthorizeListener (required in previous versions of the LWA SDK for Android). For more information on obtaining profile data, see the class reference for the User class in the SDK documentation. 2. accesstoken : If you requested an access token (occurs by default), the LWA authorization server returns an access token in the response. You no longer need to call AuthorizationManager.getToken within the onsuccess method of AuthorizeListener (required in previous versions of the LWA SDK for Android). Login with Amazon How-to Guide Page 129

130 Login with Amazon SDK for Android 3.x Migration Guide PDF last generated: August 28, protected void oncreate(bundle savedinstancestate) { super.oncreate(savedinstancestate); requestcontext = RequestContext.create(this); requestcontext.registerlistener(new AuthorizeListener() { /* Authorization was completed successfully. public void onsuccess(authorizeresult result) { /* Your app is now authorized for the requested scopes */ /* There was an error during the attempt to authorize the application. public void onerror(autherror ae) { /* Inform the user of the error */ /* Authorization was cancelled before it could be completed. public void oncancel(authcancellation cancellation) { /* Reset the UI to a ready-to-login state */ protected void oncreate(bundle savedinstancestate) { super.oncreate(s avedinstancestate); /* Previous oncreate declarations omitted */ // Find the button with the login_with_amazon ID // and set up a click handler View loginbutton = findviewbyid(r.id.login_with_amazon); loginbutton.setonclicklistener(new View.OnClickListener() public void onclick(view v) { AuthorizationManager.authorize(new AuthorizeRequest.Builder(requestContext).addScopes(ProfileScope.profile(), ProfileScope.postalCode()).build()); ); Login with Amazon How-to Guide Page 130

131 Login with Amazon SDK for Android 3.x Migration Guide PDF last generated: August 28, 2017 Call RequestContext.onResume In order to accommodate the Android application lifecycle, implement the onresume method in your activity or fragment. This will trigger all listeners registered with registerlistener in the event that your app is closed by the operating system before the user completes an authorization protected void onresume() { super.onresume(); requestcontext.onresume(); Call AuthorizationManager.authorize method with an AuthorizeRequest object. The new LWA SDK for Android introduces changes to the AuthorizationManager.authorize method. The input to AuthorizationManager.authorize is now an AuthorizeRequest object. We recommend you create the request object using the Builder class defined in the AuthorizeRequest class. Some properties commonly passed to the AuthorizeRequest object are: 1. scopes : Defines what scopes to request authorization for. The Profile class defines scopes provided by Login with Amazon. If you are using APIs for other Amazon products, you will find scopes supported by those products included in their own documentation. 2. requestcontext : The requestcontext object you created earlier. For a full list of properties in the AuthorizeRequest object, see the class references included in the SDK documentation. Add scopes to AuthorizeRequest. In the new LWA SDK for Android, we use the Scope object to represent a scope. To request scopes, you will need to add Scope objects to your AuthorizeRequest. There are two options: 1. To request customer profile scopes provided by Login with Amazon, use the methods defined in the ProfileScope class: Scope name Method in ProfileScope class profile ProfileScope.profile() postal_code ProfileScope.postalCode() profile:user_id ProfileScope.userId() 2. Alternatively, you can create a Scope object using ScopeFactory : ScopeFactory.scopeNamed("profile"); Use this alternate method to request scopes provided by other Amazon products. Login with Amazon How-to Guide Page 131

132 Login with Amazon SDK for Android 3.x Migration Guide PDF last generated: August 28, 2017 Fetch User Profile Data As long as a user is logged in and authorized to your app, you can fetch their user profile data at any time. The new LWA SDK for Android introduces the User class to help you better manage customer profile data. Some of the commonly used customer profile data is defined as properties in this class: 1. userid : the unique identifier of an customer. 2. name : the name of the customer the address of the customer. 4. postalcode : the postal code of the customer. 5. userinfo : A map that contains all available profile data of the customer. Note: To obtain this customer data, you will first need to request authorization for one or more profile scopes as described above. The new LWA SDK for Android provides you two options to request customer profile data, compared to older versions of the SDK which required a call to AuthorizationManager.getProfile : 1. When the customer is not signed in to your app, call AuthorizationManager.getProfile to retrieve a User object in the result object of your onsuccess() method. 2. If the customer is currently signed in to your app, call User.fetch to get the most up-to-date customer profile data. private void fetchuserprofile() { User.fetch(this, new Listener<User, AuthError>() { /* fetch completed successfully. public void onsuccess(user user) { final String name = user.getusername(); final String = user.getuser (); final String account = user.getuserid(); final String zipcode = user.getuserpostalcode(); runonuithread(new Runnable() public void run() { updateprofiledata(name, , account, zipcode); ); /* There was an error during the attempt to get the profile. public void onerror(autherror ae) { /* Retry or inform the user of the error */ ); Login with Amazon How-to Guide Page 132

133 Login with Amazon SDK for Android 3.x Migration Guide PDF last generated: August 28, 2017 Clear Authorization Data and Log Out a User Use the new signout API provided by the new LWA SDK for Android, which replaces protected void oncreate(bundle savedinstancestate) { super.oncreate(savedinstancestate); /* Previous oncreate declarations omitted */ // Find the button with the logout ID and set up a click handler View logout Button = findviewbyid(r.id.logout); logoutbutton.setonclicklistener(new View.OnClickListener() public void onclick(view v) { AuthorizationManager.signOut(getApplicationContext(), new Listener<Void, Aut herror>() public void onsuccess(void response) { // Set logged out state in public void onerror(autherror autherror) { // Log the error ); ); Login with Amazon How-to Guide Page 133

134 Understading Login with Amazon PDF last generated: August 28, 2017 Understading Login with Amazon LWA Conceptual Overview Access Tokens Authorization Code Refresh Tokens Customer Profile Authorization Grants Security Profile Login with Amazon How-to Guide Page 134

135 Login with Amazon Conceptual Overview PDF last generated: August 28, 2017 Login with Amazon Conceptual Overview This conceptual overview describes how Login with Amazon allows a user to login and grant your website access to their customer profile data. For more details on the customer experience in native mobile apps, including how your users can skip the login screen and experience single-sign on, see: Customer Experience in Android/Fire apps (page 100), and Customer Experience in ios apps (page 63). The Login with Amazon process begins when user visits your website or mobile 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 address). If a Login with Amazon website wants to identify a user without accessing their name and address, they will not request profile data. In this case, the user is not presented with a consent screen after they log in. 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: Login with Amazon How-to Guide Page 135

136 Login with Amazon Conceptual Overview PDF last generated: August 28, 2017 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 address of the user, and/or request the user s postal (ZIP) code. For example: Login with Amazon How-to Guide Page 136

137 Login with Amazon Conceptual Overview PDF last generated: August 28, 2017 After users log in, the client will use one of the authorization grants (page 143) to get an access token (page 138). The client can then use the access token to access a customer profile (page 141), specifying an access scope. Login with Amazon How-to Guide Page 137

138 Access Tokens PDF last generated: August 28, 2017 Access Tokens 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 address from their customer profile (page 141). When you are granted an access token, you may also receive a refresh token (page 140). 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":"atzr IQEBLzAtAhRPpMJxdwVz2Nn6f2y-tpJX2DeX..." Access tokens are returned in both the Implicit and Authorization Code grants (page 143). 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. Login with Amazon How-to Guide Page 138

139 Authorization Code PDF last generated: August 28, 2017 Authorization Code An authorization code is sent to a client as the first step in an Authorization Code Grant (page 143). When the client receives the authorization code, it calls the Login with Amazon authorization service with the code, theirclient identifier and client secret. The authorization code is useless by itself, and therefore any malware that intercepts the authorization code cannot impersonate the client to gain an access token (page 138). Login with Amazon How-to Guide Page 139

140 Refresh Tokens PDF last generated: August 28, 2017 Refresh Tokens 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 (page 138), 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 (page 143). Login with Amazon How-to Guide Page 140

141 Customer Profile PDF last generated: August 28, 2017 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 address, and their postal code. This data is divided into three scopes: profile, profile:user_id and postal_code. When you request an access token (page 138), you can request multiple access scopes by separating them with a space (for example, profile postal_code ). When your request is granted, it will specify the scope(s) returned. 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 you can communicate with them via . The profile data is returned in JSON format and consists of three parts: the user_id, the , and the name. The user_id is assigned by Amazon, and uniquely identifies the user s account. The is the address that they have registered with Amazon. For example: { " " : "johndoe@gmail.com", "name" : "John Doe", "user_id" : "amzn1.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. After 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:user_id only includes the user_id field of the profile. This uniquely identifies the user but does not provide their name, 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 user_id for a customer. However, when a customer logs in to another company s app or site, the user_id will be different. This is so user_id cannot be used to track customers across the Web. postal_code The third access scope is the postal_code 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: Login with Amazon How-to Guide Page 141

142 Customer Profile PDF last generated: August 28, 2017 { "user_id" : "amzn1.account.k2li23kl2lk2" " " : "johndoe@gmail.com", "name" : "John Doe", "postal_code": "98101", When an app requests access to the postal_code scope, alone or in concert with the profile or profile:user_id scope, the user will have to consent to share the information. Login with Amazon How-to Guide Page 142

143 Authorization Grants PDF last generated: August 28, 2017 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 (page 138) 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 (page 141) data from Amazon (G). Login with Amazon How-to Guide Page 143

144 Authorization Grants PDF last generated: August 28, 2017 Login with Amazon How-to Guide Page 144

145 Authorization Grants PDF last generated: August 28, 2017 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 (page 139) 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 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 (page 138) 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 the app. After the authorization code, client identifier, and client secret are verified, the app is granted an access token and a refresh token (page 140) from the authorization service (E). They can use the access token to access the customer profile (page 141) 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. Login with Amazon How-to Guide Page 145

146 Authorization Grants PDF last generated: August 28, 2017 Login with Amazon How-to Guide Page 146

147 Security Profile PDF last generated: August 28, 2017 Security Profile Before you can use Login with Amazon on a website or in a mobile app, you must have a security profile assigned to the website or app, and that security profile must be enabled for Login with Amazon. A security profile associates Amazon data, including security credentials, with one or more apps. For example, you may have a My Game - Free and a My Game - HD that share data because they use the same security profile. The name of your security profile is sometimes displayed to users, and should identify your app or app family (such as My Game ). When you associate a security profile with Login with Amazon, you must add some information that is displayed to users when they first login to one of the apps associated with the profile. Users will see the name of your application, your logo, and a link to your privacy policy. To use Login with Amazon you must supply the following: Privacy Notice URL. The Privacy Notice URL is the location of your company or application s privacy policy (for example, ). This link is displayed to users on the consent screen. You may also supply the following: Logo Image File. This logo is displayed on the sign-in and consent screen to represent your business or website. 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. After associating Login with Amazon with a security profile, you can add apps or websites to the security profile. After specifying some identifying information about your website or app, Login with Amazon will create security credentials (client identifier or API key ) for the 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 grant use the client identifier, but the Authorization Code Grant (page 143) 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. API Key When you associate a mobile app with Login with Amazon, your app is assigned an API key. This key securely identifies your app to the Login with Amazon authorization service ; without it, any time your app tries to log in a user it will fail. After you add your API key to your mobile project, the library will automatically use it to contact the Login with Amazon authorization service. An API key is locked to the name of your Android package or ios Bundle. You can use different API keys for the same app (for example, beta and release versions of your app might have different keys). Login with Amazon How-to Guide Page 147

148 Security PDF last generated: August 28, 2017 Security Cross-site Request Forgery Impersonating a Resource Owner Open Redirectors Code Injections Login with Amazon How-to Guide Page 148

149 Cross-site Request Forgery PDF last generated: August 28, 2017 Cross-site Request Forgery Cross-site Request Forgery happens when an attacker tricks a user into clicking on a malicious link, where the link goes to a site where the user is currently 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. Login with Amazon recommends using the state parameter to prevent Cross-site Request Forgery. The client should set the value of the state parameter when it initiates an authorization request, and save it to the user s secure session. Unlike the client_id and client_secret values, in order for the state parameter to be useful in preventing attacks it should be unique, and non-guessable, for each and every authorization request. The authorization server returns the same state when communicating with the client to deliver authorization codes and access tokens. To protect users from attacks, the client must ignore communication if the returned state parameter doesn t match the value from the initial call. Calculating the State Parameter Clients can calculate the state parameter value in any way they choose, however, the value should be secure from forgery. Login with Amazon recommends using a securely-generated random string with at least 256 bits of entropy. To calculate a state value using this method, use a random number generator suitable for cryptographic operations. Here is an example in Python: def generate_state_parameter(): random = os.urandom(256) state = base64.b64encode(random) return (state) After generating the state parameter value, save it to the user s session information, ensuring the information is communicated securely and saved to a secure session. When the state is returned by an authorization response, verify the legitimacy of the user by comparing it with the state value saved to their session. If the values do not match, you should ignore the authorization response. If you re also using the state parameter value to dynamically redirect users (page 42) after authentication, consider concatenating the securely-generated random string with the dynamic URL, separated by a space (e.g. state = state + " " + dynamicurl ). When the authorization server returns the state, parse it and split it into two values based on the space. The second value will contain the dynamic URL needed to direct the user to the appropriate page after authentication. Login with Amazon How-to Guide Page 149

150 Impersonating a Resource Owner in Implicit Flow PDF last generated: August 28, 2017 Impersonating a Resource Owner in Implicit Flow Websites using the Implicit Grant (page 28) receive an access token (page 138) from the Login with Amazon authorization service passively through a redirect URL. If an attacker can entice a user into logging in to a malicious site, the attacker s site will receive a legitimate access token. The attacker can then pass that access token to the redirect URL on another site to make it appear that the user is trying to login to the site. Clients using the implicit flow can guard against this attack by verifying that an access token is legitimate before using it to retrieve a customer profile and complete login. Login with Amazon provides an endpoint specifically for verifying access tokens. Clients should use that endpoint to compare their client identifier (page 147) to the client identifier that originally requested the access token. If the client identifiers do not match, the login request should be rejected. For more information, see Verifying Access Tokens (page 32). Login with Amazon How-to Guide Page 150

151 Open Redirectors PDF last generated: August 28, 2017 Open Redirectors An open redirector is an endpoint configured to redirect a user-agent based on the value of a parameter, without any kind of validation. Open redirectors can be exploited in Login with Amazon by attackers who fool users into authorizing access to the legitimate website, but when the authorization server redirects to the client, the open redirector sends it back to the attacker. Login with Amazon client websites should ensure that the target of the redirection URI they use for authentication is not configured as an open redirector. Some common patterns for open redirectors are: example.com/go.php?url= example.com/search?q=user+search+keywords&url= example.com/coupon.jsp?code=abcdef&url= example.com/login?url= Login with Amazon How-to Guide Page 151

152 Code Injection PDF last generated: August 28, 2017 Code Injection A code injection attack happens when an attacker changes the value of an input or a parameter in a way that causes unexpected behavior in a website (such as a Login with Amazon client). A code injection attack is possible when a website does not validate incoming data before acting on it. Login with Amazon client websites should validate data coming from the authorization service, especially the state parameter, before acting on it. Login with Amazon clients should also validate customer profile data if they use it programmatically. Login with Amazon How-to Guide Page 152

153 Resources PDF last generated: August 28, 2017 Resources Button Guidelines Style Guidelines Solution Providers Login with Amazon How-to Guide Page 153

154 Button Guidelines PDF last generated: August 28, 2017 Button Guidelines If you have a use case where the provided buttons do not fit, contact us at lwa-support@amazon.com and we will work with you to find a solution. Click the appropriate link to see the available buttons for your website or app: Android (page 154) ios (page 155) Web (page 155) Looking for Login with Amazon buttons for other languages? Click the following links to download a ZIP file of buttons for ios, Android, and Web in each of these languages: Chinese (simplified) French German Japanese Italian Portuguese Spanish Android Usage Download the LWA_for_Android zip file and select the appropriate buttons for your app. You will find pressed and unpressed states for all the buttons below. All buttons are available in the following densities: hdpi, mdpi, tvdpi, xhdpi, and xxhdpi. Login with Amazon How-to Guide Page 154

155 Button Guidelines PDF last generated: August 28, 2017 ios Usage Download the LWA_for_iOS zip file and select the appropriate buttons for your app. You will find pressed and unpressed states for all the buttons below. All buttons are available in 32dp and 44dp. Web Usage We encourage you to load the button graphic directly from our servers rather than hosting your own copy. If you do load the graphics from our servers, note that the HTTP and HTTPS URLs link to different servers. Right-click the links below to copy the URL code to your clipboard. Desktop 156 x 32px 312 x 64px pressed pressed pressed pressed pressed pressed pressed pressed Login with Amazon How-to Guide Page 155

156 Button Guidelines PDF last generated: August 28, pressed pressed pressed pressed 76 x 32px 152 x 64px pressed pressed pressed pressed pressed pressed pressed pressed pressed pressed pressed pressed 32 x 32px 64 x 64px Login with Amazon How-to Guide Page 156

157 Button Guidelines PDF last generated: August 28, pressed pressed pressed pressed pressed pressed pressed pressed pressed pressed pressed pressed Touch 195 x 46px 390 x 92px pressed pressed pressed pressed Login with Amazon How-to Guide Page 157

158 Button Guidelines PDF last generated: August 28, pressed pressed pressed pressed pressed pressed pressed pressed x 46px 202 x 92px pressed pressed pressed pressed pressed pressed pressed pressed Login with Amazon How-to Guide Page 158

159 Button Guidelines PDF last generated: August 28, pressed pressed pressed pressed 46 x 46px 92 x 92px pressed pressed pressed pressed pressed pressed pressed pressed pressed pressed pressed pressed Login with Amazon How-to Guide Page 159

160 Style Guidelines PDF last generated: August 28, 2017 Style Guidelines The Login with Amazon button should be placed wherever a login is offered on your site or app. This includes where you sign up new customers as well as the login prompt for existing customers (for example, during checkout). We also recommend that you display a small button (see below) on your Home page to encourage your customers to log in for a personalized experience. For ALT text, use Login with Amazon. For example: Note that once the user is logged in, the login button should no longer be shown or be replaced with a log out message. Add more guidance to your button We also recommend the following text appears on your login screen: Login with your Amazon credentials Track your orders online View your order history Integrate with other sign-in offerings We also have provided a simple icon. This graphic is useful for sites or apps that only show icons for the different login options. For example: Login with Amazon How-to Guide Page 160

161 Style Guidelines PDF last generated: August 28, 2017 Get started Refer to the Login with Amazon Button Guidelines (page 154) to get started. Click one of the links below to access the buttons for your platform. Android (page 154) ios (page 155) Web (page 155) Login with Amazon How-to Guide Page 161

162 Solution Providers PDF last generated: August 28, 2017 Solution Providers Amazon Cognito Amazon Cognito allows you to easily use Login with Amazon for user identity in your mobile or web app. With Amazon Cognito, your app is provided with temporary, limited-privilege credentials that it can use to access AWS resources or your own resources through Amazon API Gateway. You can set granular access permissions on your AWS resources, for example, you can limit access to a folder within an S3 bucket to a particular app user, or enable unauthenticated users to access a restricted set of resources. This means your app can access the resources it needs and that you can follow security best practices by not hardcoding credentials in your app. Learn more about implementing Login with Amazon using Amazon Cognito. Login with Amazon How-to Guide Page 162

163 Solution Providers PDF last generated: August 28, 2017 Gigya Gigya provides a Registration-as-a-Service (RaaS) solution that lets you implement Login with Amazon functionality across devices in a fast and painless single-api process that offers maximum flexibility for developers. Gigya also links accounts, letting each customer log into your site or app with any number of identity providers or traditional username and password combinations, while tying all information to an individual account and storing it in one place. Gigya also keep pace with privacy and terms of service policy changes through automatic API updates. Learn more about implementing Login with Amazon using Gigya. Janrain Janrain s unified API enables developers to improve the registration and shopping experience by implementing Login with Amazon in less than a day. Janrain has more than 1,500 clients across 65 countries, including Pfizer, Samsung, Whole Foods, Fox News, Philips, Marvel and Dr Pepper. Its identity capabilities include social and traditional login and registration, single sign-on, customer profile data storage and management, customer segments, customer insights and engagement solutions. Janrain supports 11 SDKs including Java, Android and ios, as well as 11 extensions such as Demandware, Drupal, Magento and Wordpress. Learn more about implementing Login with Amazon using Janrain. Login Radius Login with Amazon How-to Guide Page 163