Hitelesítés a Bot Csatlakozás or API-val

  • Cikk

A robot http használatával kommunikál a Bot Csatlakozás or szolgáltatással egy biztonságos csatornán keresztül (SSL/TLS). Amikor a robot kérést küld a Csatlakozás or szolgáltatásnak, tartalmaznia kell azokat az információkat, amelyeket a Csatlakozás or szolgáltatás felhasználhat az identitásának ellenőrzéséhez. Hasonlóképpen, amikor a Csatlakozás or szolgáltatás kérést küld a robotnak, tartalmaznia kell azokat az információkat, amelyeket a robot felhasználhat az identitásának ellenőrzéséhez. Ez a cikk a robot és a Bot Csatlakozás or szolgáltatás közötti szolgáltatásszintű hitelesítés hitelesítési technológiáit és követelményeit ismerteti. Ha saját hitelesítési kódot ír, az ebben a cikkben ismertetett biztonsági eljárásokat kell implementálnia, hogy a robot üzeneteket válthasson a Bot Csatlakozás or szolgáltatással.

Fontos

Ha saját hitelesítési kódot ír, fontos, hogy minden biztonsági eljárást megfelelően implementáljon. A cikk összes lépésének végrehajtásával csökkentheti annak kockázatát, hogy a támadó képes olvasni a robotnak küldött üzeneteket, üzeneteket küldhet a robotnak, és titkos kulcsokat lophat el.

Ha a Bot Framework SDK-t használja, nem kell implementálnia a cikkben ismertetett biztonsági eljárásokat, mert az SDK automatikusan elvégzi Az Ön számára. Egyszerűen konfigurálja a projektet a robothoz a regisztráció során beszerzett alkalmazásazonosítóval és jelszóval, a többit pedig az SDK fogja kezelni.

Hitelesítési technológiák

A robot és a Robot Csatlakozás or közötti bizalom kialakításához négy hitelesítési technológia használható:

Technológia Leírás
SSL/TLS Az SSL/TLS minden szolgáltatás–szolgáltatás kapcsolathoz használható. X.509v3 a tanúsítványok az összes HTTPS-szolgáltatás identitásának megállapítására szolgálnak. Az ügyfeleknek mindig meg kell vizsgálniuk a szolgáltatástanúsítványokat, hogy biztosan megbízhatóak és érvényesek legyenek. (Az ügyféltanúsítványok nem használhatók a séma részeként.)
OAuth 2.0 Az OAuth 2.0 a Microsoft Entra ID-fiók bejelentkezési szolgáltatásával hoz létre egy biztonságos jogkivonatot, amellyel a robot üzeneteket küldhet. Ez a jogkivonat szolgáltatásközi jogkivonat; nincs szükség felhasználói bejelentkezésre.
JSON webes jogkivonat (JWT) A JSON webes jogkivonatok a robotnak küldött és onnan küldött jogkivonatok kódolására szolgálnak. Az ügyfeleknek teljes mértékben ellenőrizniük kell az általuk kapott JWT-jogkivonatokat a cikkben ismertetett követelményeknek megfelelően.
OpenID-metaadatok A Bot Csatlakozás or szolgáltatás közzéteszi azoknak az érvényes jogkivonatoknak a listáját, amelyekkel saját JWT-jogkivonatokat ír alá az OpenID-metaadatokhoz egy jól ismert, statikus végponton.

Ez a cikk bemutatja, hogyan használhatja ezeket a technológiákat szabványos HTTPS-en és JSON-on keresztül. Nincs szükség speciális SDK-kra, bár előfordulhat, hogy az OpenID és mások segítői hasznosak.

A robottól a Bot Csatlakozás or szolgáltatásba irányuló kérések hitelesítése

A Bot Csatlakozás or szolgáltatással való kommunikációhoz meg kell adnia egy hozzáférési jogkivonatot az Authorization egyes API-kérések fejlécében az alábbi formátumban:

Authorization: Bearer ACCESS_TOKEN

JWT-jogkivonat beszerzése és használata a robothoz:

  1. A robot GET HTTP-kérést küld az MSA bejelentkezési szolgáltatásnak.
  2. A szolgáltatás válasza tartalmazza a használni kívánt JWT-jogkivonatot.
  3. A robot ezt a JWT-jogkivonatot tartalmazza az engedélyezési fejlécben a Bot Csatlakozás or szolgáltatáshoz érkező kérésekben.

1. lépés: Hozzáférési jogkivonat kérése a Microsoft Entra ID-fiók bejelentkezési szolgáltatásából

