Authentifizierung mit der Bot Connector-APIAuthentication with the Bot Connector API

Ihr Bot kommuniziert mit dem Bot Connector-Dienst über HTTP über einen sicheren Kanal (SSL/TLS).Your bot communicates with the Bot Connector service using HTTP over a secured channel (SSL/TLS). Wenn Ihr Bot eine Anforderung an den Connector-Dienst sendet, muss diese Informationen enthalten, anhand derer der Connector-Dienst die Identität bestätigen kann.When your bot sends a request to the Connector service, it must include information that the Connector service can use to verify its identity. Ebenso muss der Connector-Dienst, wenn er eine Anforderung an Ihren Bot sendet, Informationen enthalten, anhand der Bot die Identität überprüfen kann.Likewise, when the Connector service sends a request to your bot, it must include information that the bot can use to verify its identity. In diesem Artikel werden die Authentifizierungstechnologien und die Anforderungen für Authentifizierung auf Dienstebene beschrieben, die zwischen einem Bot und dem Bot Connector-Dienst erfolgt.This article describes the authentication technologies and requirements for the service-level authentication that takes place between a bot and the Bot Connector service. Wenn Sie eigenen Authentifizierungscode schreiben, müssen Sie die in diesem Artikel beschriebenen Sicherheitsverfahren implementieren, um Ihrem Bot den Austausch von Nachrichten mit dem Bot Connector-Dienst zu ermöglichen.If you are writing your own authentication code, you must implement the security procedures described in this article to enable your bot to exchange messages with the Bot Connector service.

Wichtig

Wenn Sie eigenen Authentifizierungscode schreiben, ist es wichtig, dass alle Sicherheitsverfahren ordnungsgemäß implementiert werden.If you are writing your own authentication code, it is critical that you implement all security procedures correctly. Durch die Implementierung aller Schritte in diesem Artikel können Sie das Risiko verringern, dass ein Angreifer in der Lage ist, Nachrichten zu lesen, die an Ihren Bot gesendet werden, Nachrichten zu senden, die sich als Ihr Bot ausgeben, und geheime Schlüssel zu stehlen.By implementing all steps in this article, you can mitigate the risk of an attacker being able to read messages that are sent to your bot, send messages that impersonate your bot, and steal secret keys.

Wenn Sie das Bot Framework SDK für .NET oder das Bot Framework SDK für Node.js verwenden, müssen Sie die in diesem Artikel beschriebenen Sicherheitsverfahren nicht implementieren, da das SDK dies automatisch für Sie erledigt.If you are using the Bot Framework SDK for .NET or the Bot Framework SDK for Node.js, you do not need to implement the security procedures described in this article, because the SDK automatically does it for you. Konfigurieren Sie einfach Ihr Projekt mit der für Ihren Bot während der Registrierung erhaltenen App-ID und dem Kennwort, und das SDK erledigt den Rest.Simply configure your project with the App ID and password that you obtained for your bot during registration and the SDK will handle the rest.

Warnung

Im Dezember 2016 wurde mit Version 3.1 des Bot Framework-Sicherheitsprotokolls Änderungen an mehreren Werten eingeführt, die bei der Tokengenerierung und -validierung verwendet werden.In December 2016, v3.1 of the Bot Framework security protocol introduced changes to several values that are used during token generation and validation. Im Spätherbst 2017 wurde die Version 3.2 des Bot Framework-Sicherheitsprotokolls eingeführt, die Änderungen an Werten enthält, die bei der Tokengenerierung und -validierung verwendet werden.In late fall of 2017, v3.2 of the Bot Framework security protocol was introduced which included changes to values that are used during token generation and validation. Weitere Informationen finden Sie unter Änderungen am Sicherheitsprotokoll.For more information, see Security protocol changes.

AuthentifizierungstechnologienAuthentication technologies

Vier Authentifizierungstechnologien werden verwendet, um eine Vertrauensstellung zwischen einem Bot und dem Bot Connector herzustellen:Four authentication technologies are used to establish trust between a bot and the Bot Connector:

