Home > Alexa > Alexa Skills Kit

Linking an Alexa User with a User in Your System

Overview

Overview

Some skills require the ability to connect the identity of the end user with a user in another system. This is referred to as account linking, since the goal is to create a link between the Alexa user and the user account in your system. Skills that use the Smart Home Skill API must use account linking (with the authorization code grant flow) to connect the Alexa user with their device cloud account. Custom skills can use accounting linking if needed.

For example, suppose you own a web-based service “Car-Fu” that lets users order taxis. A custom skill that lets users access Car-Fu by voice (“Alexa, ask Car-Fu to order a taxi”) would be very useful. Completing this request requires the skill to access your Car-Fu service as a specific Car-Fu user. Therefore, you need a link between the Amazon account used with the Alexa device and the Car-Fu account for the user.

This document describes the supported methods for establishing this type of link between an Alexa user and a user in your system.

Note that account linking is needed when the skill needs to connect with a system that requires authentication. If your custom skill just needs to keep track of a user to save attributes between sessions, you do not need to use account linking. Instead, you can use the userId provided in each request to identify the user. The userId for a given user is generated when the user enables your skill in the Alexa app. Every subsequent request from that user to your skill contains the same userId unless the user disables the skill.

How Account Linking Works

To connect an Alexa user with an account in your system, you need to provide an access token that uniquely identifies the user within your system. The Alexa service stores this token and includes it in requests sent to your skill’s service. Your skill can then use the token to authenticate with your system on behalf of the user.

Using account linking in the Alexa Skills Kit assumes some familiarity with the OAuth 2.0 authorization framework. Two OAuth authorization grant types are supported:

The primary difference between these two types is in how the access token is obtained from your system. From the end user’s perspective, there is no difference.

OAuth Roles and the Alexa Skills Kit

OAuth 2.0 specifies four roles: resource owner, resource server, client, and authorization server. When using OAuth with the Alexa Skills Kit, these roles are defined as follows:

  • Resource owner: the end user who wants to connect your skill with their user account in your system.
  • Resource server: The server hosting the resources the user wants to access. This server is part of your system, and it must be able to accept and respond to requests using access tokens. In the Car-Fu example, this is part of the Car-Fu service. The protected resource is the user’s Car-Fu account profile.
  • Client: The application making the requests to the resource server on behalf of the resource owner. In this context, this is the Alexa service.
  • Authorization server: The server that authenticates the identity of the resource owner and issues access tokens. In the Car-Fu example, this is also part of the overall Car-Fu service.

Note that the resource server and authorization server can be the same server.

How End Users Set Up Account Linking for a Skill

Users link their accounts using the Amazon Alexa app. Note that users must use the app. There is no support for establishing the link solely by voice. Users can start the process:

  • When initially enabling your skill in the app
  • After making a request that requires authentication. In this case, your skill returns a LinkAccount card, and the user can start the process from the card in the Alexa app. Note that this scenario is possible for custom skills, but not smart home skills.

The specific flow varies depending on whether you are using implicit grant or authorization code grant, but the end-user steps are the same for both.

Account linking flow for authorization code grant (for use with smart home skills or custom skills):

  1. In the Alexa app, the user enables the skill.
  2. The app displays your login page right within the app, using the Authorization URL you provide when registering your skill on the developer portal. When the companion app calls this URL, it includes state, client_id, response_type, scope, and redirect_uri as query string parameters.
    • The state is used by the Alexa service during the account linking process. Your page needs to keep track of this value, as you must pass it back later.
    • The client_id is a value defined by you when you set up account linking for the skill in the developer portal.
    • The response_type is always code for the code grant flow.
    • The scope is an optional list of access scopes indicating the level of access requested. You define the set of scopes to support when enabling account linking for your skill.
    • The redirect_uri is the URL to which your service redirects the user once the user is authenticated.
  3. The user logs in using their normal credentials for your site.
  4. Your service authenticates the user and then generates a code.
  5. Your service redirects the user to the specified redirect_uri and passes along the state and code in the URL query parameters.
  6. The Alexa service validates the returned information, then uses the code to request an access token and refresh token pair from your authorization server (specified in the Access Token URI field in the developer portal). Both of these items are saved for the Alexa user.
  7. The user’s Alexa account is now linked to the account in your service, and the skill is ready to be used.

Account linking flow for implicit grant (for use with custom skills):

  1. In the Alexa app, the user enables the skill.
  2. The app displays your login page right within the app, using the Authorization URL you provide when registering your skill on the developer portal. When the companion app calls this URL, it includes state, client_id, response_type, and scope as query string parameters.
    • The state is used by the Alexa service during the account linking process. Your page needs to keep track of this value, as you must pass it back later.
    • The client_id is a value defined by you when you set up account linking for the skill in the developer portal.
    • The response_type is always token for the implicit grant flow.
    • The scope is an optional list of access scopes indicating the level of access requested. You define the set of scopes to support when enabling account linking for your skill.
    • The redirect_uri is the URL to which your service redirects the user once the user is authenticated.
  3. The user logs in using their normal credentials for your site.
  4. Your service authenticates the user and then generates an access token that uniquely identifies the user in your system.
  5. Your service redirects the user to the specified redirect_uri and passes along the state, access_token, and token_type in the URL fragment.
  6. The Alexa service validates the returned information and then saves the access_token for the Alexa user.
  7. The user’s Alexa account is now linked to the account in your service, and the skill is ready to be used.

What Happens when a User Invokes a Skill with Account Linking

When a user begins interacting with a custom skill that has been set up with account linking, the following occurs:

  1. The user invokes the skill normally. For example: “Alexa, ask Car-Fu to order me a taxi.”
  2. If using authorization code grant, the Alexa service makes sure that the access token saved for the user is still valid. If it has expired, the Alexa service uses the refresh token to request a new access token from your authorization server.
  3. The LaunchRequest or IntentRequest sent to the service for your skill includes the previously-saved access token for the user.
  4. Your service validates that the token matches a user in your system:

    • If the token is valid for a user, your service accesses the user’s information as needed, completes the request normally, then sends back an appropriate response with the text to speak to the user and the optional card to display in the Alexa app.

      For instance, in the Car-Fu example, the Car-Fu skill verifies that the provided token matches a valid Car-Fu user. If it does, the service can access the Car-Fu profile for that user and use that information to complete the user’s request for a car.

    • If the token is invalid, your service returns text telling the user to link their account and a LinkAccount card. The user can click the link on this card to start the account linking process:

      Example of a LinkAccount card
      Example of a LinkAccount card

The process is similar for smart home skills:

  1. The user invokes the skill normally. For example: “Alexa, turn on the living room lights.”
  2. The Alexa service makes sure that the access token saved for the user is still valid. If it has expired, the Alexa service uses the refresh token to request a new access token from your authorization server.
  3. The device directive sent to your skill adapter includes the previously-saved access token in the payload.
  4. Your skill adapter passes along the token to the device cloud to complete the user’s request.
    • If the token is valid, the device cloud completes the request normally and turns on the requested light.
    • If the token is invalid, your skill adapter should return a DependentServiceUnavailableError. Alexa then tells the user that she was unable to complete the request.

For more about device directives, see the Smart Home Skill API Reference.

What Happens if the User Disables a Skill with Account Linking

