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.
Making database changes
You will need to modify your account database to record a mapping between Amazon account identifiers and your local accounts. This could take the form of a new field in your account table or a table that maps between Amazon account identifiers and your local account identifiers.
Amazon account identifiers are returned as the
user_ID property, in the form
amzn1.accountVALUE. For example:
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. The steps to implement this are available on login.amazon.com.
Handling authentication responses
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 do three things:
- Use the SDK to call the profile endpoint with the access token to get the authorized scope information (name, email, and user id). This profile data is declared by the customer when they create an account, but is not verified by Amazon.
- 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 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 http://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.