TechnologieTechnology BESCHREIBUNGDescription
SSL/TLSSSL/TLS SSL/TLS wird für alle Verbindungen von Dienst zu Dienst verwendet.SSL/TLS is used for all service-to-service connections. X.509v3-Zertifikate werden verwendet, um die Identität aller HTTPS-Dienste festzustellen.X.509v3 certificates are used to establish the identity of all HTTPS services. Clients sollten Dienstzertifikate immer überprüfen, um sicherzustellen, dass sie vertrauenswürdig und gültig sind.Clients should always inspect service certificates to ensure they are trusted and valid. (Clientzertifikate werden NICHT als Teil dieses Schema verwendet.)(Client certificates are NOT used as part of this scheme.)
OAuth 2.0OAuth 2.0 OAuth 2.0 generiert mithilfe des Anmeldediensts für das Azure AD v2-Konto (Azure Active Directory) ein Sicherheitstoken, das ein Bot zum Senden von Nachrichten verwenden kann.OAuth 2.0 uses the Azure Active Directory (Azure AD) v2 account login service to generate a secure token that a bot can use to send messages. Dieses Token ist ein Dienst-zu-Dienst-Token. Es ist keine Benutzeranmeldung erforderlich.This token is a service-to-service token; no user login is required.
JSON Web Token (JWT)JSON Web Token (JWT) JSON Web Token werden verwendet, um Token zu codieren, die vom und an den Bot gesendet werden.JSON Web Tokens are used to encode tokens that are sent to and from the bot. Clients sollten alle empfangenen JWT-Token vollständig gemäß den in diesem Artikel beschriebenen Anforderungen überprüfen.Clients should fully verify all JWT tokens that they receive, according to the requirements outlined in this article.
OpenID-MetadatenOpenID metadata Der Bot Connector-Dienst veröffentlicht eine Liste mit gültigen Token, die zum Signieren der eigenen JWT-Token verwendet, in OpenID-Metadaten auf einem bekannten statischen Endpunkt.The Bot Connector service publishes a list of valid tokens that it uses to sign its own JWT tokens to OpenID metadata at a well-known, static endpoint.

In diesem Artikel wird beschrieben, wie Sie diese Technologien über Standard-HTTPS und -JSON verwenden können.This article describes how to use these technologies via standard HTTPS and JSON. Es werden keine speziellen SDKs benötigt, obwohl Sie vielleicht feststellen, dass Helfer für OpenID etc. nützlich sind.No special SDKs are required, although you may find that helpers for OpenID etc. are useful.

Authentifizieren von Anforderungen von Ihrem Bot an den Bot Connector-DienstAuthenticate requests from your bot to the Bot Connector service

Um mit dem Bot Connector-Dienst zu kommunizieren, müssen Sie ein Zugriffstoken im Authorization-Header jeder API-Anforderung unter Verwendung dieses Formats angeben:To communicate with the Bot Connector service, you must specify an access token in the Authorization header of each API request, using this format:

Authorization: Bearer ACCESS_TOKEN

Dieses Diagramm zeigt die Schritte für die Authentifizierung von Bot zu Connector:This diagram shows the steps for bot-to-connector authentication:

Authentifizieren beim MSA-Anmeldedienst und dann beim Bot

Schritt 1: Anfordern eines Zugriffstokens vom Anmeldedienst für das Azure AD v2-KontoStep 1: Request an access token from the Azure AD v2 account login service

Wichtig

Falls nicht bereits geschehen, müssen Sie Ihren Bot bei Bot Framework registrieren, um dessen AppID und Kennwort zu erhalten.If you have not already done so, you must register your bot with the Bot Framework to obtain its AppID and password. Sie benötigen die App-ID und das Kennwort des Bots, um ein Zugriffstoken anzufordern.You need the bot's App ID and password to request an access token.

Um ein Zugriffstoken vom Anmeldedienst anzufordern, führen Sie die folgende Anforderung aus, wobei Sie MICROSOFT-APP-ID und MICROSOFT-APP-PASSWORD durch die Angaben für die App-ID und das Kennwort des Bots ersetzen, die Sie beim Registrieren Ihres Bots bei Bot Framework erhalten haben.To request an access token from the login service, issue the following request, replacing MICROSOFT-APP-ID and MICROSOFT-APP-PASSWORD with the bot's AppID and password that you obtained when you registered your bot with the Bot Framework.

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

Schritt 2: Abrufen des JWT-Tokens aus der Antwort des Anmeldediensts für das Azure AD v2-KontoStep 2: Obtain the JWT token from the the Azure AD v2 account login service response

