Authentifizierung mit der Bot Connector-API

Ihr Bot kommuniziert mit dem Bot Connector-Dienst über HTTP über einen gesicherten Kanal (SSL/TLS). Wenn Ihr Bot eine Anforderung an den Connectordienst sendet, muss er Informationen enthalten, die der Connectordienst verwenden kann, um seine Identität zu überprüfen. Ebenso muss der Connector-Dienst, wenn er eine Anfrage an Ihren Bot sendet, Informationen übermitteln, die der Bot zur Überprüfung seiner Identität verwenden kann. In diesem Artikel werden die Authentifizierungstechnologien und -anforderungen für die Authentifizierung auf Dienstebene beschrieben, die zwischen einem Bot und dem Bot Connector-Dienst stattfindet. Wenn Sie Ihren eigenen Authentifizierungscode schreiben, müssen Sie die in diesem Artikel beschriebenen Sicherheitsverfahren implementieren, damit Ihr Bot Nachrichten mit dem Bot Connector-Dienst austauschen kann.

Wenn Sie das Bot Framework SDK verwenden, müssen Sie die in diesem Artikel beschriebenen Sicherheitsverfahren nicht implementieren, da es vom SDK automatisch für Sie ausgeführt wird. Konfigurieren Sie Ihr Projekt einfach mit der App-ID und dem Kennwort, die Sie während der Registrierung für Ihren Bot erhalten haben, und das SDK behandelt den Rest.

Authentifizierungstechnologien

Vier Authentifizierungstechnologien werden verwendet, um eine Vertrauensstellung zwischen einem Bot und dem Bot Connector herzustellen:

In diesem Artikel wird beschrieben, wie Sie diese Technologien über standard HTTPS und JSON verwenden. Es sind keine speziellen SDKs erforderlich, obwohl Sie möglicherweise feststellen, dass Hilfsprogramme für OpenID und andere hilfreich sind.

Anfragen Ihres Bots beim Bot Connector-Dienst authentifizieren

Um mit dem Bot Connector-Dienst zu kommunizieren, müssen Sie mithilfe dieses Formats ein Zugriffstoken im Authorization Header jeder API-Anforderung angeben:

Authorization: Bearer ACCESS_TOKEN

So rufen Sie ein JWT-Token für Ihren Bot ab und verwenden es:

1. Ihr Bot sendet eine GET-HTTP-Anforderung an den MSA-Anmeldedienst.
2. Die Antwort des Diensts enthält das zu verwendende JWT-Token.
3. Ihr Bot fügt dieses JWT-Token im Autorisierungsheader in Anfragen an den Bot Connector-Dienst ein.

Schritt 1: Anfordern eines Zugriffstokens vom Microsoft Entra ID Kontoanmeldungsdienst

Ihre Botidentität kann in Azure auf verschiedene Arten verwaltet werden.

• Als vom Benutzer zugewiesene verwaltete Identität, sodass Sie die Anmeldeinformationen des Bots nicht selbst verwalten müssen.
• Als einzelinstanzfähige Anwendung.
• Als mehrinstanzfähige Anwendung.

Fordern Sie ein Zugriffstoken basierend auf dem Anwendungstyp Ihres Bots an.

POST https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=MICROSOFT-APP-ID&client_secret=MICROSOFT-APP-PASSWORD&scope=https%3A%2F%2Fapi.botframework.com%2F.default

POST https://login.microsoftonline.com/MICROSOFT-TENANT-ID/oauth2/v2.0/token
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=MICROSOFT-APP-ID&client_secret=MICROSOFT-APP-PASSWORD&scope=https%3A%2F%2Fapi.botframework.com%2F.default

Schritt 2: Abrufen des JWT-Tokens aus der Antwort des Microsoft Entra ID Kontoanmeldungsdiensts

Wenn Ihre Anwendung vom Anmeldedienst autorisiert ist, gibt der JSON-Antworttext Ihr Zugriffstoken, seinen Typ und seinen Ablauf (in Sekunden) an.