Fontos

Ha még nem tette meg, regisztrálnia kell a robotot a Bot Frameworkben az AppID és a jelszó beszerzéséhez. Hozzáférési jogkivonat kéréséhez szüksége van a robot alkalmazásazonosítójára és jelszavára.

A robot identitása többféleképpen kezelhető az Azure-ban.

  • Felhasználó által hozzárendelt felügyelt identitásként, hogy önnek ne kelljen saját maga kezelnie a robot hitelesítő adatait.
  • Egybérlős alkalmazásként.
  • Több-bérlős alkalmazásként.

Hozzáférési jogkivonat kérése a robot alkalmazástípusa alapján.

Ha hozzáférési jogkivonatot szeretne kérni a bejelentkezési szolgáltatástól, adja ki a következő kérést, és cserélje le a MICROSOFT-APP-ID és a MICROSOFT-APP-PASSWORD azonosítót a robot AppID azonosítójára és jelszavára, amelyet akkor kapott, amikor regisztrálta a robotot a Bot Service-ben.

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

2. lépés: A JWT-jogkivonat beszerzése a Microsoft Entra ID-fiók bejelentkezési szolgáltatás válaszából

Ha az alkalmazást a bejelentkezési szolgáltatás engedélyezi, a JSON válasz törzse megadja a hozzáférési jogkivonatot, annak típusát és lejáratát (másodpercben).

Amikor hozzáadja a jogkivonatot Authorization egy kérés fejlécéhez, a válaszban megadott pontos értéket kell használnia – ne lépjen ki a jogkivonatból, és ne kódolja a jogkivonat értékét. A hozzáférési jogkivonat a lejáratáig érvényes. Annak érdekében, hogy a jogkivonat lejárata ne befolyásolja a robot teljesítményét, dönthet úgy, hogy gyorsítótárazza és proaktív módon frissítse a jogkivonatot.

Ez a példa a Microsoft Entra ID-fiók bejelentkezési szolgáltatásának válaszát mutatja be:

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

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

3. lépés: A JWT-jogkivonat megadása a kérelmek engedélyezési fejlécében

Amikor API-kérést küld a Bot Csatlakozás or szolgáltatásnak, adja meg a hozzáférési jogkivonatot a Authorization kérés fejlécében az alábbi formátumban:

Authorization: Bearer ACCESS_TOKEN

A Bot Csatlakozás or szolgáltatásnak küldött összes kérésnek tartalmaznia kell a hozzáférési jogkivonatot a Authorization fejlécben. Ha a jogkivonat megfelelően van kialakítva, nem járt le, és a Microsoft Entra ID-fiók bejelentkezési szolgáltatása hozta létre, a Bot Csatlakozás or szolgáltatás engedélyezi a kérést. A rendszer további ellenőrzéseket végez annak érdekében, hogy a jogkivonat a kérést küldő roboté legyen.

Az alábbi példa bemutatja, hogyan adhatja meg a hozzáférési jogkivonatot a Authorization kérés fejlécében.

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

(JSON-serialized Activity message goes here)

Fontos

Csak a Bot Csatlakozás or szolgáltatásnak küldött kérések fejlécében Authorization adja meg a JWT-jogkivonatot. Ne küldje el a jogkivonatot nem biztonságos csatornákon keresztül, és NE vegye fel a más szolgáltatásoknak küldött HTTP-kérelmekbe. A Microsoft Entra ID-fiók bejelentkezési szolgáltatásából beszerzett JWT-jogkivonat olyan, mint egy jelszó, és nagy körültekintéssel kell kezelni. Bárki, aki rendelkezik a jogkivonattal, használhatja arra, hogy műveleteket hajtson végre a robot nevében.

Robot a Csatlakozás orhoz: példa JWT-összetevőkre

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
}

Megjegyzés:

A tényleges mezők a gyakorlatban eltérhetnek. Hozza létre és ellenőrizze az összes JWT-jogkivonatot a fent megadott módon.

A Robot Csatlakozás or szolgáltatásból a robotra irányuló kérések hitelesítése

Amikor a Bot Csatlakozás or szolgáltatás kérést küld a robotnak, egy aláírt JWT-jogkivonatot ad meg a Authorization kérés fejlécében. A robot az aláírt JWT-jogkivonat hitelességének ellenőrzésével hitelesítheti a Bot Csatlakozás or szolgáltatásból érkező hívásokat.