Wenn Ihre Anwendung durch den Anmeldedienst autorisiert wurde, sind im JSON-Antworttext Ihr Zugriffstoken, sein Typ und sein Ablauf (in Sekunden) angegeben.If your application is authorized by the login service, the JSON response body will specify your access token, its type, and its expiration (in seconds).

Wenn Sie das Token zum Authorization-Header einer Anforderung hinzufügen, müssen Sie genau den Wert verwenden, der in dieser Antwort angegeben ist (d. h. der Tokenwert darf nicht mit Escapezeichen versehen oder kodiert werden).When adding the token to the Authorization header of a request, you must use the exact value that is specified in this response (i.e., do not escape or encode the token value). Das Zugriffstoken ist bis zu seinem Ablauf gültig.The access token is valid until its expiration. Um zu verhindern, dass das Ablaufen von Token die Leistung Ihres Bots beeinträchtigt, können Sie das Token zwischenspeichern und proaktiv aktualisieren.To prevent token expiration from impacting your bot's performance, you may choose to cache and proactively refresh the token.

Im folgenden Beispiel wird eine Antwort vom Anmeldedienst für das Azure AD v2-Konto gezeigt:This example shows a response from the the Azure AD v2 account login service:

HTTP/1.1 200 OK
... (other headers)
{
    "token_type":"Bearer",
    "expires_in":3600,
    "ext_expires_in":3600,
    "access_token":"eyJhbGciOiJIUzI1Ni..."
}

Schritt 3: Angeben des JWT-Tokens im Autorisierungsheader von AnforderungenStep 3: Specify the JWT token in the Authorization header of requests

Wenn Sie eine API-Anforderung an den Bot Connector-Dienst senden, geben Sie das Zugriffstoken im Authorization-Header der Anforderung unter Verwendung dieses Formats an:When you send an API request to the Bot Connector service, specify the access token in the Authorization header of the request using this format:

Authorization: Bearer ACCESS_TOKEN

Alle Anforderungen, die Sie an den Bot Connector-Dienst senden, müssen das Zugriffstoken im Authorization-Header enthalten.All requests that you send to the Bot Connector service must include the access token in the Authorization header. Wenn das Token ist richtig formatiert ist, nicht abgelaufen ist und durch den Anmeldedienst für das Azure AD v2-Konto generiert wurde, autorisiert der Bot Connector-Dienst die Anforderung.If the token is correctly formed, is not expired, and was generated by the the Azure AD v2 account login service, the Bot Connector service will authorize the request. Zusätzliche Überprüfungen werden ausgeführt, um sicherzustellen, dass das Token zum Bot gehört, der die Anforderung gesendet hat.Additional checks are performed to ensure that the token belongs to the bot that sent the request.

Im folgenden Beispiel wird gezeigt, wie das Zugriffstoken im Authorization-Header der Anforderung angegeben wird.The following example shows how to specify the access token in the Authorization header of the request.

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

(JSON-serialized Activity message goes here)

Wichtig

Geben Sie das JWT-Token nur im Authorization-Header von Anforderungen an, die Sie an den Bot Connector-Dienst senden.Only specify the JWT token in the Authorization header of requests you send to the Bot Connector service. Senden Sie das Token NICHT über unsichere Kanäle, und fügen Sie es NICHT in HTTP-Anforderungen ein, die Sie an andere Dienste senden.Do NOT send the token over unsecured channels and do NOT include it in HTTP requests that you send to other services. Das JWT-Token, das Sie vom Anmeldedienst für das Azure AD v2-Konto erhalten, gleicht einem Kennwort und sollte mit äußerster Sorgfalt behandelt werden.The JWT token that you obtain from the the Azure AD v2 account login service is like a password and should be handled with great care. Jeder, der in den Besitz des Tokens kommt, kann es zum Ausführen von Vorgängen im Namen Ihres Bots verwenden.Anyone that possesses the token may use it to perform operations on behalf of your bot.

Bot an Connector: Beispiel für JWT-KomponentenBot to Connector: example JWT components

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
}

Hinweis

Die tatsächlichen Felder können in der Praxis variieren.Actual fields may vary in practice. Erstellen und überprüfen Sie alle JWT-Token wie oben angegeben.Create and validate all JWT tokens as specified above.

Authentifizieren von Anforderungen vom Bot Connector-Dienst an Ihren BotAuthenticate requests from the Bot Connector service to your bot