Wenn Sie das Token dem Authorization-Header einer Anfrage hinzufügen, müssen Sie genau den Wert verwenden, der in dieser Antwort angegeben ist – escapen oder kodieren Sie den Tokenwert nicht. Das Zugriffstoken ist bis zum Ablauf gültig. Um zu verhindern, dass sich der Ablauf des Tokens auf die Leistung Ihres Bots auswirkt, können Sie das Token zwischenspeichern und proaktiv aktualisieren.

Dieses Beispiel zeigt eine Antwort des Microsoft Entra ID Kontoanmeldungsdiensts:

HTTP/1.1 200 OK
... (other headers)

{
    "token_type":"Bearer",
    "expires_in":3600,
    "ext_expires_in":3600,
    "access_token":"eyJhbGciOiJIUzI1Ni..."
}

Schritt 3: Geben Sie das JWT-Token im Authorization-Header der Anfragen an

Wenn Sie eine API-Anforderung an den Bot Connector-Dienst senden, geben Sie das Zugriffstoken im Authorization Header der Anforderung mit diesem Format an:

Authorization: Bearer ACCESS_TOKEN

Alle Anforderungen, die Sie an den Bot Connector-Dienst senden, müssen das Zugriffstoken im Authorization Header enthalten. Wenn das Token richtig gebildet ist, nicht abgelaufen ist und vom Microsoft Entra ID Kontoanmeldungsdienst generiert wurde, autorisiert der Bot Connector-Dienst die Anforderung. Zusätzliche Überprüfungen werden durchgeführt, um sicherzustellen, dass das Token zum Bot gehört, der die Anforderung gesendet hat.

Das folgende Beispiel zeigt, wie das Zugriffstoken im Authorization Header der Anforderung angegeben wird.

POST https://smba.trafficmanager.net/teams/v3/conversations/12345/activities
Authorization: Bearer eyJhbGciOiJIUzI1Ni...

(JSON-serialized Activity message goes here)

Bot an Connector: Beispiel für JWT-Komponenten

header:
{
  typ: "JWT",
  alg: "RS256",
  x5t: "<SIGNING KEY ID>",
  kid: "<SIGNING KEY ID>"
},
payload:
{
  aud: "https://api.botframework.com",
  iss: "https://sts.windows.net/d6d49420-f39b-4df7-a1dc-d59a935871db/",
  nbf: 1481049243,
  exp: 1481053143,
  appid: "<YOUR MICROSOFT APP ID>",
  ... other fields follow
}

Authentifizieren von Anfragen des Bot Connector-Diensts an Ihren Bot

Wenn der Bot Connector-Dienst eine Anforderung an Ihren Bot sendet, gibt er ein signiertes JWT-Token im Authorization Header der Anforderung an. Ihr Bot kann Anrufe vom Bot Connector-Dienst authentifizieren, indem die Echtheit des signierten JWT-Tokens überprüft wird.

So authentifizieren Sie Anrufe vom Bot Connector-Dienst:

1. Ihr Bot bezieht das JWT-Token aus dem Autorisierungsheader in Anfragen, die vom Bot Connector-Dienst gesendet werden.
2. Ihr Bot ruft das OpenID-Metadatendokument für den Bot Connector-Dienst ab.
3. Ihr Bot ruft die Liste der gültigen Signaturschlüssel aus dem Dokument ab.
4. Ihr Bot überprüft die Authentizität des JWT-Tokens.

Schritt 2: Abrufen des OpenID-Metadatendokuments

Das OpenID-Metadatendokument gibt den Speicherort eines zweiten Dokuments an, in dem die gültigen Signaturschlüssel des Bot Connector-Diensts aufgelistet sind. Um das OpenID-Metadatendokument abzurufen, stellen Sie diese Anforderung über HTTPS aus:

GET https://login.botframework.com/v1/.well-known/openidconfiguration

Das folgende Beispiel zeigt ein OpenID-Metadatendokument, das als Antwort auf die GET Anforderung zurückgegeben wird. Die jwks_uri Eigenschaft gibt den Speicherort des Dokuments an, das die gültigen Signaturschlüssel des Bot Connector-Diensts enthält.

{
    "issuer": "https://api.botframework.com",
    "authorization_endpoint": "https://invalid.botframework.com",
    "jwks_uri": "https://login.botframework.com/v1/.well-known/keys",
    "id_token_signing_alg_values_supported": [
      "RS256"
    ],
    "token_endpoint_auth_methods_supported": [
      "private_key_jwt"
    ]
}

Schritt 3: Abrufen der Liste der gültigen Signaturschlüssel

Um die Liste der gültigen Signaturschlüssel abzurufen, geben Sie eine GET Anforderung über HTTPS an die url aus, die von der jwks_uri Eigenschaft im OpenID-Metadatendokument angegeben wurde. Beispiel:

GET https://login.botframework.com/v1/.well-known/keys

Der Antworttext gibt das Dokument im JWK-Format an, enthält aber auch eine zusätzliche Eigenschaft für jeden Schlüssel: endorsements

Die endorsements Eigenschaft innerhalb jedes Schlüssels enthält eine oder mehrere Bestätigungszeichenfolgen, mit denen Sie überprüfen können, ob die kanal-ID, die in der channelId Eigenschaft innerhalb des Activity-Objekts der eingehenden Anforderung angegeben ist, authentifiziert ist. Die Liste der Kanal-IDs, die Bestätigungen erfordern, kann in jedem Bot konfiguriert werden. Standardmäßig ist dies die Liste aller veröffentlichten Kanal-IDs, obwohl Botentwickler ausgewählte Kanal-ID-Werte auf beide Arten außer Kraft setzen können.

Schritt 4: Überprüfen des JWT-Tokens

Um die Authentizität des Tokens zu überprüfen, das vom Bot Connector-Dienst gesendet wurde, müssen Sie das Token aus dem Authorization Header der Anforderung extrahieren, das Token analysieren, dessen Inhalt überprüfen und seine Signatur überprüfen.

JWT-Analysebibliotheken sind für viele Plattformen verfügbar und implementieren die sicherste und zuverlässige Analyse für JWT-Token, obwohl Sie diese Bibliotheken in der Regel so konfigurieren müssen, dass bestimmte Merkmale des Tokens (aussteller, Zielgruppe usw.) korrekte Werte enthalten. Beim Analysieren des Tokens müssen Sie die Analysebibliothek konfigurieren oder eine eigene Überprüfung schreiben, um sicherzustellen, dass das Token diese Anforderungen erfüllt:

1. Das Token wurde im HTTP-Header Authorization im „Bearer“-Schema übermittelt.
2. Das Token ist gültiger JSON-Code, der dem JWT-Standard entspricht.
3. Das Token enthält einen "issuer"-Anspruch mit dem Wert von https://api.botframework.com.
4. Das Token enthält einen "Audience"-Anspruch mit einem Wert, der der Microsoft App-ID des Bots entspricht.
5. Das Token liegt innerhalb des Gültigkeitszeitraums. Der branchenübliche Taktversatz beträgt 5 Minuten.
6. Das Token verfügt über eine gültige kryptografische Signatur, wobei ein Schlüssel im OpenID-Schlüsseldokument aufgeführt ist, das in Schritt 3 abgerufen wurde, mithilfe des Signaturalgorithmus, der in der id_token_signing_alg_values_supported Eigenschaft des Open ID-Metadatendokuments angegeben ist, das in Schritt 2 abgerufen wurde.
7. Das Token enthält einen „serviceUrl“-Claim mit einem Wert, der mit der serviceUrl-Eigenschaft auf Stammebene des Activity-Objekts der eingehenden Anforderung übereinstimmt.

Wenn die Bestätigung für eine Kanal-ID erforderlich ist:

• Sie sollten festlegen, dass jedes Activity Objekt, das mit dieser Kanal-ID an Ihren Bot gesendet wird, von einem JWT-Token begleitet wird, das mit einer Bestätigung für diesen Kanal signiert ist.
• Wenn die Bestätigung nicht vorhanden ist, sollte Ihr Bot die Anforderung ablehnen, indem ein HTTP 403 (Verbotener) Statuscode zurückgegeben wird.

Implementierer sollten keine Möglichkeit zum Deaktivieren der Überprüfung des JWT-Tokens verfügbar machen, das an den Bot gesendet wird.

Connector zum Bot: Beispielkomponenten eines JWT

header:
{
  typ: "JWT",
  alg: "RS256",
  x5t: "<SIGNING KEY ID>",
  kid: "<SIGNING KEY ID>"
},
payload:
{
  aud: "<YOU MICROSOFT APP ID>",
  iss: "https://api.botframework.com",
  nbf: 1481049243,
  exp: 1481053143,
  ... other fields follow
}

Anfragen vom Bot Framework Emulator an Ihren Bot authentifizieren

Der Bot Framework-Emulator ist ein Desktoptool, mit dem Sie die Funktionalität Ihres Bots testen können. Obwohl der Bot Framework-Emulator die gleichen Authentifizierungstechnologien wie oben beschrieben verwendet, kann er den tatsächlichen Bot Connector-Dienst nicht imitieren. Stattdessen wird die Microsoft App-ID und Microsoft App-Kennwort verwendet, das Sie angeben, wenn Sie den Emulator mit Ihrem Bot verbinden, um Token zu erstellen, die mit denen identisch sind, die der Bot erstellt. Wenn der Emulator eine Anforderung an Ihren Bot sendet, gibt er das JWT-Token im Authorization Header der Anforderung an – im Wesentlichen die eigenen Anmeldeinformationen des Bots, um die Anforderung zu authentifizieren.

Wenn Sie eine Authentifizierungsbibliothek implementieren und Anforderungen vom Bot Framework-Emulator akzeptieren möchten, müssen Sie diesen zusätzlichen Überprüfungspfad hinzufügen. Der Pfad ähnelt strukturell dem Connector -> Bot-Überprüfungspfad , verwendet aber das OpenID-Dokument von MSA anstelle des OpenID-Dokuments des Bot Connectors.

So authentifizieren Sie Aufrufe vom Bot Framework-Emulator:

1. Ihr Bot bezieht das JWT-Token aus dem Autorisierungsheader in Anfragen, die vom Bot Framework-Emulator gesendet werden.
2. Ihr Bot ruft das OpenID-Metadatendokument für den Bot Connector-Dienst ab.
3. Ihr Bot ruft die Liste der gültigen Signaturschlüssel aus dem Dokument ab.
4. Ihr Bot überprüft die Authentizität des JWT-Tokens.

Schritt 2: Abrufen des MSA OpenID-Metadatendokuments

Das OpenID-Metadatendokument gibt den Speicherort eines zweiten Dokuments an, in dem die gültigen Signaturschlüssel aufgelistet sind. Um das MSA OpenID-Metadatendokument abzurufen, stellen Sie diese Anforderung über HTTPS aus:

GET https://login.microsoftonline.com/botframework.com/v2.0/.well-known/openid-configuration

Das folgende Beispiel zeigt ein OpenID-Metadatendokument, das als Antwort auf die GET Anforderung zurückgegeben wird. Die jwks_uri Eigenschaft gibt den Speicherort des Dokuments an, das die gültigen Signaturschlüssel enthält.

{
    "authorization_endpoint":"https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
    "token_endpoint":"https://login.microsoftonline.com/common/oauth2/v2.0/token",
    "token_endpoint_auth_methods_supported":["client_secret_post","private_key_jwt"],
    "jwks_uri":"https://login.microsoftonline.com/common/discovery/v2.0/keys",
    ...
}

Schritt 3: Abrufen der Liste der gültigen Signaturschlüssel