A Bot Csatlakozás or szolgáltatásból érkező hívások hitelesítése:

  1. A robot lekéri a JWT-jogkivonatot az engedélyezési fejlécből a Bot Csatlakozás or szolgáltatásból küldött kérelmekben.
  2. A robot lekéri a Bot Csatlakozás or szolgáltatás OpenID metaadat-dokumentumát.
  3. A robot lekéri az érvényes aláírókulcsok listáját a dokumentumból.
  4. A robot ellenőrzi a JWT-jogkivonat hitelességét.

2. lépés: Az OpenID metaadat-dokumentumának lekérése

Az OpenID metaadat-dokumentum egy második dokumentum helyét adja meg, amely felsorolja a Bot Csatlakozás or szolgáltatás érvényes aláírókulcsait. Az OpenID metaadat-dokumentum lekéréséhez adja ki ezt a kérést HTTPS-en keresztül:

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

Tipp.

Ez egy statikus URL- cím, amelyet az alkalmazásba kódolhat.

Az alábbi példa egy OpenID metaadat-dokumentumot mutat be, amelyet a rendszer a GET kérésre adott válaszként ad vissza. A jwks_uri tulajdonság megadja a Bot Csatlakozás or szolgáltatás érvényes aláíró kulcsait tartalmazó dokumentum helyét.

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

3. lépés: Érvényes aláírókulcsok listájának lekérése

Az érvényes aláírókulcsok listájának lekéréséhez küldjön egy kérést GET HTTPS-en keresztül az jwks_uri OpenID metaadat-dokumentum tulajdonsága által megadott URL-címre. Például:

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

A válasz törzse JWK formátumban adja meg a dokumentumot, de minden kulcshoz tartalmaz egy további tulajdonságot is: endorsements.

Tipp.

A kulcsok listája stabil, és gyorsítótárazható, de bármikor új kulcsokat adhat hozzá. Annak érdekében, hogy a robot naprakész másolatot készítsen a dokumentumról a kulcsok használata előtt, minden robotpéldánynak legalább 24 óránként frissítenie kell a dokumentum helyi gyorsítótárát.

Az endorsements egyes kulcsokon belüli tulajdonság egy vagy több ellenőrző sztringet tartalmaz, amelyekkel ellenőrizheti, hogy a bejövő kérelem Tevékenység objektumában a tulajdonságban channelId megadott csatornaazonosító hiteles-e. A jóváhagyást igénylő csatornaazonosítók listája az egyes robotokon belül konfigurálható. Alapértelmezés szerint ez lesz az összes közzétett csatornaazonosító listája, bár a robotfejlesztők mindkét esetben felülbírálhatják a kiválasztott csatornaazonosító-értékeket.

4. lépés: A JWT-jogkivonat ellenőrzése

A Bot Csatlakozás or szolgáltatás által küldött jogkivonat hitelességének ellenőrzéséhez ki kell nyernie a jogkivonatot a Authorization kérés fejlécéből, elemeznie kell a jogkivonatot, ellenőriznie kell annak tartalmát, és ellenőriznie kell annak aláírását.

A JWT-elemzési kódtárak számos platformon elérhetők, és a legtöbben a JWT-jogkivonatok biztonságos és megbízható elemzését valósítják meg, bár ezeket a kódtárakat általában úgy kell konfigurálni, hogy a jogkivonat bizonyos jellemzői (kiállítója, célközönsége stb.) helyes értékeket tartalmazzanak. A jogkivonat elemzésekor konfigurálnia kell az elemzési könyvtárat, vagy meg kell írnia a saját érvényesítését, hogy a jogkivonat megfeleljen az alábbi követelményeknek:

  1. A jogkivonat a HTTP-fejlécben Authorization lett elküldve a "Bearer" sémával.
  2. A jogkivonat érvényes JSON, amely megfelel a JWT szabványnak.
  3. A jogkivonat egy "kiállító" jogcímet tartalmaz, amelynek értéke : https://api.botframework.com.
  4. A jogkivonat egy "célközönség" jogcímet tartalmaz, amelynek értéke megegyezik a robot Microsoft-alkalmazásazonosítójával.
  5. A jogkivonat az érvényességi időszakon belül van. Az iparági szabvány szerinti óraátállítás 5 perc.
  6. A jogkivonat érvényes titkosítási aláírással rendelkezik, amely a 3. lépésben lekért OpenID-kulcsok dokumentumában szerepel a 2. lépésben lekért Open ID Metaadat-dokumentum tulajdonságában id_token_signing_alg_values_supportedmegadott aláíró algoritmus használatával.
  7. A jogkivonat egy "serviceUrl" jogcímet tartalmaz, amelynek értéke megegyezik a serviceUrl bejövő kérelem Tevékenység objektumának gyökerénél lévő tulajdonsággal.

