Deine Alexa Dashboards Einstellungen

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: