Integrate with Your Existing Account System
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.
- 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
- Users have some kind of unique identifier
- 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 doThese 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:
Set up Login with Amazon
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, and websites.
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:
- Send the access token in your authorization response to your server using HTTPS.
- From server-side, call the
profileendpoint using the access token. See the section titled Using Access Tokens to Read a Customer Profile of the Login with Amazon developer guide for details on calling the
profileendpoint server-side, including code samples in multiple languages. Login with Amazon will return a customer profile response with values (such as
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 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 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.
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 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 https://www.amazon.com if they want to change their password.
Mark the user as authenticated
Once you have 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.