Account Linking Concepts for Alexa Skills

To create a link between the Alexa user's Amazon account and the account that they have with your service, the Alexa Skills Kit uses the OAuth 2.0 authentication framework. OAuth 2.0 defines a means by which your service can allow Alexa, with the user's permission, to access information from the account that the user has set up with you.

This topic describes OAuth 2.0 concepts in the context of the most common account-linking implementation for Alexa skills: Alexa-app only account linking with the authorization code grant type. Less common variants of account linking such as a different grant type (implicit grant) or an alternate flow (app-to-app account linking) share many of the same concepts but are not described here.

Overview

For Alexa skills, account linking rests on the concept that to access the user's account in your system, the Alexa skill must use an access token. In other words, to "link accounts" means "to get the user's permission to obtain an access token" so that the skill can use the access token in API calls to the server that contains the user data. Here, we assume that you own the server that contains the user data, though it could be owned by a third party.

In the most typical scenario (authorization code grant type), the Alexa service does not get an access token directly: it must first get an authorization code and then exchange that for an access token (and, optionally, a refresh token so that it can request a new access token when the old access token expires). The following figure shows the relationship between the key components of account linking, which are described later in this topic. For an example of how users experience the account linking flow, see How Users Experience Account Linking for Alexa Skills.

Alexa app-to-app account linking.

Concepts

This section reviews concepts that you might encounter as you implement account linking.

OAuth roles

OAuth 2.0 defines four roles: resource owner, resource server, client, and authorization server. The following sections describe these roles in the context of Alexa skills. The examples use a fictional custom skill that lets users order rides (Ride Hailer) and a smart home skill that can control lighting (My Lights).

Resource owner

This is the Alexa user who wants to enable your skill and link it to their account in your system.

Resource server

This is the server that hosts the protected resource (user data) that the Alexa skill needs to access, with the user's permission.

Client

This is the Alexa skill that is making requests to your resource server on behalf of the Alexa user, with the user's permission.

Although the skill is the OAuth client, Alexa performs some operations on behalf of the skill. For example, Alexa makes requests to the authorization server to get an access token. The skill is still considered the client because it is the only component that ever accesses the protected resource (user data) in the resource server.

Authorization server

This is the server that identifies and authenticates the identity of the Alexa user with a user in your system. It plays a key role in account linking in that it: 1) displays a log-in page for the user to log into your system, 2) authenticates the user in your system, 3) generates an authorization code that identifies the user, and 4) passes the authorization code to the Alexa app, and finally, 5) accepts the authorization code from the Alexa service and returns an access token that the Alexa service can use to access the user's data in your system. Due to that last step, the authorization server is sometimes also called a token server.

You can use a third-party authorization server such as Login with Amazon or build your own. In any case, the authorization server must support Oath2.0. If you use a third-party authorization server, the authorization server provides you with data that you can map to your users in your resource server. For example, if you use Login with Amazon to authenticate users, and then use the Amazon profile:user_id to access a user's profile in your database.

For authorization URI requirements, see Authorization URI requirements.

Codes and tokens

As described previously, account linking for Alexa skills involves using an access token to access the resource (in this case, the user's account with your service). In the most typical scenario (authorization code grant type), the client must first get an authorization code and then exchange that for an access token and, optionally, a refresh token so that it can request a new access token when the old access token expires. These are described next.

Authorization code

This is a code that your authorization server gives the Alexa service so that the Alexa service can exchange the code for an access/refresh token pair. Your authorization server gives the Alexa service the authorization code by including it in the query string when it redirects the user back to the Alexa app after the user logs into your authorization server.

Access token

This is a credential that your token server gives the Alexa service in exchange for the authorization code that your authorization server gave the Alexa service after the user logged into your authorization server. The access/refresh token pair identifies the user in your system and represents the user's permission for the Alexa skill to access their data in your system. After the Alexa service gets the access token from your token server, it includes the access token in requests sent to your skill if the user has successfully linked their account.

For access token URI requirements, see Access token URI requirements.

Refresh token

This is a credential that the Alexa service can use to request a new access token after the old access token expires.

Reciprocal access token

Reciprocal access tokens are used in reciprocal authorization, which is a way for the user to allow a pair of resources (the Amazon account they use with Alexa, and the account with your service) to be synced and updated between the two accounts.

Grant types

OAuth 2.0 defines a number of grant types. Grants are ways for a client application (in this case, an Alexa skill) to authorize the user and obtain an access token that it can use to authenticate a request to the resource server. There are two grant types that apply to Alexa skills: the authorization code grant (the vast majority of cases) and the implicit grant (limited use). The Alexa account linking documentation focuses on the authorization code grant type because it is the recommended grant type for security and usability reasons.

Authorization code grant type

This is the grant type in which the Alexa service gets an authorization code from your authorization server, exchanges it for an access token, and then passes the access token in requests to your skill. (This was described in Codes and tokens also.) In an authorization code grant, your authorization server gives the Alexa service the authorization code by including it in the query string when it redirects the user back to the Alexa app after the user logs into your authorization server. The Alexa service then uses this code to request an access/refresh token pair from your token server, using the access token endpoint (URI). The refresh token can then be used to request a new access token after the old token expires. Implement the authorization code grant type unless you are sure that you want the implicit grant type.

Implicit grant type

This is a grant type for requesting the end user's authorization to access their information in another system. In an implicit grant, the authorization server returns the access token once the user logs in. This grant type is less secure, and is limited compared to the authorization code grant type. Only custom skills can use the implicit grant type.

Reciprocal authorization

Reciprocal authorization is when the user allows a pair of resources to be synced and updated. Typical account linking allows Alexa to access resources in your system. Reciprocal authorization goes a step further, in that it allows you to access Alexa resources as well.

Most OAuth servers only provide the ability to authenticate and authorize users in your system. However, some skills must proactively interact with the Alexa backend to make updates. In Alexa, this is achieved by a reciprocal authorization endpoint, which you host to obtain an authorization code from Alexa.

URIs that account linking uses

This section describes the URIs that relate to account linking.

Name Description Where you specify or get it

Authorization URI

The URI of your authorization server, which provides the Alexa service with an authorization code. The Alexa service calls the authorization URI with these query parameters.

For a list of requirements regarding the authorization server, see Authorization URI requirements.

You specify this using:

  • Developer console (Authorization URI)
  • ASK CLI (Authorization URL)
  • SMAPI (authorizationUrl).

Alexa redirect URI

Your authorization server calls this URI to take the user back to the Alexa app after they log into your system.

Use the value that the Alexa service passes as the redirect_uri query parameter when it calls your authorization URI.

You can also find the Alexa redirect URI in the developer console (Alexa Redirect URLs), ASK CLI, or SMAPI (redirectUrls). However, these sources list multiple redirect URIs because the final value depends on where the user registered their Alexa device. As noted previously, use the redirect_uri that Alexa passes to your authorization URI as a query parameter.

You must register the Alexa redirect URI as described in Authorization URI requirements.

Access token URI

The URI of your token server, which is the endpoint of your authorization server that can receive an authorization code and return an access/refresh token pair that the Alexa service can use to access the user's data in your system. The Alexa service makes a POST request to the access token URI and includes the authorization code in the parameters. The token server responds and includes the access/refresh tokens in JSON.

For a list of requirements regarding access tokens, see Access token URI requirements.

You specify this using:

  • Developer console (Access Token URI)
  • ASK CLI (Access Token URI)
  • SMAPI (accessTokenUrl).

Last updated: Aug 03, 2022