Um die Liste der gültigen Signaturschlüssel abzurufen, geben Sie eine GET Anforderung über HTTPS an die url aus, die von der jwks_uri Eigenschaft im OpenID-Metadatendokument angegeben wurde. Beispiel:

GET https://login.microsoftonline.com/common/discovery/v2.0/keys
Host: login.microsoftonline.com

Der Antworttext gibt das Dokument im JWK-Format an.

Schritt 4: Überprüfen des JWT-Tokens

Um die Echtheit des Tokens zu überprüfen, das vom Emulator gesendet wurde, müssen Sie das Token aus dem Authorization Header der Anforderung extrahieren, das Token analysieren, dessen Inhalt überprüfen und seine Signatur überprüfen.

JWT-Analysebibliotheken sind für viele Plattformen verfügbar und implementieren die sicherste und zuverlässige Analyse für JWT-Token, obwohl Sie diese Bibliotheken in der Regel so konfigurieren müssen, dass bestimmte Merkmale des Tokens (aussteller, Zielgruppe usw.) korrekte Werte enthalten. Beim Analysieren des Tokens müssen Sie die Analysebibliothek konfigurieren oder eine eigene Überprüfung schreiben, um sicherzustellen, dass das Token diese Anforderungen erfüllt:

1. Das Token wurde im HTTP-Header Authorization im „Bearer“-Schema übermittelt.
2. Das Token ist gültiger JSON-Code, der dem JWT-Standard entspricht.
3. Das Token enthält einen Ausstelleranspruch für das entsprechende Sicherheitsprotokoll. Informationen zur aktuellen Implementierung finden Sie unter Microsoft. Agents.Connector.
4. Das Token enthält einen "Audience"-Anspruch mit einem Wert, der der Microsoft App-ID des Bots entspricht.
5. Der Emulator sendet abhängig von der Version die AppId entweder über den Appid-Anspruch (Version 1) oder den Anspruch der autorisierten Partei (Version 2).
6. Das Token liegt innerhalb des Gültigkeitszeitraums. Der branchenübliche Taktversatz beträgt 5 Minuten.
7. Das Token verfügt über eine gültige kryptografische Signatur mit einem Schlüssel, der im OpenID-Schlüsseldokument aufgeführt ist, das in Schritt 3 abgerufen wurde.

Wenn das Token nicht alle diese Anforderungen erfüllt, sollte Ihr Bot die Anforderung beenden, indem ein HTTP 403 (Verbotener) Statuscode zurückgegeben wird.

Emulator für Bot: Beispiel-JWT-Komponenten

header:
{
  typ: "JWT",
  alg: "RS256",
  x5t: "<SIGNING KEY ID>",
  kid: "<SIGNING KEY ID>"
},
payload:
{
  aud: "<YOUR MICROSOFT APP ID>",
  iss: "https://sts.windows.net/d6d49420-f39b-4df7-a1dc-d59a935871db/",
  nbf: 1481049243,
  exp: 1481053143,
  ... other fields follow
}

Sicherheitsprotokolländerungen

Bot-zu-Connector-Authentifizierung

OAuth-Anmelde-URL

OAuth-Bereich

Connector zur Bot-Authentifizierung

OpenID-Metadatendokument

JWT-Aussteller

Emulator für Bot-Authentifizierung

OAuth-Anmelde-URL

OAuth-Bereich

JWT-Zielgruppe

JWT-Aussteller

Informationen zur aktuellen Implementierung finden Sie unter Microsoft. Agents.Connector.

OpenID-Metadatendokument

Weitere Ressourcen

• Problembehandlung bei der Bot Framework-Authentifizierung
• Spezifikation des Aktivitätsprotokolls
• RestConnectorClient-API-Referenz
• JSON Web Token (JWT) draft-jones-json-web-token-07
• JSON Web Signature (JWS) draft-jones-json-web-signature-04
• JSON Web Key (JWK) RFC 7517