Share via

Verificatie met de Bot Verbinding maken or-API

  • Artikel

Uw bot communiceert met de Bot Verbinding maken or-service via HTTP via een beveiligd kanaal (SSL/TLS). Wanneer uw bot een aanvraag naar de Verbinding maken orservice verzendt, moet deze informatie bevatten die de Verbinding maken orservice kan gebruiken om de identiteit te verifiëren. Ook wanneer de Verbinding maken orservice een aanvraag naar uw bot verzendt, moet deze informatie bevatten die de bot kan gebruiken om de identiteit ervan te verifiëren. In dit artikel worden de verificatietechnologieën en -vereisten beschreven voor de verificatie op serviceniveau die plaatsvindt tussen een bot en de Bot Verbinding maken or-service. Als u uw eigen verificatiecode schrijft, moet u de beveiligingsprocedures implementeren die in dit artikel worden beschreven om uw bot in staat te stellen berichten uit te wisselen met de Bot Verbinding maken or-service.

Belangrijk

Als u uw eigen verificatiecode schrijft, is het essentieel dat u alle beveiligingsprocedures correct implementeert. Door alle stappen in dit artikel te implementeren, kunt u het risico beperken dat een aanvaller berichten kan lezen die naar uw bot worden verzonden, berichten verzendt die zich voordoen als uw bot en geheime sleutels steelt.

Als u de Bot Framework SDK gebruikt, hoeft u de beveiligingsprocedures die in dit artikel worden beschreven, niet te implementeren, omdat de SDK dit automatisch voor u doet. Configureer uw project met de app-id en het wachtwoord dat u tijdens de registratie hebt verkregen voor uw bot en de SDK verwerkt de rest.

Authenticatietechnologieën

Er worden vier verificatietechnologieën gebruikt om een vertrouwensrelatie tot stand te brengen tussen een bot en de bot Verbinding maken or:

Technologie Beschrijving
SSL/TLS SSL/TLS wordt gebruikt voor alle service-naar-service-verbindingen. X.509v3 certificaten worden gebruikt om de identiteit van alle HTTPS-services tot stand te brengen. Clients moeten altijd servicecertificaten inspecteren om ervoor te zorgen dat ze vertrouwd en geldig zijn. (Clientcertificaten worden NIET gebruikt als onderdeel van dit schema.)
OAuth 2.0 OAuth 2.0 maakt gebruik van de aanmeldingsservice voor het Microsoft Entra ID-account om een beveiligd token te genereren dat een bot kan gebruiken om berichten te verzenden. Dit token is een service-to-servicetoken; er is geen aanmelding van de gebruiker vereist.
JSON-webtoken (JWT) JSON-webtokens worden gebruikt om tokens te coderen die naar en van de bot worden verzonden. Clients moeten alle JWT-tokens die ze ontvangen, volledig verifiëren volgens de vereisten die in dit artikel worden beschreven.
OpenID-metagegevens De Bot Verbinding maken or-service publiceert een lijst met geldige tokens die worden gebruikt om zijn eigen JWT-tokens te ondertekenen bij OpenID-metagegevens op een bekend, statisch eindpunt.

In dit artikel wordt beschreven hoe u deze technologieën gebruikt via standaard HTTPS en JSON. Er zijn geen speciale SDK's vereist, hoewel u misschien merkt dat helpers voor OpenID en anderen nuttig zijn.

Aanvragen van uw bot verifiëren bij de bot Verbinding maken orservice

Als u wilt communiceren met de Bot Verbinding maken or-service, moet u een toegangstoken opgeven in de Authorization header van elke API-aanvraag, met behulp van deze indeling:

Authorization: Bearer ACCESS_TOKEN

Een JWT-token ophalen en gebruiken voor uw bot:

  1. Uw bot verzendt een GET HTTP-aanvraag naar de MSA-aanmeldingsservice.
  2. Het antwoord van de service bevat het JWT-token dat moet worden gebruikt.
  3. Uw bot bevat dit JWT-token in de autorisatieheader in aanvragen voor de Bot Verbinding maken or-service.

Stap 1: Een toegangstoken aanvragen bij de aanmeldingsservice van het Microsoft Entra ID-account

Belangrijk

Als u dit nog niet hebt gedaan, moet u uw bot registreren bij het Bot Framework om de Bijbehorende AppID en het wachtwoord op te halen. U hebt de app-id en het wachtwoord van de bot nodig om een toegangstoken aan te vragen.

Uw bot-identiteit kan op verschillende manieren worden beheerd in Azure.

  • Als een door de gebruiker toegewezen beheerde identiteit, zodat u de referenties van de bot niet zelf hoeft te beheren.
  • Als een app met één tenant .
  • Als een app met meerdere tenants .

Vraag een toegangstoken aan op basis van het toepassingstype van uw bot.

Als u een toegangstoken wilt aanvragen bij de aanmeldingsservice, dient u de volgende aanvraag uit te voeren, waarbij u MICROSOFT-APP-ID en MICROSOFT-APP-PASSWORD vervangt door de AppID en het wachtwoord van de bot die u hebt verkregen toen u uw bot bij de Bot Service registreerde .

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

Stap 2: het JWT-token ophalen uit het aanmeldingsserviceantwoord van het Microsoft Entra ID-account

Als uw toepassing is geautoriseerd door de aanmeldingsservice, geeft de hoofdtekst van het JSON-antwoord uw toegangstoken, het type en de vervaldatum op (in seconden).

Wanneer u het token toevoegt aan de Authorization header van een aanvraag, moet u de exacte waarde gebruiken die in dit antwoord is opgegeven. U hoeft de tokenwaarde niet te escapen of te coderen. Het toegangstoken is geldig totdat het is verlopen. Als u wilt voorkomen dat het token verloopt van invloed is op de prestaties van uw bot, kunt u ervoor kiezen om het token in de cache op te slaan en proactief te vernieuwen.

In dit voorbeeld ziet u een antwoord van de aanmeldingsservice van het Microsoft Entra ID-account:

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

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

Stap 3: Geef het JWT-token op in de autorisatieheader van aanvragen

Wanneer u een API-aanvraag naar de Bot Verbinding maken or-service verzendt, geeft u het toegangstoken op in de Authorization header van de aanvraag met behulp van deze indeling:

Authorization: Bearer ACCESS_TOKEN

Alle aanvragen die u naar de bot Verbinding maken orservice verzendt, moeten het toegangstoken in de Authorization header bevatten. Als het token correct is gevormd, niet is verlopen en is gegenereerd door de aanmeldingsservice van het Microsoft Entra ID-account, autoriseert de Bot Verbinding maken or-service de aanvraag. Er worden extra controles uitgevoerd om ervoor te zorgen dat het token deel uitmaakt van de bot die de aanvraag heeft verzonden.

In het volgende voorbeeld ziet u hoe u het toegangstoken opgeeft in de Authorization header van de aanvraag.

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

(JSON-serialized Activity message goes here)

Belangrijk

Geef alleen het JWT-token op in de Authorization header van aanvragen die u naar de bot Verbinding maken orservice verzendt. Verzend het token niet via onbeveiligde kanalen en neem het niet op in HTTP-aanvragen die u naar andere services verzendt. Het JWT-token dat u van de aanmeldingsservice voor het Microsoft Entra ID-account verkrijgt, is vergelijkbaar met een wachtwoord en moet zorgvuldig worden afgehandeld. Iedereen die het token bezit, kan dit gebruiken om bewerkingen uit te voeren namens uw bot.

Bot naar Verbinding maken or: voorbeeld van JWT-onderdelen

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
}

Notitie

De werkelijke velden kunnen in de praktijk verschillen. Maak en valideer alle JWT-tokens zoals hierboven is opgegeven.

Aanvragen van de Bot Verbinding maken or service verifiëren bij uw bot

Wanneer de bot Verbinding maken orservice een aanvraag naar uw bot verzendt, wordt een ondertekend JWT-token opgegeven in de Authorization header van de aanvraag. Uw bot kan aanroepen van de Bot Verbinding maken or-service verifiëren door de echtheid van het ondertekende JWT-token te verifiëren.

Oproepen van de Bot Verbinding maken or-service verifiëren:

  1. Uw bot haalt het JWT-token op uit de autorisatieheader in aanvragen die zijn verzonden vanuit de Bot Verbinding maken or-service.
  2. Uw bot haalt het OpenID-metagegevensdocument op voor de Bot Verbinding maken or-service.
  3. Uw bot haalt de lijst met geldige ondertekeningssleutels op uit het document.
  4. Uw bot verifieert de echtheid van het JWT-token.

Stap 2: Het OpenID-metagegevensdocument ophalen

Het OpenID-metagegevensdocument geeft de locatie op van een tweede document met de geldige ondertekeningssleutels van de Bot Verbinding maken or-service. Als u het OpenID-metagegevensdocument wilt ophalen, voert u deze aanvraag uit via HTTPS:

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

Tip

Dit is een statische URL die u in uw toepassing kunt coderen.

In het volgende voorbeeld ziet u een OpenID-metagegevensdocument dat wordt geretourneerd als reactie op de GET aanvraag. De jwks_uri eigenschap geeft de locatie op van het document dat de geldige ondertekeningssleutels van de Bot Verbinding maken or-service bevat.

{
    "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"
    ]
}

Stap 3: De lijst met geldige ondertekeningssleutels ophalen

Als u de lijst met geldige ondertekeningssleutels wilt ophalen, verzendt u een GET aanvraag via HTTPS naar de URL die is opgegeven door de jwks_uri eigenschap in het OpenID-metagegevensdocument. Voorbeeld:

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

De hoofdtekst van het antwoord geeft het document op in de JWK-indeling , maar bevat ook een extra eigenschap voor elke sleutel: endorsements.

Tip

De lijst met sleutels is stabiel en kan in de cache worden opgeslagen, maar er kunnen op elk gewenst moment nieuwe sleutels worden toegevoegd. Om ervoor te zorgen dat uw bot een up-to-date kopie van het document heeft voordat deze sleutels worden gebruikt, moeten alle botexemplaren de lokale cache van het document minstens eenmaal per 24 uur vernieuwen.

De endorsements eigenschap binnen elke sleutel bevat een of meer goedkeuringstekenreeksen die u kunt gebruiken om te controleren of de kanaal-id die is opgegeven in de channelId eigenschap binnen het activiteitsobject van de binnenkomende aanvraag, authentiek is. De lijst met kanaal-id's waarvoor goedkeuringen zijn vereist, kan binnen elke bot worden geconfigureerd. Standaard is dit de lijst met alle gepubliceerde kanaal-id's, hoewel botontwikkelaars geselecteerde kanaal-id-waarden op beide manieren kunnen overschrijven.

Stap 4: Het JWT-token verifiëren

Als u de echtheid van het token wilt controleren dat is verzonden door de Bot Verbinding maken or-service, moet u het token extraheren uit de Authorization header van de aanvraag, het token parseren, de inhoud ervan controleren en de handtekening verifiëren.

JWT-parseringsbibliotheken zijn beschikbaar voor veel platforms en implementeren veilig en betrouwbaar parseren voor JWT-tokens, hoewel u deze bibliotheken doorgaans moet configureren om te vereisen dat bepaalde kenmerken van het token (de uitgever, doelgroep, enzovoort) de juiste waarden bevatten. Bij het parseren van het token moet u de parseringsbibliotheek configureren of uw eigen validatie schrijven om ervoor te zorgen dat het token voldoet aan deze vereisten:

  1. Het token is verzonden in de HTTP-header Authorization met het bearer-schema.
  2. Het token is een geldige JSON die voldoet aan de JWT-standaard.
  3. Het token bevat een 'issuer'-claim met de waarde van https://api.botframework.com.
  4. Het token bevat een doelgroepclaim met een waarde die gelijk is aan de Microsoft App-id van de bot.
  5. Het token valt binnen de geldigheidsperiode. Industriestandaard klokverschil is 5 minuten.
  6. Het token heeft een geldige cryptografische handtekening, met een sleutel die wordt vermeld in het Document OpenID-sleutels die is opgehaald in stap 3, met behulp van het ondertekeningsalgoritme dat is opgegeven in de id_token_signing_alg_values_supported eigenschap van het document Open ID Metadata dat is opgehaald in stap 2.
  7. Het token bevat een serviceUrl-claim met waarde die overeenkomt met de serviceUrl eigenschap in de hoofdmap van het activiteitsobject van de binnenkomende aanvraag.

Als goedkeuring voor een kanaal-id is vereist:

  • U moet vereisen dat elk Activity object dat met die kanaal-id naar uw bot wordt verzonden, vergezeld gaat van een JWT-token dat is ondertekend met een goedkeuring voor dat kanaal.
  • Als de goedkeuring niet aanwezig is, moet uw bot de aanvraag afwijzen door een HTTP 403-statuscode (Verboden) te retourneren.

Belangrijk

Al deze vereisten zijn belangrijk, met name vereisten 4 en 6. Als u AL deze verificatievereisten niet implementeert, blijft de bot open voor aanvallen waardoor de bot het JWT-token kan onthullen.

Implementeerfuncties mogen geen manier beschikbaar maken om validatie van het JWT-token uit te schakelen dat naar de bot wordt verzonden.

Verbinding maken or bot: voorbeeld van JWT-onderdelen

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
}

Notitie

De werkelijke velden kunnen in de praktijk verschillen. Maak en valideer alle JWT-tokens zoals hierboven is opgegeven.

Aanvragen van de Bot Framework Emulator verifiëren bij uw bot

Bot Framework Emulator is een bureaubladhulpprogramma dat u kunt gebruiken om de functionaliteit van uw bot te testen. Hoewel de Bot Framework Emulator dezelfde verificatietechnologieën gebruikt als hierboven beschreven, kan deze de echte Bot Verbinding maken or-service niet imiteren. In plaats daarvan wordt de Microsoft App-id en het Microsoft App-wachtwoord gebruikt die u opgeeft wanneer u de emulator verbindt met uw bot om tokens te maken die identiek zijn aan de tokens die door de bot worden gemaakt. Wanneer de emulator een aanvraag naar uw bot verzendt, geeft deze het JWT-token op in de Authorization header van de aanvraag, in wezen met behulp van de eigen referenties van de bot om de aanvraag te verifiëren.

Als u een verificatiebibliotheek implementeert en aanvragen van de Bot Framework Emulator wilt accepteren, moet u dit aanvullende verificatiepad toevoegen. Het pad is structureel vergelijkbaar met het Verbinding maken or -> Botverificatiepad, maar maakt gebruik van het OpenID-document van MSA in plaats van het OpenID-document van de Bot Verbinding maken or.

Oproepen verifiëren vanuit de Bot Framework Emulator:

  1. Uw bot haalt het JWT-token op uit de autorisatieheader in aanvragen die zijn verzonden vanuit de Bot Framework Emulator.
  2. Uw bot haalt het OpenID-metagegevensdocument op voor de Bot Verbinding maken or-service.
  3. Uw bot haalt de lijst met geldige ondertekeningssleutels op uit het document.
  4. Uw bot verifieert de echtheid van het JWT-token.

Stap 2: het MSA OpenID-metagegevensdocument ophalen

Het OpenID-metagegevensdocument geeft de locatie op van een tweede document met de geldige ondertekeningssleutels. Als u het MSA OpenID-metagegevensdocument wilt ophalen, verzendt u deze aanvraag via HTTPS:

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

In het volgende voorbeeld ziet u een OpenID-metagegevensdocument dat wordt geretourneerd als reactie op de GET aanvraag. De jwks_uri eigenschap geeft de locatie op van het document dat de geldige ondertekeningssleutels bevat.

{
    "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",
    ...
}

Stap 3: De lijst met geldige ondertekeningssleutels ophalen

Als u de lijst met geldige ondertekeningssleutels wilt ophalen, verzendt u een GET aanvraag via HTTPS naar de URL die is opgegeven door de jwks_uri eigenschap in het OpenID-metagegevensdocument. Voorbeeld:

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

De hoofdtekst van het antwoord geeft het document op in de JWK-indeling.

Stap 4: Het JWT-token verifiëren

Als u de echtheid van het token wilt controleren dat door de emulator is verzonden, moet u het token extraheren uit de Authorization header van de aanvraag, het token parseren, de inhoud controleren en de handtekening controleren.

JWT-parseringsbibliotheken zijn beschikbaar voor veel platforms en implementeren veilig en betrouwbaar parseren voor JWT-tokens, hoewel u deze bibliotheken doorgaans moet configureren om te vereisen dat bepaalde kenmerken van het token (de uitgever, doelgroep, enzovoort) de juiste waarden bevatten. Bij het parseren van het token moet u de parseringsbibliotheek configureren of uw eigen validatie schrijven om ervoor te zorgen dat het token voldoet aan deze vereisten:

  1. Het token is verzonden in de HTTP-header Authorization met het bearer-schema.
  2. Het token is een geldige JSON die voldoet aan de JWT-standaard.
  3. Het token bevat een 'issuer'-claim met een van de gemarkeerde waarden voor niet-gouvernementele gevallen. Als u controleert op beide verlenerwaarden, controleert u of u zowel de waarden van het beveiligingsprotocol v3.1 als v3.2-verlener controleert.
  4. Het token bevat een doelgroepclaim met een waarde die gelijk is aan de Microsoft App-id van de bot.
  5. De emulator verzendt, afhankelijk van de versie, de AppId via de appid-claim (versie 1) of de claim van de geautoriseerde partij (versie 2).
  6. Het token valt binnen de geldigheidsperiode. Industriestandaard klokverschil is 5 minuten.
  7. Het token heeft een geldige cryptografische handtekening met een sleutel die wordt vermeld in het Document OpenID-sleutels die is opgehaald in stap 3.

Notitie

Vereiste 5 is een specifiek voor het verificatiepad van de emulator.

Als het token niet aan al deze vereisten voldoet, moet uw bot de aanvraag beëindigen door een HTTP 403-statuscode (Verboden) te retourneren.

Belangrijk

Al deze vereisten zijn belangrijk, met name vereisten 4 en 7. Als u AL deze verificatievereisten niet implementeert, blijft de bot open voor aanvallen waardoor de bot het JWT-token kan onthullen.

Emulator naar bot: voorbeeld van JWT-onderdelen

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
}

Notitie

De werkelijke velden kunnen in de praktijk verschillen. Maak en valideer alle JWT-tokens zoals hierboven is opgegeven.

Wijzigingen in beveiligingsprotocol

Bot naar Verbinding maken orverificatie

OAuth-aanmeldings-URL

Protocolversie Geldige waarde
v3.1 & v3.2 https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token

OAuth-bereik

Protocolversie Geldige waarde
v3.1 & v3.2 https://api.botframework.com/.default

Verbinding maken or botverificatie

OpenID-metagegevensdocument

Protocolversie Geldige waarde
v3.1 & v3.2 https://login.botframework.com/v1/.well-known/openidconfiguration

JWT Issuer

Protocolversie Geldige waarde
v3.1 & v3.2 https://api.botframework.com

Emulator naar botverificatie

OAuth-aanmeldings-URL

Protocolversie Geldige waarde
v3.1 & v3.2 https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token

OAuth-bereik

Protocolversie Geldige waarde
v3.1 & v3.2 De Microsoft App-id + van uw bot /.default

JWT-doelgroep

Protocolversie Geldige waarde
v3.1 & v3.2 De Microsoft App-id van uw bot

JWT Issuer

Protocolversie Geldige waarde
v3.1 1.0 https://sts.windows.net/d6d49420-f39b-4df7-a1dc-d59a935871db/
v3.1 2.0 https://login.microsoftonline.com/d6d49420-f39b-4df7-a1dc-d59a935871db/v2.0
v3.2 1.0 https://sts.windows.net/f8cdef31-a31e-4b4a-93e4-5f571e91255a/
v3.2 2.0 https://login.microsoftonline.com/f8cdef31-a31e-4b4a-93e4-5f571e91255a/v2.0

Zie ook de gemarkeerde waarden voor niet-gouvernementele gevallen.

OpenID-metagegevensdocument

Protocolversie Geldige waarde
v3.1 & v3.2 https://login.microsoftonline.com/botframework.com/v2.0/.well-known/openid-configuration

Aanvullende bronnen