Wenn der Bot Connector-Dienst eine Anforderung an Ihren Bot sendet, wird ein signiertes JWT-Token im Authorization-Header der Anforderung angegeben.When the Bot Connector service sends a request to your bot, it specifies a signed JWT token in the Authorization header of the request. Ihr Bot kann Aufrufe des Bot Connector-Diensts authentifizieren, indem er die Echtheit des signierten JWT-Tokens überprüft.Your bot can authenticate calls from the Bot Connector service by verifying the authenticity of the signed JWT token.

Dieses Diagramm zeigt die Schritte für die Authentifizierung von Connector zu Bot:This diagram shows the steps for connector-to-bot authentication:

Authentifizieren von Aufrufen von Bot Connector zu Ihrem Bot

Schritt 2: Abrufen des OpenID-MetadatendokumentsStep 2: Get the OpenID metadata document

Das OpenID-Metadatendokument gibt den Speicherort eines zweiten Dokuments an, in dem die gültigen Signaturschlüssel des Bot Connector-Diensts auflistet sind.The OpenID metadata document specifies the location of a second document that lists the Bot Connector service's valid signing keys. Um das OpenID-Metadatendokument zu erhalten, geben Sie diese Anforderung über HTTPS aus:To get the OpenID metadata document, issue this request via HTTPS:

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

Tipp

Dies ist eine statische URL, die Sie in Ihrer Anwendung hartcodieren können.This is a static URL that you can hardcode into your application.

Im folgenden Beispiel wird ein OpenID-Metadatendokument gezeigt, das als Antwort auf die GET-Anforderung zurückgegeben wird.The following example shows an OpenID metadata document that is returned in response to the GET request. Die jwks_uri-Eigenschaft gibt den Speicherort des Dokuments an, das die gültigen Signaturschlüssel des Bot Connector-Diensts enthält.The jwks_uri property specifies the location of the document that contains the Bot Connector service's valid signing keys.

