Login with Amazon Integrate with your Existing Account System

: June 8, 2024
: Amazon

Table of Contents

Login with Amazon: Integrate with your Existing Account System
Read User Manual Online (PDF format)
Download This Manual (PDF format)

Amazon and the Amazon logo are trademarks of Amazon.com, Inc. or its affiliates. All other trademarks not owned by Amazon are the property of their respective owners.

Introduction

This is a guide for integrating customer profile data from Login with Amazon user accounts with a website or mobile app that already has an account management system.

You will learn how you can enable your site or app to let users log in using their Amazon accounts, as well as how you can let existing users of your website attach their Amazon identity so that they log in with their Amazon credentials.

What you Need to Have

This guide assumes you have previously signed up for Login with Amazon, registered your website or 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 site or app currently has these features:

An account database where you record information about each user account:
a. Users have some kind of unique identifier
b. Users currently sign in using their username/password
A sign-in page for registered users.
A registration page for registering new users by taking in profile information (name, email, etc.).
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).

What you Need to Do

These are the high level changes you need to make to integrate Amazon customers into your account management system:

Database Changes: You will need to map Amazon customer identifiers to your own internal identifiers. This might take the form of an additional field in the users table in your database.
Sign-in UI Changes: You need to change your sign-in page, registration page, and checkout page (if applicable). 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. The steps to implement this are covered in the Login with Amazon Style Guidelines.
Create a Response Handler: This is a new page on your site, or function in your app to handle authentication responses from Amazon.

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.

Using the relevant SDK or server-side methods for your website or 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 details on how to authenticate users using Login with Amazon, please see our developer guides for iOS, android- gsg._TTH [PDF], and website-gsg._TTH.

Obtain and Secure Amazon Customer Profile Data

Once the user has interacted with the Login with Amazon service to authenticate (and, on the first visit, authorize data sharing), you will receive an authentication response.

When you receive an authentication response you should:

Send the access token in your authorization response to your server using HTTPS.
From server side, call the profile endpoint using the access token. See the section titled Using Access Tokens to Read a Customer Profile of the Login with Amazon website-developer-guide._TTH [PDF] for details on calling the profile endpoint server-side, including code samples in multiple languages. Login with Amazon will return a customer profile response with values (such as user_id, email, 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.
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.
Search for the user’s email address in your account system. If they have a local account with that email address, prompt them to enter their local credentials to allow Login with Amazon to log in that account.
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 that 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 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 not 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 email address. You may 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 email 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.

Note: If your website or app’s local account management includes resetting passwords, you may want to ensure that Login with Amazon users do not get confused about how that effects their Amazon account. That could mean hiding a “Reset Password” link if users are logged in via Login with Amazon, or a note on the password reset page directing them to https://www.amazon.com if they want to change their password.

Mark the User as Authenticated

Once you have received a valid authentication response and found or created a corresponding account in your own account database, you should mark the user has having authenticated. This step can work exactly the same as in your current authentication system.

Login with Amazon Integrate with your Existing Account System – Download [optimized]
Login with Amazon Integrate with your Existing Account System – Download