Ha szükség van egy csatornaazonosító jóváhagyására:

  • Meg kell követelnie, hogy a robotnak a csatornaazonosítóval küldött összes Activity objektumot egy JWT-jogkivonat kísérje, amely az adott csatornához tartozó jóváhagyással van aláírva.
  • Ha a jóváhagyás nem jelenik meg, a robotnak el kell utasítania a kérést egy HTTP 403 (Tiltott) állapotkód visszaadásával.

Fontos

Ezek a követelmények mind fontosak, különösen a 4. és a 6. követelmények. Ha nem hajtja végre ezeket az ellenőrzési követelményeket, a robot nyitva marad olyan támadásokra, amelyek miatt a robot közzéteheti A JWT-tokenjét.

A implementátorok nem tehetik közzé a robotnak küldött JWT-jogkivonat érvényesítésének letiltását.

Csatlakozás vagy a Botnak: példa JWT-összetevőkre

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
}

Megjegyzés:

A tényleges mezők a gyakorlatban eltérhetnek. Hozza létre és ellenőrizze az összes JWT-jogkivonatot a fent megadott módon.

A Bot Framework Emulatortól a robothoz érkező kérések hitelesítése

A Bot Framework Emulator egy asztali eszköz, amellyel tesztelheti a robot funkcióit. Bár a Bot Framework Emulator ugyanazokat a hitelesítési technológiákat használja, mint korábban, nem tudja megszemélyesíteni a valódi Bot Csatlakozás or szolgáltatást. Ehelyett az Emulátor robothoz való csatlakoztatásakor megadott Microsoft-alkalmazásazonosítót és Microsoft-alkalmazásjelszót használja a robottal azonos jogkivonatok létrehozásához. Amikor az Emulator kérést küld a robotnak, megadja a JWT-jogkivonatot a Authorization kérés fejlécében– lényegében a robot saját hitelesítő adataival hitelesíti a kérést.

Ha hitelesítési kódtárat implementál, és el szeretné fogadni a Bot Framework Emulatortól érkező kéréseket, hozzá kell adnia ezt a további ellenőrzési útvonalat. Az elérési út szerkezetileg hasonló a Csatlakozás or –> Robot ellenőrzési útvonalához, de az MSA OpenID-dokumentumát használja a Bot Csatlakozás or OpenID-dokumentuma helyett.

A Bot Framework Emulator hívásainak hitelesítése:

  1. A robot lekéri a JWT-tokent az engedélyezési fejlécből a Bot Framework Emulatortól küldött kérelmekben.
  2. A robot lekéri a Bot Csatlakozás or szolgáltatás OpenID metaadat-dokumentumát.
  3. A robot lekéri az érvényes aláírókulcsok listáját a dokumentumból.
  4. A robot ellenőrzi a JWT-jogkivonat hitelességét.

2. lépés: Az MSA OpenID metaadat-dokumentumának lekérése

Az OpenID metaadat-dokumentum egy második dokumentum helyét adja meg, amely felsorolja az érvényes aláírókulcsokat. Az MSA OpenID metaadat-dokumentum lekéréséhez adja ki ezt a kérést HTTPS-en keresztül:

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

Az alábbi példa egy OpenID metaadat-dokumentumot mutat be, amelyet a rendszer a GET kérésre adott válaszként ad vissza. A jwks_uri tulajdonság az érvényes aláírókulcsokat tartalmazó dokumentum helyét adja meg.

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

3. lépés: Érvényes aláírókulcsok listájának lekérése

Az érvényes aláírókulcsok listájának lekéréséhez küldjön egy kérést GET HTTPS-en keresztül az jwks_uri OpenID metaadat-dokumentum tulajdonsága által megadott URL-címre. Például:

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

A válasz törzse JWK formátumban adja meg a dokumentumot.

4. lépés: A JWT-jogkivonat ellenőrzése

Az Emulator által küldött jogkivonat hitelességének ellenőrzéséhez ki kell nyernie a jogkivonatot a Authorization kérés fejlécéből, elemeznie kell a jogkivonatot, ellenőriznie kell annak tartalmát, és ellenőriznie kell az aláírását.