{
    "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üsselStep 3: Get the list of valid signing keys

Um die Liste der gültigen Signaturschlüssel zu erhalten, geben Sie eine GET-Anforderung über HTTPS an die von der jwks_uri-Eigenschaft im OpenID-Metadatendokument angegebene URL aus.To get the list of valid signing keys, issue a GET request via HTTPS to the URL specified by the jwks_uri property in the OpenID metadata document. Beispiel:For example:

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

Der Antworttext gibt das Dokument im JWK-Format an, enthält jedoch auch eine zusätzliche Eigenschaft für jeden Schlüssel: endorsements.The response body specifies the document in the JWK format but also includes an additional property for each key: endorsements.

Tipp

Die Liste der Schlüssel ist stabil und kann zwischengespeichert werden. Neue Schlüssel können jedoch jederzeit hinzugefügt werden.The list of keys is stable and may be cached, but new keys may be added at any time. Um sicherzustellen, dass Ihr Bot über eine aktuelle Kopie des Dokuments verfügt, bevor diese Schlüssel verwendet werden, sollten alle Botinstanzen ihren lokalen Cache des Dokuments mindestens einmal alle 24 Stunden aktualisieren.To ensure your bot has an up-to-date copy of the document before these keys are used, all bot instances should refresh their local cache of the document at least once every 24 hours.

Die endorsements-Eigenschaft in jedem Schlüssel enthält eine oder mehrere Endorsement-Zeichenfolgen, mit denen Sie sicherstellen können, dass die in der channelId-Eigenschaft im Aktivität-Objekt angegebene Kanal-ID der eingehenden Anforderung echt ist.The endorsements property within each key contains one or more endorsement strings which you can use to verify that the channel ID specified in the channelId property within the Activity object of the incoming request is authentic. Die Liste der Kanal-IDs, die Endorsements erfordern, kann in jedem Bot konfiguriert werden.The list of channel IDs that require endorsements is configurable within each bot. Standardmäßig ist es die Liste aller veröffentlichten Kanal-IDs, aber Botentwickler können bestimmte Kanal-ID-Werde in beiden Fällen überschreiben.By default, it will be the list of all published channel IDs, although bot developers may override selected channel ID values either way.

Schritt 4: Überprüfen des JWT-TokensStep 4: Verify the JWT token

Um die Echtheit des Tokens, das vom Bot Connector-Dienst gesendet wurde, zu überprüfen, müssen Sie das Token aus dem Authorization-Header der Anforderung extrahieren, das Token analysieren, seinen Inhalt überprüfen und seine Signatur überprüfen.To verify the authenticity of the token that was sent by the Bot Connector service, you must extract the token from the Authorization header of the request, parse the token, verify its contents, and verify its signature.

JWT-Analysebibliotheken sind für viele Plattformen verfügbar, und die meisten implementieren sichere und zuverlässige Analyse für JWT-Token. Allerdings müssen Sie diese Bibliotheken typischerweise so konfigurieren, dass bestimmte Eigenschaften des Tokens (Herausgeber, Zielgruppe usw.) korrekte Werte enthalten.JWT parsing libraries are available for many platforms and most implement secure and reliable parsing for JWT tokens, although you must typically configure these libraries to require that certain characteristics of the token (its issuer, audience, etc.) contain correct values. Wenn Sie Token analysieren möchten, müssen Sie die Analysebibliothek konfigurieren oder eine eigene Überprüfung schreiben, um sicherzustellen, dass das Token diese Anforderungen erfüllt:When parsing the token, you must configure the parsing library or write your own validation to ensure the token meets these requirements:

  1. Das Token wurde im HTTP Authorization-Header mit dem „Bearer“-Schema gesendet.The token was sent in the HTTP Authorization header with "Bearer" scheme.
  2. Das Token liegt in gültigem, mit dem JWT-Standard konformen JSON-Format vor.The token is valid JSON that conforms to the JWT standard.
  3. Das Token enthält einen „issuer“-Anspruch mit dem https://api.botframework.com-Wert.The token contains an "issuer" claim with value of https://api.botframework.com.
  4. Das Token enthält einen „audience“-Anspruchs mit einem Wert, der der Microsoft App-ID des Bots entspricht.The token contains an "audience" claim with a value equal to the bot's Microsoft App ID.
  5. Die Gültigkeit des Tokens ist nicht abgelaufen.The token is within its validity period. Branchenstandard-Uhrabweichung beträgt 5 Minuten.Industry-standard clock-skew is 5 minutes.
  6. Das Token verfügt über eine gültige kryptographische Signatur mit einem Schlüssel, der im OpenID-Schlüsseldokument aufgeführt ist, das in Schritt 3 abgerufen wurde, und verwendet einen Signaturalgorithmus, der in der id_token_signing_alg_values_supported-Eigenschaft des in Schritt 2 abgerufenen Open ID-Metadatendokuments angegeben ist.The token has a valid cryptographic signature, with a key listed in the OpenID keys document that was retrieved in Step 3, using the signing algorithm that is specified in the id_token_signing_alg_values_supported property of the Open ID Metadata document that was retrieved in Step 2.
  7. Das Token enthält einen Anspruch vom Typ „serviceUrl“ mit einem Wert, der der serviceUrl-Eigenschaft im Stamm des Aktivität-Objekts der eingehenden Anforderung entspricht.The token contains a "serviceUrl" claim with value that matches the serviceUrl property at the root of the Activity object of the incoming request.

Wenn das Endorsement für eine Kanal-ID erforderlich ist:If endorsement for a channel ID is required:

  • Legen Sie fest, dass jedes Activity-Objekt, das mit dieser Kanal-ID an Ihren Bot gesendet wird, zudem über ein JWT-Token verfügen muss, das mit einem Endorsement für diesen Kanal signiert ist.You should require that any Activity object sent to your bot with that channel ID is accompanied by a JWT token that is signed with an endorsement for that channel.
  • Wenn kein Endorsement vorhanden ist, sollte Ihr Bot die Anforderung unter Rückgabe eines HTTP 403 (Unzulässig) -Statuscodes abweisen.If the endorsement is not present, your bot should reject the request by returning an HTTP 403 (Forbidden) status code.

Wichtig

Alle diese Anforderungen sind wichtig, besonders die Anforderungen 4 und 6.All of these requirements are important, particularly requirements 4 and 6. Wenn nicht ALLE diese Verifizierungsanforderungen implementiert werden, ist der Bot offen für Angriffe, die dazu führen könnten, dass der Bot sein JWT-Token preisgibt.Failure to implement ALL of these verification requirements will leave the bot open to attacks which could cause the bot to divulge its JWT token.

Implementierer sollten keine Möglichkeit bieten, die Validierung des an den Bot gesendeten JWT-Tokens zu deaktivieren.Implementers should not expose a way to disable validation of the JWT token that is sent to the bot.

Connector an Bot: Beispiel für JWT-KomponentenConnector to Bot: example JWT components

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
}

Hinweis

Die tatsächlichen Felder können in der Praxis variieren.Actual fields may vary in practice. Erstellen und überprüfen Sie alle JWT-Token wie oben angegeben.Create and validate all JWT tokens as specified above.

Authentifizieren von Anforderungen vom Bot Framework Emulator an Ihren BotAuthenticate requests from the Bot Framework Emulator to your bot

Warnung

Im Spätherbst 2017 wurde Version 3.2. des Bot Framework -Sicherheitsprotokolls eingeführt.In late fall of 2017, v3.2 of the Bot Framework security protocol was introduced. Diese neue Version enthält einen neuen „issuer“-Wert in Token, die zwischen dem Bot Framework Emulator und Ihrem Bot ausgetauscht werden.This new version includes a new "issuer" value within tokens that are exchanged between the Bot Framework Eumaltor and your bot. Zur Vorbereitung dieser Änderung beschreiben die unten aufgeführten Schritte, wie Sie „issuer“-Werte sowohl für Version 3.1 als auch Version 3.2 überprüfen.To prepare for this change, the below steps outline how to check for both the v3.1 and v3.2 issuer values.

Der Bot Framework Emulator ist ein Desktoptool, das Sie zum Testen der Funktionalität Ihres Bots verwenden können.The Bot Framework Emulator is a desktop tool that you can use to test the functionality of your bot. Der Bot Framework Emulator verwendet zwar die gleichen Authentifizierungstechnologien wie oben beschrieben, ist aber nicht in der Lage, den echten Bot Connector-Dienst nachzuahmen.Although the Bot Framework Emulator uses the same authentication technologies as described above, it is unable to impersonate the real Bot Connector service. Stattdessen werden die Microsoft-App-ID und das Microsoft-App-Kennwort verwendet, die Sie angeben, wenn Sie den Emulator mit Ihrem Bot verbinden, um Token zu erstellen, die mit denen identisch sind, die der Bot erstellt.Instead, it uses the Microsoft App ID and Microsoft App Password that you specify when you connect the Emulator to your bot to create tokens that are identical to those that the bot creates. Wenn der Emulator eine Anforderung an Ihren Bot sendet, gibt er das JWT-Token im Header der Anforderung an – im Wesentlichen unter Verwendung der eigenen Anmeldeinformationen des Bots zum Authentifizieren Authorization der Anforderung.When the Emulator sends a request to your bot, it specifies the JWT token in the Authorization header of the request -- in essence, using the bot's own credentials to authenticate the request.

Wenn Sie eine Authentifizierungsbibliothek implementieren und Anforderungen vom Bot Framework-Emulator akzeptiert werden sollen, müssen Sie diesen zusätzlichen Überprüfungspfad hinzufügen.If you are implementing an authentication library and want to accept requests from the Bot Framework Emulator, you must add this additional verification path. Der Pfad ähnelt strukturell dem Connector-> Bot-Überprüfungspfad, verwendet jedoch das OpenID-Dokument von MSA anstelle des OpenID-Dokuments des Bot Connectors.The path is structurally similar to the Connector -> Bot verification path, but it uses MSA's OpenID document instead of the Bot Connector's OpenID document.

Dieses Diagramm zeigt die Schritte für die Emulator-zu-Bot-Authentifizierung:This diagram shows the steps for Emulator-to-bot authentication:

Authentifizieren von Aufrufen vom Bot Framework Emulator an Ihren Bot


Schritt 2: Abrufen des MSA OpenID-MetadatendokumentsStep 2: Get the MSA OpenID metadata document

Das OpenID-Metadatendokument gibt den Speicherort eines zweiten Dokuments an, in dem die gültigen Signaturschlüssel auflistet sind.The OpenID metadata document specifies the location of a second document that lists the valid signing keys. Um das MSA OpenID-Metadatendokument zu erhalten, geben Sie diese Anforderung über HTTPS aus:To get the MSA OpenID metadata document, issue this request via HTTPS:

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

Im folgenden Beispiel wird ein OpenID-Metadatendokument gezeigt, das als Antwort auf die GET-Anforderung zurückgegeben wird.The following example shows an OpenID metadata document that is returned in response to the GET request. Die jwks_uri-Eigenschaft gibt den Speicherort des Dokuments an, das die gültigen Signaturschlüssel enthält.The jwks_uri property specifies the location of the document that contains the valid signing keys.

{
    "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üsselStep 3: Get the list of valid signing keys

Um die Liste der gültigen Signaturschlüssel zu erhalten, geben Sie eine GET-Anforderung über HTTPS an die von der jwks_uri-Eigenschaft im OpenID-Metadatendokument angegebene URL aus.To get the list of valid signing keys, issue a GET request via HTTPS to the URL specified by the jwks_uri property in the OpenID metadata document. Beispiel:For example:

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

Der Antworttext gibt das Dokument im JWK-Format an.The response body specifies the document in the JWK format.

Schritt 4: Überprüfen des JWT-TokensStep 4: Verify the JWT token

Um die Authentizität des Tokens zu überprüfen, das vom Emulator gesendet wurde, müssen Sie das Token aus dem Header der Anforderung extrahieren, das Token analysieren, seinen Inhalt überprüfen und seine Authorization Signatur überprüfen.To verify the authenticity of the token that was sent by the Emulator, you must extract the token from the Authorization header of the request, parse the token, verify its contents, and verify its signature.

JWT-Analysebibliotheken sind für viele Plattformen verfügbar, und die meisten implementieren sichere und zuverlässige Analyse für JWT-Token. Allerdings müssen Sie diese Bibliotheken typischerweise so konfigurieren, dass bestimmte Eigenschaften des Tokens (Herausgeber, Zielgruppe usw.) korrekte Werte enthalten.JWT parsing libraries are available for many platforms and most implement secure and reliable parsing for JWT tokens, although you must typically configure these libraries to require that certain characteristics of the token (its issuer, audience, etc.) contain correct values. Wenn Sie Token analysieren möchten, müssen Sie die Analysebibliothek konfigurieren oder eine eigene Überprüfung schreiben, um sicherzustellen, dass das Token diese Anforderungen erfüllt:When parsing the token, you must configure the parsing library or write your own validation to ensure the token meets these requirements:

  1. Das Token wurde im HTTP Authorization-Header mit dem „Bearer“-Schema gesendet.The token was sent in the HTTP Authorization header with "Bearer" scheme.
  2. Das Token liegt in gültigem, mit dem JWT-Standard konformen JSON-Format vor.The token is valid JSON that conforms to the JWT standard.
  3. Das Token enthält einen Ausstelleranspruch mit einem der hervorgehobenen Werte für nicht behördliche Fälle.The token contains an "issuer" claim with one of the highlighted values for non governmental cases. Wenn Sie beide Ausstellerwerte überprüfen, stellen Sie sicher, dass Sie sowohl die Ausstellerwerte des Sicherheitsprotokolls v3.1 als auch der Version 3.2 überprüfen.Checking for both issuer values will ensure you are checking for both the security protocol v3.1 and v3.2 issuer values.
  4. Das Token enthält einen „audience“-Anspruchs mit einem Wert, der der Microsoft App-ID des Bots entspricht.The token contains an "audience" claim with a value equal to the bot's Microsoft App ID.
  5. Je nach Version sendet der Emulator die AppId entweder über den Anspruch appid (Version 1) oder den Anspruch der autorisierten Partei (Version 2).The Emulator, depending on the version, sends the AppId via either the appid claim (version 1) or the authorized party claim (version 2).
  6. Die Gültigkeit des Tokens ist nicht abgelaufen.The token is within its validity period. Branchenstandard-Uhrabweichung beträgt 5 Minuten.Industry-standard clock-skew is 5 minutes.
  7. Das Token verfügt über eine gültige kryptografische Signatur mit einem Schlüssel, der in Dokument der OpenID-Schlüssel aufgeführt ist, das in Schritt 3 abgerufen wurde.The token has a valid cryptographic signature with a key listed in the OpenID keys document that was retrieved in Step 3.

Hinweis

Anforderung 5 ist für den Überprüfungspfad des Emulators spezifisch.Requirement 5 is a specific to the Emulator verification path.

Wenn das Token nicht alle diese Anforderungen erfüllt, sollte Ihr Bot die Anforderung unter Rückgabe eines HTTP 403 (Unzulässig) -Statuscodes beenden.If the token does not meet all of these requirements, your bot should terminate the request by returning an HTTP 403 (Forbidden) status code.

Wichtig

Alle diese Anforderungen sind wichtig, besonders die Anforderungen 4 und 7.All of these requirements are important, particularly requirements 4 and 7. Wenn nicht ALLE diese Verifizierungsanforderungen implementiert werden, ist der Bot offen für Angriffe, die dazu führen könnten, dass der Bot sein JWT-Token preisgibt.Failure to implement ALL of these verification requirements will leave the bot open to attacks which could cause the bot to divulge its JWT token.

Emulator an Bot: Beispiel für JWT-KomponentenEmulator to Bot: example JWT components

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
}

Hinweis

Die tatsächlichen Felder können in der Praxis variieren.Actual fields may vary in practice. Erstellen und überprüfen Sie alle JWT-Token wie oben angegeben.Create and validate all JWT tokens as specified above.

Änderungen des SicherheitsprotokollsSecurity protocol changes

Warnung

Die Unterstützung für Version 3.0 des Sicherheitsprotokolls wurde zum 31. Juli 2017 eingestellt.Support for v3.0 of the security protocol was discontinued on July 31, 2017. Wenn Sie Ihren eigenen Authentifizierungscode geschrieben haben (d.h. den Bot nicht mit dem Bot Framework SDK erstellt haben), müssen Sie ein Upgrade auf Version 3.1 des Sicherheitsprotokolls vornehmen, indem Sie Ihre Anwendung zur Verwendung der unten aufgeführten v3.1-Werte aktualisieren.If you have written your own authentication code (i.e., did not use the Bot Framework SDK to create your bot), you must upgrade to v3.1 of the security protocol by updating your application to use the v3.1 values that are listed below.

Bot zu Connector-AuthentifizierungBot to Connector authentication

OAuth-Anmelde-URLOAuth login URL

ProtokollversionProtocol version Gültiger WertValid value
v3.1 und v3.2v3.1 & v3.2 https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token

OAuth-BereichOAuth scope

ProtokollversionProtocol version Gültiger WertValid value
v3.1 und v3.2v3.1 & v3.2 https://api.botframework.com/.default

Connector zu Bot AuthentifizierungConnector to Bot authentication

OpenID-MetadatendokumentOpenID metadata document

ProtokollversionProtocol version Gültiger WertValid value
v3.1 und v3.2v3.1 & v3.2 https://login.botframework.com/v1/.well-known/openidconfiguration

JWT-AusstellerJWT Issuer

ProtokollversionProtocol version Gültiger WertValid value
v3.1 und v3.2v3.1 & v3.2 https://api.botframework.com

Emulator zu Bot AuthentifizierungEmulator to Bot authentication

OAuth-Anmelde-URLOAuth login URL

ProtokollversionProtocol version Gültiger WertValid value
v3.1 und v3.2v3.1 & v3.2 https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token

OAuth-BereichOAuth scope

ProtokollversionProtocol version Gültiger WertValid value
v3.1 und v3.2v3.1 & v3.2 Microsoft-App-ID Ihres Bots + /.defaultYour bot's Microsoft App ID + /.default

JWT-ZielgruppeJWT Audience

ProtokollversionProtocol version Gültiger WertValid value
v3.1 und v3.2v3.1 & v3.2 Microsoft-App-ID Ihres BotsYour bot's Microsoft App ID

JWT-AusstellerJWT Issuer

ProtokollversionProtocol version Gültiger WertValid value
v3.1 1.0v3.1 1.0 https://sts.windows.net/d6d49420-f39b-4df7-a1dc-d59a935871db/
v3.1 2.0v3.1 2.0 https://login.microsoftonline.com/d6d49420-f39b-4df7-a1dc-d59a935871db/v2.0
v3.2 1.0v3.2 1.0 https://sts.windows.net/f8cdef31-a31e-4b4a-93e4-5f571e91255a/
v3.2 2.0v3.2 2.0 https://login.microsoftonline.com/f8cdef31-a31e-4b4a-93e4-5f571e91255a/v2.0

Siehe auch die hervorgehobenen Werte für nicht behördliche Fälle.See also the highlighted values for non governmental cases.

OpenID-MetadatendokumentOpenID metadata document

ProtokollversionProtocol version Gültiger WertValid value
v3.1 und v3.2v3.1 & v3.2 https://login.microsoftonline.com/botframework.com/v2.0/.well-known/openid-configuration

Zusätzliche RessourcenAdditional resources