If the user disables the skill in the Alexa app, the Alexa service deletes the access token (and refresh token if applicable) associated with that user and skill. This essentially removes the link between the user’s Alexa account and their account in your service.

If the user later re-enables the skill, they will need to complete the account linking process as a new user.

What Do You Need to Add Account Linking to Your Skill?

To implement account linking in a skill, you need the following:

Authorization Code Grant Implicit Grant
A web-based service that authenticates users. A web-based service that authenticates users.
An authorization server that can present a login page to collect user’s credentials, authorize the user, and then generate an authorization code. An authorization server that can present a login page to collect user’s credentials, authorize the user, and then generate an access token that uniquely identifies that user.
An authorization server that can accept the authorization code and Alexa’s client credentials and generate an access token that uniquely identifies that user. Not Applicable

To add account linking to your skill, you must do the following:

  1. Add account linking support to the login page for your service.
  2. Add account linking logic to the cloud-based service (web service or Lambda function) for your skill.
  3. Enable account linking for your skill on the developer portal.

See the sections below for details about these steps.

Adding Account Linking Support to Your Login Page (Authorization URL)

When a user starts the process of linking accounts, the Alexa app displays a login page for your resource server. You need to design and code a page appropriate for this purpose. The page needs to validate the user’s credentials and then return either an access token or authorization code.

You provide the URL for this page in the Authorization URL field when enabling account linking for your skill in the developer portal.

Providing the Login Page in the User’s Language

The Alexa app attempts to use the user’s browser language preference to display a localized version of the app if the user’s browser is set to one of the supported languages (en-us, en-gb, or de-de). For other languages, the app defaults to en-us.

For a consistent user experience, your login page should also render in the same language as the Alexa app. To get the language, check the Accept-Language header first. The Alexa app attempts to set this when calling your Authorization URL.

If the header is not set, you can use the language defined by the user’s browser by checking navigator.language or navigator.browserLanguage. See Navigator language Property.

Note that the user’s browser settings are independent of the language defined on the user’s Alexa-enabled device. For example, a user could configure their device to use German, but configure their browser to use UK English. In this case, the Alexa app renders in English and the Accept-Language header is set to English (en-gb).

Parameters Passed to Your Authorization URL

The Alexa app includes the following parameters in the URL query string when it calls your Authorization URL:

  • state is used internally by the Alexa service to track the account linking process.
    • Your page must pass this value back (unchanged) when calling the redirect URL.
    • This value expires after five minutes. If it takes more than five minutes for the user to log in and for your service to redirect the user, the state becomes invalid and the account linking process fails. In this case, the user must start over by clicking the link in the Alexa app.
  • client_id is an identifier defined by you. You can use this to provide any skill-specific functionality, such as distinguishing between different skills you have configured with account linking. You define your client_id when enabling account linking for your skill in the developer portal.
  • The response_type value depends on whether you are using authorization code grant or implicit grant.
    • code for authorization code grant.
    • token for implicit grant.
  • scope is an optional list of scopes indicating the access the Alexa user needs. You define these scopes when enabling account linking for your skill in the developer portal.
    • You can use this information when generating the access token. For example, you could create a token that allows access to basic profile information in your resource server, but does not allow access to payment information.
    • Multiple scopes can be used. The list is delimited by URL-encoded spaces.
    • You may want to also tell users what access they are allowing by linking their accounts. For instance, your login page could display text such as “This allows the Car-Fu skill to order a taxi on your behalf and charge your account for the cost.”
  • redirect_uri is the Amazon-specific redirect URL (OAuth Redirection Endpoint) to which your service should redirect the user after authenticating the user. The values you can expect for this parameter are also displayed on the developer portal when you configure account linking, so you can verify that the URL is valid.

For example, if the authorization URL for your page is https://www.carfu.com/login, the URL called by the Alexa app might look like this (for authorization code grant):

https://www.carfu.com/login?state=abc&client_id=alexa-skill&scope=order_car%20basic_profile&response_type=code&redirect_uri=https%3A%2F%2Fpitangui.amazon.com%2Fspa%2Fskill%2Faccount-linking-status.html%3FvendorId%3DAAAAAAAAAAAAAA

Requirements for Your Login Page

Your login page should meet the following requirements:

  • It must be served over HTTPS.
  • It must be mobile-friendly, as it will be displayed within the Alexa app.
  • The page cannot open any pop-up windows.
  • It must accept the user’s credentials and then authenticate the user.
  • It must either:
    • Generate an access token that uniquely identifies the user to your resource server.
    • Generate an authorization code that can be passed to your authorization server to retrieve an access token.
  • It must keep track of the state value passed in the query string.
  • After authenticating the user, the page must redirect the user to one of two Amazon-provided redirect URLs.
    • The redirect URL you use is included in the authorization request as the redirect_uri parameter.
    • Two redirect URLs are also displayed in the developer portal when you turn on the account linking options for your skill, so you can see the possible values your login page should expect in the redirect_uri parameter.
    • For authorization code grant, include the state, and code in the URL query string.
    • For implicit grant, include the state, access_token, and token_type in the URL fragment. The token_type should be Bearer.

For example, assume your Amazon-provided redirect URL is the following:

https://pitangui.amazon.com/spa/skill/account-linking-status.html?vendorId=AAAAAAAAAAAAAA

For authorization code grant, the redirect URL might look like this:

https://pitangui.amazon.com/spa/skill/account-linking-status.html?vendorId=AAAAAAAAAAAAAA&state=xyz&code=SplxlOBeZQQYbYS6WxSbIA

The parameters you must pass back (state and code) are in the query string portion of the URL.

For implicit grant, the redirect URL might look like this:

https://pitangui.amazon.com/spa/skill/account-linking-status.html?vendorId=AAAAAAAAAAAAAA#state=xyz&access_token=2YotnFZFEjr1zCsicMWpAA&token_type=Bearer