A JWT-elemzési kódtárak számos platformon elérhetők, és a legtöbben a JWT-jogkivonatok biztonságos és megbízható elemzését valósítják meg, bár ezeket a kódtárakat általában úgy kell konfigurálni, hogy a jogkivonat bizonyos jellemzői (kiállítója, célközönsége stb.) helyes értékeket tartalmazzanak. A jogkivonat elemzésekor konfigurálnia kell az elemzési könyvtárat, vagy meg kell írnia a saját érvényesítését, hogy a jogkivonat megfeleljen az alábbi követelményeknek:

  1. A jogkivonat a HTTP-fejlécben Authorization lett elküldve a "Bearer" sémával.
  2. A jogkivonat érvényes JSON, amely megfelel a JWT szabványnak.
  3. A jogkivonat egy "kiállító" jogcímet tartalmaz, amely a nem kormányzati esetek egyik kiemelt értékével rendelkezik. Mindkét kiállítói érték ellenőrzése biztosítja, hogy a biztonsági protokoll 3.1-s és 3.2-s kiállítói értékeit is ellenőrizze.
  4. A jogkivonat egy "célközönség" jogcímet tartalmaz, amelynek értéke megegyezik a robot Microsoft-alkalmazásazonosítójával.
  5. Az Emulator a verziótól függően az AppId-et az appid jogcímen (1. verzió) vagy a jogosult fél jogcímén (2. verzió) keresztül küldi el.
  6. A jogkivonat az érvényességi időszakon belül van. Az iparági szabvány szerinti óraátállítás 5 perc.
  7. A jogkivonat érvényes titkosítási aláírással rendelkezik, amely a 3. lépésben lekért OpenID-kulcsok dokumentumban szereplő kulccsal rendelkezik.

Megjegyzés:

Az 5. követelmény az Emulator ellenőrzési útvonalára jellemző.

Ha a jogkivonat nem felel meg az összes követelménynek, a robotnak le kell mondania a kérést egy HTTP 403 (Tiltott) állapotkód visszaadásával.

Fontos

Ezek a követelmények mind fontosak, különösen a 4. és a 7. követelmények. Ha nem hajtja végre ezeket az ellenőrzési követelményeket, a robot nyitva marad olyan támadásokra, amelyek miatt a robot közzéteheti A JWT-tokenjét.

Emulátor a robothoz: példa JWT-összetevőkre

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
}

Megjegyzés:

A tényleges mezők a gyakorlatban eltérhetnek. Hozza létre és ellenőrizze az összes JWT-jogkivonatot a fent megadott módon.

Biztonsági protokoll módosításai

Robot a Csatlakozás hitelesítéshez

OAuth bejelentkezési URL-cím

Protokollverzió Érvényes érték
v3.1 & v3.2 https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token

OAuth-hatókör

Protokollverzió Érvényes érték
v3.1 & v3.2 https://api.botframework.com/.default

robothitelesítés Csatlakozás or

OpenID metaadat-dokumentum

Protokollverzió Érvényes érték
v3.1 & v3.2 https://login.botframework.com/v1/.well-known/openidconfiguration

JWT-kiállító

Protokollverzió Érvényes érték
v3.1 & v3.2 https://api.botframework.com

Emulátor–robothitelesítés

OAuth bejelentkezési URL-cím

Protokollverzió Érvényes érték
v3.1 & v3.2 https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token

OAuth-hatókör

Protokollverzió Érvényes érték
v3.1 & v3.2 A robot Microsoft-alkalmazásazonosítója + /.default

JWT-célközönség

Protokollverzió Érvényes érték
v3.1 & v3.2 A robot Microsoft-alkalmazásazonosítója

JWT-kiállító

Protokollverzió Érvényes érték
3.1 1.0-s verzió https://sts.windows.net/d6d49420-f39b-4df7-a1dc-d59a935871db/
3.1 2.0-s verzió https://login.microsoftonline.com/d6d49420-f39b-4df7-a1dc-d59a935871db/v2.0
v3.2 1.0 https://sts.windows.net/f8cdef31-a31e-4b4a-93e4-5f571e91255a/
3.2 2.0-s verzió https://login.microsoftonline.com/f8cdef31-a31e-4b4a-93e4-5f571e91255a/v2.0

Lásd még a nem kormányzati esetek kiemelt értékeit .

OpenID metaadat-dokumentum

Protokollverzió Érvényes érték
v3.1 & v3.2 https://login.microsoftonline.com/botframework.com/v2.0/.well-known/openid-configuration

További információforrások