Autentisering med Bot Anslut or-API:et

  • Artikel

Roboten kommunicerar med tjänsten Bot Anslut or med HTTP via en skyddad kanal (SSL/TLS). När roboten skickar en begäran till Anslut eller-tjänsten måste den innehålla information som Anslut eller-tjänsten kan använda för att verifiera dess identitet. På samma sätt måste den innehålla information som roboten kan använda för att verifiera sin identitet när tjänsten Anslut eller skickar en begäran till din robot. Den här artikeln beskriver de autentiseringstekniker och krav för autentisering på tjänstnivå som sker mellan en robot och bot Anslut eller-tjänsten. Om du skriver en egen autentiseringskod måste du implementera de säkerhetsprocedurer som beskrivs i den här artikeln för att roboten ska kunna utbyta meddelanden med bot-Anslut eller-tjänsten.

Viktigt!

Om du skriver en egen autentiseringskod är det viktigt att du implementerar alla säkerhetsprocedurer korrekt. Genom att implementera alla steg i den här artikeln kan du minska risken för att en angripare kan läsa meddelanden som skickas till din robot, skicka meddelanden som personifierar din robot och stjäla hemliga nycklar.

Om du använder Bot Framework SDK behöver du inte implementera de säkerhetsprocedurer som beskrivs i den här artikeln, eftersom SDK:t automatiskt gör det åt dig. Konfigurera bara projektet med det app-ID och lösenord som du fick för din robot under registreringen så hanterar SDK resten.

Autentiseringsteknologier

Fyra autentiseringstekniker används för att upprätta förtroende mellan en robot och robotens Anslut eller:

Teknik beskrivning
SSL/TLS SSL/TLS används för alla tjänst-till-tjänst-anslutningar. X.509v3 certifikat används för att fastställa identiteten för alla HTTPS-tjänster. Klienter bör alltid inspektera tjänstcertifikat för att säkerställa att de är betrodda och giltiga. (Klientcertifikat används INTE som en del av det här schemat.)
OAuth 2.0 OAuth 2.0 använder inloggningstjänsten för Microsoft Entra-ID-konto för att generera en säker token som en robot kan använda för att skicka meddelanden. Den här token är en tjänst-till-tjänst-token. ingen användarinloggning krävs.
JSON-webbtoken (JWT) JSON-webbtoken används för att koda token som skickas till och från roboten. Klienter bör fullständigt verifiera alla JWT-token som de får, enligt de krav som beskrivs i den här artikeln.
OpenID-metadata Bot Anslut or-tjänsten publicerar en lista över giltiga token som används för att signera sina egna JWT-token till OpenID-metadata på en välkänd, statisk slutpunkt.

Den här artikeln beskriver hur du använder dessa tekniker via standard-HTTPS och JSON. Inga särskilda SDK:er krävs, även om du kanske tycker att hjälparna för OpenID och andra är användbara.

Autentisera begäranden från roboten till robotens Anslut eller-tjänst

Om du vill kommunicera med bot-Anslut eller-tjänsten måste du ange en åtkomsttoken i huvudet för Authorization varje API-begäran med det här formatet:

Authorization: Bearer ACCESS_TOKEN

Så här hämtar och använder du en JWT-token för din robot:

  1. Roboten skickar en GET HTTP-begäran till MSA-inloggningstjänsten.
  2. Svaret från tjänsten innehåller den JWT-token som ska användas.
  3. Roboten innehåller den här JWT-token i auktoriseringshuvudet i begäranden till Bot Anslut or-tjänsten.

Steg 1: Begär en åtkomsttoken från inloggningstjänsten för Microsoft Entra-ID-konto

Viktigt!

Om du inte redan har gjort det måste du registrera din robot med Bot Framework för att få dess AppID och lösenord. Du behöver robotens app-ID och lösenord för att begära en åtkomsttoken.

Din robotidentitet kan hanteras i Azure på några olika sätt.

  • Som en användartilldelad hanterad identitet så att du inte behöver hantera robotens autentiseringsuppgifter själv.
  • Som en app för en enda klientorganisation .
  • Som en app för flera klientorganisationer .

Begär en åtkomsttoken baserat på robotens programtyp.

Om du vill begära en åtkomsttoken från inloggningstjänsten skickar du följande begäran och ersätter MICROSOFT-APP-ID och MICROSOFT-APP-PASSWORD med robotens AppID och lösenord som du fick när du registrerade din robot med Bot Service.

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

Steg 2: Hämta JWT-token från inloggningstjänstens svar för Microsoft Entra-ID-kontot

Om ditt program har godkänts av inloggningstjänsten anger JSON-svarstexten din åtkomsttoken, dess typ och förfallodatum (i sekunder).

När du lägger till token i Authorization rubriken för en begäran måste du använda det exakta värdet som anges i det här svaret– undvik inte eller koda inte tokenvärdet. Åtkomsttoken är giltig tills den upphör att gälla. För att förhindra att förfallodatum för token påverkar robotens prestanda kan du välja att cachelagrar och proaktivt uppdatera token.

Det här exemplet visar ett svar från inloggningstjänsten för Microsoft Entra-ID-konto:

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

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

Steg 3: Ange JWT-token i auktoriseringshuvudet för begäranden

När du skickar en API-begäran till bot-Anslut eller-tjänsten anger du åtkomsttoken i Authorization rubriken för begäran med det här formatet:

Authorization: Bearer ACCESS_TOKEN

Alla begäranden som du skickar till bot Anslut eller-tjänsten måste innehålla åtkomsttoken i Authorization rubriken. Om token har bildats korrekt, inte har upphört att gälla och genererades av inloggningstjänsten för Microsoft Entra-ID-kontot, godkänner bot Anslut or-tjänsten begäran. Ytterligare kontroller utförs för att säkerställa att token tillhör roboten som skickade begäran.

I följande exempel visas hur du anger åtkomsttoken i Authorization rubriken för begäran.

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

(JSON-serialized Activity message goes here)

Viktigt!

Ange bara JWT-token i Authorization rubriken för begäranden som du skickar till bot-Anslut eller-tjänsten. Skicka INTE token via oskyddade kanaler och ta INTE med den i HTTP-begäranden som du skickar till andra tjänster. Den JWT-token som du får från inloggningstjänsten för Microsoft Entra-ID-kontot är som ett lösenord och bör hanteras med stor försiktighet. Alla som har token kan använda den för att utföra åtgärder för din robot.

Robot till Anslut eller: exempel på JWT-komponenter

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
}

Kommentar

Faktiska fält kan variera i praktiken. Skapa och verifiera alla JWT-token enligt ovan.

Autentisera begäranden från bot-Anslut eller-tjänsten till din robot

När tjänsten Bot Anslut or skickar en begäran till roboten anger den en signerad JWT-token i Authorization rubriken för begäran. Roboten kan autentisera anrop från bot-Anslut eller-tjänsten genom att verifiera äktheten hos den signerade JWT-token.

Så här autentiserar du anrop från bot-Anslut eller-tjänsten:

  1. Roboten hämtar JWT-token från auktoriseringshuvudet i begäranden som skickas från Bot Anslut or-tjänsten.
  2. Roboten hämtar OpenID-metadatadokumentet för bot-Anslut eller-tjänsten.
  3. Din robot hämtar listan över giltiga signeringsnycklar från dokumentet.
  4. Roboten verifierar JWT-tokens äkthet.

Steg 2: Hämta dokumentet med OpenID-metadata

Dokumentet med OpenID-metadata anger platsen för ett andra dokument som listar bot-Anslut eller-tjänstens giltiga signeringsnycklar. Om du vill hämta openID-metadatadokumentet utfärdar du den här begäran via HTTPS:

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

Dricks

Det här är en statisk URL som du kan hårdkoda i ditt program.

I följande exempel visas ett OpenID-metadatadokument som returneras som svar på GET begäran. Egenskapen jwks_uri anger platsen för dokumentet som innehåller bot-Anslut eller-tjänstens giltiga signeringsnycklar.

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

Steg 3: Hämta listan över giltiga signeringsnycklar

Om du vill hämta listan över giltiga signeringsnycklar skickar du en GET begäran via HTTPS till den URL som anges av jwks_uri egenskapen i Dokumentet med OpenID-metadata. Till exempel:

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

Svarstexten anger dokumentet i JWK-format men innehåller även ytterligare en egenskap för varje nyckel: endorsements.

Dricks

Listan över nycklar är stabil och kan cachelagras, men nya nycklar kan läggas till när som helst. För att säkerställa att roboten har en uppdaterad kopia av dokumentet innan dessa nycklar används bör alla robotinstanser uppdatera sin lokala cache för dokumentet minst en gång var 24:e timme.

Egenskapen endorsements i varje nyckel innehåller en eller flera bekräftelsesträngar som du kan använda för att kontrollera att kanal-ID:t som anges i channelId egenskapen i aktivitetsobjektet för den inkommande begäran är autentisering. Listan över kanal-ID:t som kräver godkännanden kan konfigureras i varje robot. Som standard är det listan över alla publicerade kanal-ID:er, även om robotutvecklare kan åsidosätta valda kanal-ID-värden i båda riktningarna.

Steg 4: Verifiera JWT-token

För att verifiera äktheten för token som skickades av bot-Anslut eller-tjänsten måste du extrahera token från Authorization rubriken för begäran, parsa token, verifiera innehållet och verifiera dess signatur.

JWT-parsningsbibliotek är tillgängliga för många plattformar och de flesta implementerar säker och tillförlitlig parsning för JWT-token, även om du vanligtvis måste konfigurera dessa bibliotek så att vissa egenskaper för token (utfärdaren, målgruppen och så vidare) innehåller korrekta värden. När du parsar token måste du konfigurera parsningsbiblioteket eller skriva en egen validering för att säkerställa att token uppfyller följande krav:

  1. Token skickades i HTTP-huvudet med "Bearer"- Authorization schemat.
  2. Token är giltig JSON som överensstämmer med JWT-standarden.
  3. Token innehåller ett "utfärdare"-anspråk med värdet https://api.botframework.com.
  4. Token innehåller ett "målgruppsanspråk" med ett värde som är lika med robotens Microsoft App-ID.
  5. Token är inom dess giltighetsperiod. Branschstandardens klocksnedställning är 5 minuter.
  6. Token har en giltig kryptografisk signatur med en nyckel som anges i dokumentet OpenID-nycklar som hämtades i steg 3 med hjälp av signeringsalgoritmen id_token_signing_alg_values_supported som anges i egenskapen för dokumentet Öppna ID-metadata som hämtades i steg 2.
  7. Token innehåller ett "serviceUrl"-anspråk med ett värde som matchar serviceUrl egenskapen i roten för aktivitetsobjektet för den inkommande begäran.

Om godkännande för ett kanal-ID krävs:

  • Du bör kräva att alla Activity objekt som skickas till din robot med kanal-ID:t åtföljs av en JWT-token som är signerad med ett godkännande för kanalen.
  • Om bekräftelsen inte finns bör roboten avvisa begäran genom att returnera statuskoden HTTP 403 (förbjuden).

Viktigt!

Alla dessa krav är viktiga, särskilt kraven 4 och 6. Om du inte implementerar alla dessa verifieringskrav blir roboten öppen för attacker som kan leda till att roboten avslöjar sin JWT-token.

Implementerare bör inte exponera ett sätt att inaktivera valideringen av JWT-token som skickas till roboten.

Anslut eller till robot: exempel på JWT-komponenter

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
}

Kommentar

Faktiska fält kan variera i praktiken. Skapa och verifiera alla JWT-token enligt ovan.

Autentisera begäranden från Bot Framework-emulatorn till din robot

Bot Framework-emulatorn är ett skrivbordsverktyg som du kan använda för att testa funktionerna i din robot. Även om Bot Framework-emulatorn använder samma autentiseringstekniker som beskrivs ovan kan den inte personifiera den verkliga bot-Anslut eller-tjänsten. I stället används det Microsoft App-ID och Microsoft App Password som du anger när du ansluter emulatorn till din robot för att skapa token som är identiska med dem som roboten skapar. När emulatorn skickar en begäran till din robot, anger den JWT-token i Authorization rubriken för begäran , i huvudsak med hjälp av robotens egna autentiseringsuppgifter för att autentisera begäran.

Om du implementerar ett autentiseringsbibliotek och vill acceptera begäranden från Bot Framework-emulatorn måste du lägga till den här ytterligare verifieringssökvägen. Sökvägen är strukturellt lik den Anslut eller –> robotverifieringssökväg, men den använder MSA:s OpenID-dokument i stället för boten Anslut eller OpenID-dokument.

Så här autentiserar du anrop från Bot Framework-emulatorn:

  1. Roboten hämtar JWT-token från auktoriseringshuvudet i begäranden som skickas från Bot Framework-emulatorn.
  2. Roboten hämtar OpenID-metadatadokumentet för bot-Anslut eller-tjänsten.
  3. Din robot hämtar listan över giltiga signeringsnycklar från dokumentet.
  4. Roboten verifierar JWT-tokens äkthet.

Steg 2: Hämta dokumentet med MSA OpenID-metadata

Dokumentet med OpenID-metadata anger platsen för ett andra dokument som visar en lista över giltiga signeringsnycklar. Om du vill hämta dokumentet med MSA OpenID-metadata utfärdar du den här begäran via HTTPS:

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

I följande exempel visas ett OpenID-metadatadokument som returneras som svar på GET begäran. Egenskapen jwks_uri anger platsen för dokumentet som innehåller giltiga signeringsnycklar.

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

Steg 3: Hämta listan över giltiga signeringsnycklar

Om du vill hämta listan över giltiga signeringsnycklar skickar du en GET begäran via HTTPS till den URL som anges av jwks_uri egenskapen i Dokumentet med OpenID-metadata. Till exempel:

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

Svarstexten anger dokumentet i JWK-format.

Steg 4: Verifiera JWT-token

För att verifiera äktheten för token som skickades av emulatorn måste du extrahera token från Authorization rubriken för begäran, parsa token, verifiera innehållet och verifiera dess signatur.

JWT-parsningsbibliotek är tillgängliga för många plattformar och de flesta implementerar säker och tillförlitlig parsning för JWT-token, även om du vanligtvis måste konfigurera dessa bibliotek så att vissa egenskaper för token (utfärdaren, målgruppen och så vidare) innehåller korrekta värden. När du parsar token måste du konfigurera parsningsbiblioteket eller skriva en egen validering för att säkerställa att token uppfyller följande krav:

  1. Token skickades i HTTP-huvudet med "Bearer"- Authorization schemat.
  2. Token är giltig JSON som överensstämmer med JWT-standarden.
  3. Token innehåller ett "utfärdare"-anspråk med ett av de markerade värdena för icke-statliga fall. Om du söker efter båda utfärdarvärdena kontrollerar du att du söker efter både utfärdarvärdena för säkerhetsprotokoll v3.1 och v3.2.
  4. Token innehåller ett "målgruppsanspråk" med ett värde som är lika med robotens Microsoft App-ID.
  5. Emulatorn skickar, beroende på version, AppId via appid-anspråket (version 1) eller det auktoriserade partanspråket (version 2).
  6. Token är inom dess giltighetsperiod. Branschstandardens klocksnedställning är 5 minuter.
  7. Token har en giltig kryptografisk signatur med en nyckel som anges i dokumentet OpenID-nycklar som hämtades i steg 3.

Kommentar

Krav 5 är specifikt för verifieringssökvägen för emulatorn.

Om token inte uppfyller alla dessa krav bör roboten avsluta begäran genom att returnera statuskoden HTTP 403 (förbjuden).

Viktigt!

Alla dessa krav är viktiga, särskilt kraven 4 och 7. Om du inte implementerar alla dessa verifieringskrav blir roboten öppen för attacker som kan leda till att roboten avslöjar sin JWT-token.

Emulator till robot: exempel på JWT-komponenter

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
}

Kommentar

Faktiska fält kan variera i praktiken. Skapa och verifiera alla JWT-token enligt ovan.

Ändringar i säkerhetsprotokoll

Robot för Anslut eller autentisering

Inloggnings-URL för OAuth

Protokollversion Giltigt värde
v3.1 & v3.2 https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token

OAuth-omfång

Protokollversion Giltigt värde
v3.1 & v3.2 https://api.botframework.com/.default

Anslut eller till robotautentisering

OpenID-metadatadokument

Protokollversion Giltigt värde
v3.1 & v3.2 https://login.botframework.com/v1/.well-known/openidconfiguration

JWT-utfärdare

Protokollversion Giltigt värde
v3.1 & v3.2 https://api.botframework.com

Emulator till robotautentisering

Inloggnings-URL för OAuth

Protokollversion Giltigt värde
v3.1 & v3.2 https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token

OAuth-omfång

Protokollversion Giltigt värde
v3.1 & v3.2 Robotens Microsoft App-ID + /.default

JWT-målgrupp

Protokollversion Giltigt värde
v3.1 & v3.2 Robotens Microsoft App-ID

JWT-utfärdare

Protokollversion Giltigt värde
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

Se även de markerade värdena för icke-statliga ärenden.

OpenID-metadatadokument

Protokollversion Giltigt värde
v3.1 & v3.2 https://login.microsoftonline.com/botframework.com/v2.0/.well-known/openid-configuration

Ytterligare resurser