The parameters you must pass back (state, access_token, and token_type) are in the URL fragment portion of the URL. This is the portion after the hashtag (#).

About Access and Refresh Tokens

Your authorization server needs to provide an access token that uniquely identifies a user in your system.

For authorization code grant, the Alexa service calls your authorization server (specified as the Access Token URI in the developer portal) and passes the code and client credentials. The authorization server must return the access token and an optional refresh token. Although the refresh token is optional, it is recommended if your access token expires. The Alexa service can use the refresh token to get a new access token when the previous one expires, without disrupting the end user.

For implicit grant, your login page includes the access token when calling the redirect URL, as shown in the redirect URI examples above. Implicit grant does not support refresh tokens, so if the token expires, the end user will need to re-link the accounts. If you want to use expiring tokens, use authorization code grant instead.

For either type, when generating the access token, provide a token specific to your resource server. Do not use access tokens provided by other OAuth providers such as Google or Facebook. For security, your token should be a value that identifies the user, but cannot be guessed.

Adding Account Linking Logic to the Service for Your Skill

To add account linking to your skill, you need to code the logic to verify and use the access token included in requests sent to your skill.

Getting the Access Token from the Request (Custom Skills)

When using the Java library, the access token is available in the Session object passed to the onIntent(), onLaunch(), and onSessionEnded() methods. You can use the Session.getUser() method to retrieve a User, then call User.getAccessToken() to get the token.

In the JSON, the access token is available in the accessToken property of the user object in the request:

{
  "version": "string",
  "session": {
    "new": boolean,
    "sessionId": "string",
    "application": {
      "applicationId": "string"
    },
    "attributes": {
      "string": object
    },
    "user": {
      "userId": "string",
      "accessToken": "string"
    }
  },
  "request": object
}

Getting the Access Token from the Request (Smart Home Skills)

The access token is sent to your skill adapter as part of the device directive, in the accessToken property of the payload object.

For example, note this DiscoverAppliancesRequest directive:

{
  "header": {
    "namespace": "Alexa.ConnectedHome.Discovery",
    "name": "DiscoverAppliancesRequest",
    "payloadVersion": "2",
    "messageId": "6d6d6e14-8aee-473e-8c24-0d31ff9c17a2"
  },
  "payload": {
    "accessToken": "string"
  }
}

Validating the Access Token

For a request that requires authentication, your code should do at least two checks:

  1. Validate that the accessToken exists (custom skills only).

    In the Java library, User.getAccessToken() returns null if the user has not successfully linked their account.

    In the JSON, the accessToken property does not exist if the user has not linked their account.

    Note that this check does not apply to smart home skills. It is not possible to enable a smart home skill without also successfully linking the accounts.

  2. If the accessToken exists, verify that it is valid and identifies a user in your resource server. An existing token could become invalid for multiple reasons, for example:

    • The user deleted or canceled their account with your service. For example, an Alexa user might have set up account linking with Car-Fu, then later canceled their Car-Fu account. At this point, the token stored by the Alexa service would identify a non-existent user.
    • The token has expired, and the Alexa service was unable to obtain a new token. This can occur when using authorization code grant if your authorization server does not provide refresh tokens. This can also occur if you are using the implicit grant authorization, which does not support refresh tokens.

If the token is valid, the skill can handle the request normally, accessing data from your resource server as needed. In the Car-Fu example, the skill would retrieve profile and payment information for the user from the Car-Fu service, order a car, and return a confirmation to the user. See the “Returning a Response” section of Handling Requests Sent by Alexa for more about returning responses.

Responding to an Invalid Access Token (Smart Home Skills)

If the access token sent to your skill adapter for a smart home skill is invalid, return a DependentServiceUnavailableError. Alexa then tells the user that she was unable to complete the request.

Responding to an Invalid or Non-existent Access Token (Custom Skills)

If the access token sent to your custom skill does not exist or is invalid, your skill should return a response containing the following:

  • Output speech text explaining to the user that they need to link their account to use this feature.
  • A link account card. This is a special type of card that tells the user to link their account. When displayed in the Alexa app, this card displays a link to the URL for your login page. The user can start the account linking process right from this card.

To send the link account card:

  • When using the Java library, create an instance of the LinkAccountCard class and include it as the card in your response.
  • When using JSON, set the card type to LinkAccount:

     {
         "version": "1.0",
         "sessionAttributes": {
           ...(session attributes not shown)
         },
         "response": {
           "outputSpeech": {
             "type": "PlainText",
             "text": "You must have a Car-Fu account to use this skill. Please use the Alexa app to link your Amazon account with your Car-Fu Account."
           },
           "card": {
             "type": "LinkAccount"
           },
           "shouldEndSession": true
         }
     }
    

In most cases, this response should end the session, since the user cannot continue with their request until after they have linked their account. If your skill includes some intents that don’t require authentication, it may make sense to ask the user a different question and keep the session open.

When to Require a Valid Access Token

Your service should validate the accessToken for every request that requires the user to authenticate with your web site.

For a smart home skill, this includes every directive.

For a custom skill, this usually includes most intents, but you can have intents that don’t require authentication. For example, the Car-Fu custom skill might require user authentication to order a car, but does not require authentication to just ask whether the service is available in a particular city. Therefore, the code for this skill might do the following:

  • The handler for an OrderTaxi intent would check for a valid accessToken and use that token to retrieve the user’s Car-Fu profile and order a car.
  • The handler for a generic TaxiAvailabilityByCity intent would not need to check for an accessToken, but would look up public information on the Car-Fu service and return a response.

Enabling Account Linking for a Skill in the Developer Portal

You enable account linking on the Configuration page in the Amazon Developer Portal.

After registering your skill on the portal normally, navigate to the Configuration page and select Yes for Account Linking or Creation. Note that this option is not displayed for smart home skills, since account linking is always required.

At a minimum, you must enter the following to enable account linking:

  • Authorization URL: The URL for your web site’s login page. Refer back to Adding Account Linking Support to Your Login Page for information about how this page is used when users link their accounts.
  • Client Id: An identifier your login page uses to recognize that the request came from your skill. This value is passed to your authorization URL in the client_id parameter. When using authorization code grant, this value is also part of the client credentials that the Alexa service includes when requesting an access token from the Access Token URI.
  • Authorization Grant Type: The type of OAuth 2.0 authorization grant to use to obtain the access token. The Alexa Skills Kit supports two grant types:
  • For Authorization Code Grant, you must also fill in the following:
    • Access Token URI: The URL for the authorization server that provides the access tokens.
    • Client Secret: A credential you provide that lets the Alexa service authenticate with the Access Token URI. This is combined with the Client Id to identify the request as coming from Alexa.
    • Client Authentication Scheme identifies the type of authentication Alexa should use when requesting tokens from the Access Token URI.
  • Privacy Policy URL: A URL for a page with your privacy policy. This link is displayed in the Alexa app. This is required for skills that use account linking. Note that the URL you enter is also shown in the Privacy Policy URL field on the Privacy & Compliance page.

If your login page retrieves content from other domains, enter those in the Domain List. This is only necessary for domains beyond your authorization URL. For example, suppose your authorization URL is https://www.carfu.com/login. If your page pulls in any content (such as images) from domains other than www.carfu.com, you would add them to the Domain List.

If your resource server supports different scopes for access, enter those in the Scope list. All of the scopes entered here are included in the scope parameter when the Alexa app calls your authorization URL.

Redirect URL Values

Enabling account linking displays your Redirect URL. This is the URL to which your login page must redirect the user after they are authenticated. This value is also passed to your login page as the redirect_uri parameter included with the Authorization URL.

Note that there are multiple Redirect URL values. The Alexa app passes your Authorization URL the value you should use based on where the user registered their device.

The parameters your page needs to include when redirecting the user after authentication depend on the whether you are using authorization code grant or implicit grant. Refer back to Requirements for Your Login Page.

Next Steps

Coding topics (custom skills):

Other topics:

Reference materials:

Verknüpfen eines Alexa-Benutzers mit einem Benutzer in Ihrem System

Überblick

Für einige Skills muss die Identität des Endbenutzers mit einem Benutzer in einem anderen System verknüpft werden. Dies wird als Kontoverknüpfung bezeichnet, weil damit eine Verknüpfung zwischen dem Alexa-Benutzer und dem Benutzerkonto in Ihrem System erstellt wird. Skills, die die Smart Home Skill API verwenden, müssen die Kontoverknüpfung (mit dem Ablauf zur Erteilung des Autorisierungscodes) nutzen, damit der Alexa-Benutzer mit dem Cloud-Konto seines Geräts verbunden werden kann. Benutzerdefinierte Skills können falls erforderlich die Kontoverknüpfung verwenden.

Beispiel: Sie betreiben einen Webdienst namens Mitfahrdienst, über den Benutzer Taxis bestellen können. Ein benutzerdefinierter Skill, bei dem Benutzer sprachgesteuert auf Mitfahrdienst zugreifen können („Alexa, bestelle bei Mitfahrdienst ein Taxi“) wäre eine nützliche Sache. Der Skill erfüllt diese Anforderung, indem er auf den „Mitfahrdienst“-Dienst als „Mitfahrdienst“-Benutzer zugreift. Sie benötigen daher eine Verknüpfung zwischen dem Amazon-Konto, das mit dem Alexa-Gerät verwendet wird, und dem „Mitfahrdienst“-Konto für den Benutzer.

In diesem Dokument werden die unterstützten Methoden für die Einrichtung dieser Art von Verknüpfungen zwischen einem Alexa-Benutzer und einem Benutzer in Ihrem System beschrieben.

Beachten Sie, dass die Kontoverknüpfung erforderlich ist, wenn der Skill sich mit einem System verbinden muss, für das eine Authentifizierung erforderlich ist. Wenn Ihr benutzerdefinierter Skill nur den Benutzer nachverfolgen muss, um Attribute zwischen Sitzungen zu speichern, ist eine Kontoverknüpfung nicht erforderlich. Sie können anstatt dessen die userID verwenden, die bei jeder Anforderung mitgeliefert wird, um den Benutzer zu identifizieren. Die userID für einen bestimmten Benutzer wird generiert, wenn der Benutzer Ihren Skill in der Alexa App aktiviert. Jede nachfolgende Anforderung von diesem Benutzer an Ihren Skill enthält dieselbe userID, bis der Benutzer den Skill deaktiviert. Der Beispiel-Skill Scorekeeper zeigt, wie die userID-Werte in einer Datenbank gespeichert werden, um die Attribute zwischen Sitzungen beizubehalten.

Funktionsweise der Kontoverknüpfung

Zur Verknüpfung eines Alexa-Benutzers mit einem Konto in Ihrem System benötigen Sie einen Zugriffstoken (Zugriffsberechtigung), der den Benutzer in Ihrem System eindeutig identifiziert. Der Alexa-Dienst speichert diese Zugriffsberechtigung und sendet sie mit Anforderungen an Ihren Skill-Dienst mit. Ihr Skill kann dann die Zugriffsberechtigung verwenden, um eine Authentifizierung des Benutzers in Ihrem System durchzuführen.

Wenn die Kontoverknüpfung im Alexa Skills Kit verwendet wird, sollten Sie über gewisse Kenntnisse mit dem OAuth 2.0 Authorization Framework verfügen. Zwei OAuth-Typen für die Erteilung einer Autorisierung werden unterstützt:

Der wichtigste Unterschied zwischen diesen beiden Typen besteht darin, wie die Zugriffsberechtigung in Ihrem System erworben wird. Für den Endbenutzer ist kein Unterschied erkennbar.

OAuth-Rollen und das Alexa Skills Kit

OAuth 2.0 legt vier Rollen fest: resource owner (Ressourceneigentümer), resource server (Ressourcenserver), Client und authorization server (Autorisierungsserver). Wenn Sie OAuth mit dem Alexa Skills Kit verwenden, werden diese Rollen wie folgt definiert:

  • Ressourceneigentümer: der Endbenutzer, der Ihren Skill mit dem Benutzerkonto in Ihrem System verbinden möchte.
  • Ressourcenserver: Der Server, der die Ressource hostet, auf die der Benutzer zugreifen möchte. Der Server ist Teil Ihres Systems und muss fähig sein, die Anforderungen, die mit Zugriffsberechtigungen eintreffen, zu akzeptieren und darauf zu reagieren. Im „Mitfahrdienst“-Beispiel ist dies Teil des „Mitfahrdienst“-Dienstes. Die geschützte Ressource ist das Kontoprofil des Benutzers auf „Mitfahrdienst“.
  • Client: Die Anwendung, die Anforderungen an den Ressourcenserver im Auftrag des Eigentümers der Ressource durchführt. In diesem Kontext ist dies der Alexa-Dienst.
  • Autorisierungsserver: Der Server, der die Identität des Eigentümers der Ressource authentifiziert und Zugriffsberechtigungen erteilt. Im „Mitfahrdienst“-Beispiel ist dies ebenfalls Teil des „Mitfahrdienst“-Dienstes.

Beachten Sie, dass der Ressourcenserver und der Autorisierungsserver in einem Server zusammengefasst werden können.

Einrichten der Kontoverknüpfung für einen Skill durch Endbenutzer

Benutzer verknüpfen Ihre Konten mithilfe der Amazon Alexa App. Beachten Sie, dass die Benutzer dafür die App verwenden müssen. Die Verknüpfung kann nicht durch Sprachbefehle erfolgen: Dafür gibt es keine Sprachunterstützung. Benutzer können den Prozess wie folgt starten:

  • Wenn sie den Skill in der App zum ersten Mal aktivieren
  • Nachdem sie eine Anforderung geäußert haben, für die eine Authentifizierung erforderlich ist. In diesem Fall gibt Ihr Skill eine LinkAccount-Karte zurück und der Benutzer kann den Prozess von der Karte in der Alexa App beginnen. Beachten Sie, dass dieses Szenario für benutzerdefinierte Skills möglich ist, nicht aber für Smart Home Skills.

Welcher Ablauf genau erfolgt, hängt davon ab, ob Sie die implizite Erteilung („implicit grant“) oder die Erteilung über Autorisierungscode („authorization code grant“) verwenden. Für den Endbenutzer sind aber die Schritte in beiden Fällen gleich.

Der Ablauf für die Kontoverknüpfung bei der Erteilung durch Autorisierungscode (bei Smart Home Skills und benutzerdefinierten Skills):

  1. Der Benutzer aktiviert den Skill in der Alexa App.
  2. Die Alexa App zeigt Ihre Anmeldeseite direkt in der App und verwendet dazu die Autorisierungs-URL, die Sie bei der Registrierung Ihres Skills im Entwicklerportal bereitgestellt haben. Wenn die App diese URL aufruft, übergibt sie die Informationen state, client_id, response_type und scope als Abfrage-Zeichenfolgeparameter.
    • Der Parameter state wird vom Alexa-Dienst während des Vorgangs der Kontoverknüpfung verwendet. Ihre Seite muss diesen Wert registrieren, weil Sie ihn später zurückgeben müssen.
    • Der Parameter client_id ist ein von Ihnen definierter Wert, wenn Sie die Kontoverknüpfung für den Skill im Entwicklerportal einrichten.
    • Der Parameter response_type ist immer code für den Ablauf für die Erteilung durch Code.
    • Der Parameter scope ist eine optionale Liste von Werten für den Zugriffsumfang, der die angeforderte Stufe des Zugriffs angibt. Sie definieren die Werte für den gewünschten Zugriffsumfang, wenn Sie die Kontoverknüpfung für Ihren Skill aktivieren.
  3. Der Benutzer meldet sich mit seinen normalen Anmeldedaten für Ihre Website an.
  4. Ihr Service authentifiziert den Benutzer und generiert dann einen code.
  5. Ihr Dienst leitet den Benutzer auf eine für Amazon spezifische URL um und übergibt die Parameter state und code in den URL-Abfrageparametern.
  6. Der Alexa-Dienst validiert die zurückgegebenen Informationen und verwendet dann den Parameter code, um ein Token-Paar für Zugriffsberechtigung und Erneuerung von Ihrem Authentifizierungsserver anzufordern (der im Access Token URI-Feld im Entwicklerportal festgelegt wurde). Beide Elemente werden für den Alexa-Benutzer gespeichert.
  7. Das Alexa-Konto des Benutzers ist nun mit dem Konto in Ihrem Dienst verknüpft und der Skill kann benutzt werden.

Ablauf der Kontoverknüpfung für die implizite Erteilung (für benutzerdefinierte Skills):

  1. Der Benutzer aktiviert den Skill in der Alexa App.
  2. Die Alexa App zeigt Ihre Anmeldeseite direkt in der App und verwendet dazu die Autorisierungs-URL, die Sie bei der Registrierung Ihres Skills im Entwicklerportal bereitgestellt haben. Wenn die App diese URL aufruft, übergibt sie die Informationen state, client_id, response_type und scope als Abfrage-Zeichenfolgeparameter.
    • Der Parameter state wird vom Alexa-Dienst während des Vorgangs der Kontoverknüpfung verwendet. Ihre Seite muss diesen Wert registrieren, weil Sie ihn später zurückgeben müssen.
    • Der Parameter client_id ist ein von Ihnen definierter Wert, wenn Sie die Kontoverknüpfung für den Skill im Entwicklerportal einrichten.
    • Der Parameter response_type ist immer token für den Ablauf für die implizite Erteilung.
    • Der Parameter scope ist eine optionale Liste von Werten für den Zugriffsumfang, der die angeforderte Stufe des Zugriffs angibt. Sie definieren die Werte für den gewünschten Zugriffsumfang, wenn Sie die Kontoverknüpfung für Ihren Skill aktivieren.
  3. Der Benutzer meldet sich mit seinen normalen Anmeldedaten für Ihre Website an.
  4. Ihr Dienst authentifiziert den Benutzer und generiert einen Zugriffstoken, der den Benutzer in Ihrem System eindeutig identifiziert.
  5. Ihr Dienst leitet den Benutzer auf eine für Amazon spezifische URL um und übergibt die Parameter state, access_token und token_type im URL-Fragment.
  6. Der Alexa-Dienst validiert die zurückgegebenen Informationen und speichert den access_token für den Alexa-Benutzer.
  7. Das Alexa-Konto des Benutzers ist nun mit dem Konto in Ihrem Dienst verknüpft und der Skill kann benutzt werden.

Ablauf beim Aufruf eines Skills mit Kontoverknüpfung durch den Benutzer

Wenn ein Benutzer die Interaktion mit einem benutzerdefinierten Skill beginnt, der mit Kontoverknüpfung eingerichtet wurde, entsteht folgender Ablauf:

  1. Der Benutzer ruft den Skill normal auf. Zum Beispiel: „Alexa, bestelle bei Mitfahrdienst ein Taxi für mich.“
  2. Wenn Sie die Erteilung durch Autorisierungscode verwenden, stellt der Alexa-Dienst sicher, dass der Zugriffstoken, der für den Benutzer gespeichert wurde, weiterhin gültig ist. Sollte er abgelaufen sein, verwendet der Alexa-Dienst den Erneuerungstoken, um einen neuen Zugriffstoken von Ihrem Autorisierungsserver anzufordern.
  3. Der LaunchRequest- oder IntentRequest-Befehl, der an den Dienst für Ihren Skill abgesendet wird, enthält den zuvor gespeicherten Zugriffstoken für den Benutzer.
  4. Ihr Service überprüft, ob der Token mit einem Benutzer in Ihrem System übereinstimmt.

    • Wenn der Token für einen Benutzer gültig ist, greift Ihr Dienst im erforderlichen Ausmaß auf die Benutzerdaten zu, führt die Anforderung normal durch und sendet eine entsprechende Antwort mit dem Text zurück, der für den Benutzer gesprochen werden muss, sowie eine optionale Karte, die in der Alexa App angezeigt werden kann.

      Im Mitfahrdienst-Beispiel überprüft der Mitfahrdienst-Skill, dass der bereitgestellte Token einem gültigen Mitfahrdienst-Benutzer entspricht. Wenn dies der Fall ist, kann der Dienst auf das Mitfahrdienst-Profil für diesen Benutzer zugreifen und diese Informationen verwenden, um die Benutzeranforderung für ein Taxi durchzuführen.

    • Wenn der Token ungültig ist, gibt Ihr Dienst einen Text zurück, der den Benutzer auffordert, sein Konto zu verknüpfen. Dazu wird eine LinkAccount-Karte übermittelt. Der Benutzer kann auf den Link auf dieser Karte klicken, um den Vorgang für die Kontoverknüpfung zu starten:

      Beispiel für eine LinkAccount-Karte
      Beispiel für eine LinkAccount-Karte

Der Vorgang ist bei Smart Home Skills ähnlich:

  1. Der Benutzer ruft den Skill normal auf. Zum Beispiel: „Alexa, schalte das Licht im Wohnzimmer ein.“
  2. Der Alexa-Dienst stellt sicher, dass der Zugriffstoken, der für den Benutzer gespeichert wurde, weiterhin gültig ist. Sollte es abgelaufen sein, verwende den Alexa-Dienst Erneuerungstoken, um einen neuen Zugriffstoken von Ihrem Autorisierungsserver anzufordern.
  3. Die Geräteanweisung, die an Ihren Skill-Adapter gesendet wird, enthält den zuvor gespeicherten Zugriffstoken in der payload.
  4. Ihr Skill-Adapter übergibt den Token an die Geräte-Cloud, um die Benutzeranforderung durchzuführen.
    • Wenn der Token gültig ist, führt die Geräte-Cloud die Anforderung normal durch und aktiviert die erforderlichen Beleuchtungskörper.
    • Wenn der Token ungültig ist, muss Ihr Skill-Adapter DependentServiceUnavailableError zurückgeben. Alexa teilt danach dem Benutzer mit, dass sie die Anforderung nicht durchführen konnte.

Weitere Informationen über Geräteanweisungen finden Sie in der Smart Home Skill API-Referenz.

Ablauf beim Deaktivieren eines Skills mit Kontoverknüpfung durch den Benutzer

Wenn der Benutzer den Skill in der Alexa App deaktiviert, löscht der Alexa-Dienst den Zugriffstoken (und den Erneuerungstoken, falls vorhanden), der mit diesem Benutzer und dem Skill verbunden ist. Damit wird die Verknüpfung zwischen dem Alexa-Konto des Benutzers und seinem Konto in Ihrem Dienst entfernt.

Wenn der Benutzer später den Skill wieder aktiviert, muss er den Prozess der Kontoverknüpfung als neuer Benutzer erneut durchführen.

Anforderungen für das Hinzufügen der Kontoverknüpfung zu Ihrem Skill

Für die Kontoverknüpfung in einem Skill sind folgende Voraussetzungen zu erfüllen:

Authorization Code Grant (Erteilung durch Autorisierungscode) Implicit Grant (implizite Erteilung)
Webbasierter Dienst, der Benutzer authentifiziert Webbasierter Dienst, der Benutzer authentifiziert
Autorisierungsserver, der eine Anmeldeseite anzeigen kann, um die Anmeldedaten des Benutzers aufzunehmen, den Benutzer zu autorisieren und danach einen Autorisierungscode zu erstellen. Autorisierungsserver, der eine Anmeldeseite anzeigen kann, um die Anmeldedaten des Benutzers aufzunehmen, den Benutzer zu autorisieren und danach einen Autorisierungscode zu erstellen, der den Benutzer eindeutig identifiziert.
Autorisierungsserver, der den Autorisierungscode und die Anmeldedaten des Alexa-Clients akzeptiert und einen Zugriffstoken erstellt, der den Benutzer eindeutig identifiziert.

Für die Kontoverknüpfung in einem Skill gehen Sie wie folgt vor:

  1. Fügen Sie die Unterstützung für die Kontoverknüpfung der Anmeldeseite für Ihren Dienst hinzu.
  2. Fügen Sie die Logik für die Kontoverknüpfung dem cloudbasierten Dienst für Ihren Skill hinzu (Webdienst oder Lambda-Funktion).
  3. Aktivieren Sie die Kontoverknüpfung für Ihren Skill im Entwicklerportal.

In den nachfolgenden Abschnitten finden Sie Details zu diesen Schritten.

Hinzufügen der Unterstützung für die Kontoverknüpfung zu Ihrer Anmeldeseite (Autorisierungs-URL)

Wenn ein Benutzer den Vorgang zur Kontoverknüpfung startet, zeigt die Alexa App eine Anmeldeseite für Ihren Ressourcenserver an. Sie müssen eine Seite erstellen und programmieren, die für diesen Zweck geeignet ist. Die Seite muss die Anmeldedaten des Benutzers verifizieren und dann entweder einen Zugriffstoken oder einen Autorisierungscode zurückgeben.

Die URL für diese Seite übergeben Sie im Feld Autorisierungs-URL, wenn Sie die Kontoverknüpfung für Ihren Skill im Entwicklerportal aktivieren.

An die Autorisierungs-URL übergebene Parameter

Die Alexa App enthält folgende Parameter in der URL-Abfragezeichenfolge, wenn sie Ihre Autorisierungs-URL abruft:

  • Der Parameter state wird vom Alexa-Dienst während des Vorgangs der Kontoverknüpfung verwendet.
    • Ihre Seite muss diesen Wert (unverändert) zurückgeben, wenn die umgeleitete URL aufgerufen wird.
    • Dieser Wert läuft nach 5 Minuten ab. Wenn es länger als 5 Minuten dauert, den Benutzer anzumelden und weiterzuleiten, wird der Parameter state ungültig und der Vorgang zu Kontoverknüpfung schlägt fehl. In diesem Fall muss der Benutzer erneut beginnen, indem er auf den Link in der Alexa App tippt.
  • Der Parameter client_id ist eine von Ihnen erstellte Kennung. Sie können sie verwenden, um skillspezifische Funktionalitäten bereitzustellen, beispielsweise die Unterscheidung zwischen verschiedenen Skills, die Sie mit Kontoverknüpfung erstellt haben. Sie definieren Ihre client_id, wenn Sie die Kontoverknüpfung für Ihren Skill im Entwicklerportal einrichten.
  • Der Wert response_type hängt davon ab, ob Sie eine Erteilung durch Autorisierungscode oder eine implizite Erteilung verwenden.
    • code für die Erteilung durch Autorisierungscode
    • token für implizite Erteilung
  • Der Parameter scope ist eine optionale Liste von Werten für den Zugriffsumfang, der die angeforderte Stufe des Zugriffs angibt. Sie definieren diesen Zugriffsumfang, wenn Sie die Kontoverknüpfung für Ihren Skill im Entwicklerportal einrichten.
    • Sie können diese Informationen verwenden, wenn Sie den Zugriffstoken erstellen. Beispiel: Sie können einen Token erstellen, der den Zugriff auf einfache Profilinformationen in Ihrem Ressourcenserver zulässt, nicht aber auf Zahlungsinformationen.
    • Es können mehrere Ebenen für den Zugriffsumfang definiert werden. Die Liste wird gemäß URL-Codierung begrenzt.
    • Sie können auch den Benutzern mitteilen, welchen Zugriff sie erlauben, indem sie die Kontoverknüpfung durchführen. Beispiel: Ihre Anmeldeseite kann den Text „Der Mitfahrdienst-Skill kann in Ihrem Namen ein Taxi buchen und Ihr Konto mit den Kosten belasten“ anzeigen.

Beispiel: Wenn die Autorisierungs-URL für Ihre Seite https://www.Mitfahrdienst.de/login ist, kann die von der Alexa App aufgerufene URL so aussehen (bei Erteilung durch Autorisierungscode):

https://www.carfu.com/login?state=abc&client_id=alexa-skill&scope=order_car basic_profile&response_type=code

Anforderungen für Ihre Anmeldeseite

Ihre Anmeldeseite muss folgende Anforderungen erfüllen:

  • Sie muss über HTTPS laufen.
  • Sie muss für Mobilgeräte angepasst sein, weil sie in der Alexa App angezeigt wird.
  • Die Seite kann keine anderen Pop-up-Fenster aufmachen.
  • Sie muss die Anmeldedaten des Benutzers entgegennehmen und danach den Benutzer authentifizieren.
  • Sie muss folgende Optionen erlauben:
    • Generieren eines Zugriffstokens, der den Benutzer für Ihren Ressourcenserver eindeutig identifiziert
    • Generieren eines Autorisierungscodes, der an Ihren Autorisierungsserver weitergegeben werden kann, damit dieser einen Zugriffstoken abruft
  • Sie muss den state-Wert verfolgen, der in der Abfragezeichenfolge übergeben wird.
  • Nachdem der Benutzer authentifiziert wurde, muss die Seite den Benutzer auf eine von Amazon bereitgestellte Weiterleitungs-URL weiterleiten.
    • Die von Ihnen verwendete Weiterleitungs-URL wird im Entwicklerportal angezeigt, wenn Sie die Kontoverknüpfungsoptionen für Ihren Skill aktivieren.
    • Bei der Erteilung durch Autorisierungscode schließen Sie die Parameter state und code in die URL-Abfragezeichenfolge ein.
    • Bei der implizierten Erteilung schließen Sie die Parameter state, access_token und token_type in das URL-Fragment ein. Der token_type muss Bearer lauten.

Als Beispiel nehmen Sie die folgende, von Amazon bereitgestellte Weiterleitungs-URL her:

https://pitangui.amazon.com/spa/skill/account-linking-status.html?vendorId=AAAAAAAAAAAAAA

Für die Erteilung durch Autorisierungscode kann die Weiterleitungs-URL wie folgt aussehen:

https://pitangui.amazon.com/spa/skill/account-linking-status.html?vendorId=AAAAAAAAAAAAAA&state=xyz&code=SplxlOBeZQQYbYS6WxSbIA

Die Parameter, die Sie zurückgeben müssen (state und code), befinden sich im Abfragezeichenfolge-Teil der URL.

Für die implizite Erteilung kann die Weiterleitungs-URL wie folgt aussehen:

https://pitangui.amazon.com/spa/skill/account-linking-status.html?vendorId=AAAAAAAAAAAAAA#state=xyz&access_token=2YotnFZFEjr1zCsicMWpAA&token_type=Bearer

Die Parameter, die Sie zurückgeben müssen (state, access_token und token_type), befinden sich im URL-Fragment-Teil der URL. Dies ist der Teil nach dem Hashtag (#).

Hinweise zu Zugriffstoken und Erneuerungstoken

Ihr Dienst authentifiziert den Benutzer und generiert einen Zugriffstoken, der den Benutzer in Ihrem System eindeutig identifiziert.

Für die Erteilung durch Autorisierungscode ruft der Alexa-Dienst Ihren Autorisierungsserver (angegeben als Access Token URI im Entwicklerportal) auf und übergibt den Parameter code sowie die Client-Anmeldedaten. Der Autorisierungsserver muss den Zugriffstoken und einen optionalen Erneuerungstoken zurückgeben. Obwohl der Erneuerungstoken optional ist, wird er für den Fall empfohlen, dass der Zugriffstoken erlischt. Der Alexa-Dienst kann den Erneuerungstoken verwenden, um einen neuen Zugriffstoken zu erhalten, sobald der vorherige abgelaufen ist, ohne dass der Endbenutzer damit belästigt werden muss.

Bei der impliziten Erteilung enthält Ihre Anmeldeseite den Zugriffstoken, wenn die Weiterleitungs-URL aufgerufen wird, wie im obigen Beispiel einer Weiterleitungs-URI gezeigt. Die implizite Erteilung unterstützt keine Erneuerungstoken. Wenn der Zugriffstoken abläuft, muss der Benutzer die Konten erneut verknüpfen. Wenn Sie abgelaufene Token erneut verwenden möchten, verwenden Sie anstelle dessen die Erteilung mit Autorisierungscode.

Für beide Typen gilt: Wenn der Zugriffstoken generiert wird, müssen Sie einen für Ihren Ressourcenserver spezifischen Token bereitstellen. Verwenden Sie keine Zugriffstoken, die von anderen OAuth-Anbietern wie Google oder Facebook bereitgestellt werden. Aus Sicherheitsgründen sollte Ihr Token ein Wert sein, der den Benutzer identifiziert, aber nicht erraten werden kann.

Hinzufügen der Logik für die Kontoverknüpfung zum Dienst für Ihren Skill

Um Ihrem Skill die Kontoverknüpfung hinzuzufügen, muss die Logik Ihres Skills entsprechend programmiert werden, den Zugriffstoken in den Anforderungen zu prüfen und zu verwenden, der an Ihren Skill gesendet wird.

Abrufen des Zugriffstokens aus der Anforderung (benutzerdefinierte Skills)

Bei Verwendung einer Java-Bibliothek ist der Zugriffstoken im Session-Objekt verfügbar, das an die Methoden onIntent(), onLaunch() und onSessionEnded() übergeben wird. Sie können die Methode Session.getUser() verwenden, um einen User abzurufen, und verwenden dann User.getAccessToken(), um den Token zu erhalten.

Im JSON-Code ist der Zugriffstoken in der accessToken-Eigenschaft des user-Objekts in der Anforderung verfügbar:

{
  "version": "string",
  "session": {
    "new": boolean,
    "sessionId": "string",
    "application": {
      "applicationId": "string"
    },
    "attributes": {
      "string": object
    },
    "user": {
      "userId": "string",
      "accessToken": "string"
    }
  },
  "request": object
}

Abrufen des Zugriffstokens aus der Anforderung (Smart Home Skills)

Der Zugriffstoken wird als Teil der Geräteanweisung in der accessToken-Eigenschaft des payload-Objekts an Ihren Skill-Adapter übergeben.

Als Beispiel sehen Sie sich diese DiscoverAppliancesRequest-Anweisung an:

{
  "header": {
    "namespace": "Alexa.ConnectedHome.Discovery",
    "name": "DiscoverAppliancesRequest",
    "payloadVersion": "2",
    "messageId": "6d6d6e14-8aee-473e-8c24-0d31ff9c17a2"
  },
  "payload": {
    "accessToken": "string"
  }
}

Validieren des Zugriffstokens

Bei einer Anforderung, die Authentifizierung erfordert, muss Ihr Programmcode mindestens zwei Prüfungen durchführen:

  1. Er muss bestätigen, dass accessToken vorhanden ist (nur benutzerdefinierte Skills).

    In der Java-Bibliothek gibt User.getAccessToken() den Wert null zurück, wenn der Benutzer die Kontoverknüpfung nicht erfolgreich durchführen konnte.

    Im JSON-Code existiert die Eigenschaft accessToken nicht, wenn der Benutzer sein Konto nicht verknüpft hat.

    Beachten Sie, dass diese Prüfung auf Smart Home Skills nicht anzuwenden ist. Es ist nicht möglich, einen Smart Home Skill ohne erfolgreiche Verknüpfung der Konten zu aktivieren.

  2. Wenn die Eigenschaft accessToken vorhanden ist, muss überprüft werden, ob sie gültig ist und einen Benutzer im Ressourcenserver identifiziert. Ein bestehender Token kann aus mehreren Gründen ungültig werden, beispielsweise:

    • Der Benutzer hat sein Konto bei Ihrem Dienst gelöscht oder storniert. Beispiel: ein Alexa-Benutzer hat eine Kontoverknüpfung mit „Mitfahrdienst“ eingerichtet und danach sein Mitfahrdienst-Konto gelöscht. Der vom Alexa-Dienst gespeicherte Token würde zu diesem Zeitpunkt einen nicht existierenden Benutzer identifizieren.
    • Der Token ist abgelaufen und der Alexa-Dienst konnte keinen neuen Token erwerben. Dies kann vorkommen, wenn die Erteilung durch Autorisierungscode verwendet wird und Ihr Server keine Erneuerungstoken bereitstellt. Es kann auch vorkommen, wenn Sie die Autorisierung durch implizite Erteilung verwenden, bei der keine Erneuerungstoken unterstützt werden.

Wenn der Token gültig ist, kann der Skill die Anforderung normal abwickeln und gegebenenfalls Daten von Ihrem Ressourcenserver abrufen. Im Mitfahrdienst-Beispiel würde der Skill Profil- und Zahlungsinformationen für den Benutzer aus dem Mitfahrdienst-Dienst abrufen, ein Taxi bestellen und die Bestätigung an den Benutzer zurückgeben. Weitere Informationen zur Rückgabe von Antworten finden Sie im Abschnitt Verarbeitung der von Alexa gesendeten Anforderungen.

Antworten bei einem ungültigen Zugriffstoken (Smart Home Skills)

Wenn der an Ihren Skill-Adapter für einen Smart Home Skill gesendete Zugriffstoken ungültig ist, geben Sie DependentServiceUnavailableError zurück. Alexa teilt danach dem Benutzer mit, dass sie die Anforderung nicht durchführen konnte.

Antworten bei einem ungültigen oder nicht existierenden Zugriffstoken (benutzerdefinierte Skills)

Wenn der an Ihren benutzerdefinierten Skill gesendete Zugriffstoken nicht existiert oder ungültig ist, muss Ihr Skill eine Antwort zurückgeben, die folgende Informationen enthält:

  • Text für die Sprachausgabe, in dem dem Benutzer erklärt wird, dass er seine Konten verknüpfen muss, um diese Funktion verwenden zu können.
  • Eine Karte für die Kontoverknüpfung. Dabei handelt es sich um einen speziellen Kartentyp, auf dem der Benutzer aufgefordert wird, sein Konto zu verknüpfen. Wenn die Karte in der Alexa App angezeigt wird, enthält sie einen Link zur URL mit Ihrer Anmeldeseite. Der Benutzer kann den Prozess zur Kontoverknüpfung direkt von dieser Karte starten.

So wird eine Karte für die Kontoverknüpfung gesendet:

  • Wenn Sie die Java-Bibliothek verwenden, erstellen Sie eine Instanz der LinkAccountCard-Klasse und fügen sie in Ihrer Antwort in die Karte ein.
  • Bei der Verwendung von JSON setzen Sie den Parameter type für die Karte auf LinkAccount:

     {
         "version": "1.0",
         "sessionAttributes": {
           ...(session attributes not shown)
         },
         "response": {
           "outputSpeech": {
             "type": "PlainText",
             "text": "You must have a Car-Fu account to use this skill. Please use the Alexa app to link your Amazon account with your Car-Fu Account."
           },
           "card": {
             "type": "LinkAccount"
           },
           "shouldEndSession": true
         }
     }
    

In den meisten Fällen wird durch diese Antwort die Sitzung beendet, da der Benutzer mit seiner Anforderung erst fortfahren kann, nachdem er sein Konto verknüpft hat. Wenn Ihr Skill Absichten enthält, die keine Authentifizierung erfordern, kann es sinnvoll sein, dem Benutzer eine andere Frage zu stellen und die Sitzung offen zu lassen.

Anforderung eines gültigen Zugriffstokens

Ihr Dienst muss accessToken für jede Anforderung validieren, bei der sich Ihr Benutzer bei Ihrer Website authentifizieren muss.

Bei einem Smart Home Skill umfasst dies jede Anweisung.

Bei einem benutzerdefinierten Skill umfasst dies in der Regel die meisten Absichten, aber es kann Absichten geben, für die keine Authentifizierung erforderlich ist. Zum Beispiel könnte der benutzerdefinierte Skill Mitfahrdienst Benutzerauthentifizierung erfordern, um ein Auto zu bestellen, aber keine Authentifizierung erfordern, um nur zu fragen, ob der Dienst in einer bestimmten Stadt zur Verfügung steht.Der Code für diesen Skill kann daher wie folgt aussehen:

  • Der Handler für die Absicht OrderTaxi prüft das Vorhandensein eines gültigen accessToken und verwendet diesen Token, um das Mitfahrdienst-Profil des Benutzers abzurufen und ein Taxi zu bestellen.
  • Der Handler für eine allgemeine TaxiAvailabilityByCity-Absicht muss das Vorhandensein eines accessToken nicht prüfen, sondern sucht nach öffentlichen Informationen im Mitfahrdienst-Dienst und gibt eine Antwort zurück.

Aktivieren der Kontoverknüpfung für einen Skill im Entwicklerportal

Sie aktivieren die Kontoverknüpfung auf der Seite Configuration im Amazon-Entwicklerportal.

Nachdem Sie Ihren Skill im Portal registriert haben, navigieren Sie zur Seite Configuration und wählen Yes für Account Linking or Creation. Beachten Sie, dass diese Option für Smart Skills nicht angezeigt wird, da die Kontoverknüpfung immer erforderlich ist.

Sie müssen zumindest folgende Informationen eingeben, um die Kontoverknüpfung zu aktivieren:

  • Autorisierungs-URL: Die URL der Anmeldeseite für Ihre Website. Unter dem Thema Hinzufügen der Unterstützung für die Kontoverknüpfung zu Ihrer Anmeldeseite finden Sie Informationen darüber, wie diese Seite verwendet wird, wenn Benutzer ihre Konten verknüpfen.
  • Client ID (client_id): Diese Kennung wird von Ihrer Anmeldeseite verwendet, um zu erkennen, dass die Anforderung von Ihrem Skill kommt. Dieser Wert wird im Parameter client_id an Ihre Autorisierungs-URL übergeben. Wenn Sie die Erteilung durch Autorisierungscode verwenden, ist dieser Wert auch Teil der Client-Anmeldedaten, die der Alexa-Dienst in die Anforderung eines Zugriffstokens aus der Access Token URI einschließt.
  • Authorization Code Grant (Erteilung durch Autorisierungscode) Der Typ der Autorisierungserteilung nach OAuth 2.0, um einen Zugriffstoken zu erhalten. Das Alexa Skills Kit unterstützt zwei Erteilungstypen:
  • Für die Erteilung durch Autorisierungscode (Authorization Code Grant) müssen Sie Folgendes eintragen:
    • Access Token URI: Die URL für den Autorisierungsserver, der die Zugriffstoken bereitstellt.
    • Client-Geheimnis: Anmeldedaten, die Sie übergeben und mit denen der Alexa-Dienst die Authentifizierung anhand der Access Token URI durchführen kann. Dies wird mit der Client-ID abgeglichen, um zu bestätigen, dass die Anforderung von Alexa kommt.
    • Client Authentication Scheme identifiziert den Authentifizierungstyp, den Alexa verwenden muss, wenn Token von der Access Token URI abgerufen werden.
  • Datenschutzbestimmungen-URL: Eine URL zu einer Seite mit Ihren Datenschutzbestimmungen. Der Link wird in der Alexa App angezeigt. Dies ist für Skills erforderlich, die eine Kontoverknüpfung verwenden. Beachten Sie, dass die von Ihnen eingegebene URL im Feld Privacy Policy URL auf der Seite Privacy & Compliance angezeigt wird.

Wenn Ihre Anmeldeseite Inhalte von anderen Domänen abruft, geben Sie diese in Domainliste ein. Dies ist nur für Domänen außerhalb Ihrer Autorisierungs-URL nötig. Beispielsweise wenn Ihre Autorisierungs-URL https://www.Mitfahrdienstde/login ist. Wenn Ihre Seite Inhalte abruft (beispielsweise Bilder), die auf anderen Domänen als www.Mitfahrdienst.de liegen, können Sie sie in die Domainliste einfügen.

Wenn Ihr Ressourcenserver verschiedene Zugriffsebenen unterstützt, geben Sie diese in der Liste Scope ein. Alle hier eingegebenen Zugriffsebenen werden in den scope-Parameter einbezogen, wenn die Alexa App Ihre Autorisierungs-URL abruft.

Durch das Aktivieren der Kontoverknüpfung wird Ihre Weiterleitungs-URL angezeigt. Dies ist die URL, auf die Ihre Anmeldeseite den Benutzer umleiten muss, nachdem er authentifiziert wurde. Die Parameter, die die Seite in die Weiterleitung-URI aufnehmen muss, hängen davon ab, ob Sie die Erteilung durch Autorisierungscode oder die implizite Erteilung verwenden. Weitere Hinweise finden Sie unter Anforderungen für Ihre Anmeldeseite.

Nächste Schritte

Coding-Themen (benutzerdefinierte Skills):

Andere Themen:

Referenzmaterial: