Ověřování pomocí rozhraní API Připojení oru robota

Článek
10/27/2023

Váš robot komunikuje se službou bot Připojení or pomocí protokolu HTTP přes zabezpečený kanál (SSL/TLS). Když robot odešle žádost službě Připojení or, musí obsahovat informace, které může služba Připojení or použít k ověření své identity. Podobně když služba Připojení or odešle žádost robotovi, musí obsahovat informace, které může robot použít k ověření své identity. Tento článek popisuje technologie ověřování a požadavky na ověřování na úrovni služby, které probíhá mezi robotem a službou robota Připojení or. Pokud píšete vlastní ověřovací kód, musíte implementovat postupy zabezpečení popsané v tomto článku, aby robot mohl vyměňovat zprávy se službou Robot Připojení or.

Důležité

Pokud píšete vlastní ověřovací kód, je důležité, abyste správně implementovali všechny bezpečnostní postupy. Implementací všech kroků v tomto článku můžete zmírnit riziko, že útočník dokáže číst zprávy odeslané robotovi, odesílat zprávy, které zosobňují robota, a ukrást tajné klíče.

Pokud používáte sadu SDK služby Bot Framework, nemusíte implementovat postupy zabezpečení popsané v tomto článku, protože sada SDK ji automaticky provede za vás. Jednoduše nakonfigurujte projekt s ID aplikace a heslem, které jste získali pro robota během registrace , a sada SDK zpracuje zbytek.

Technologií ověřování

K navázání důvěryhodnosti mezi robotem a Připojení orem robota se používají čtyři technologie ověřování:

Technologie	Popis
SSL/TLS	Protokol SSL/TLS se používá pro všechna připojení mezi službami. `X.509v3` certifikáty slouží k vytvoření identity všech služeb HTTPS. Klienti by měli vždy kontrolovat certifikáty služeb, aby měli jistotu, že jsou důvěryhodné a platné. (Klientské certifikáty se nepoužívají jako součást tohoto schématu.)
OAuth 2.0	OAuth 2.0 používá přihlašovací službu účtu Microsoft Entra ID k vygenerování zabezpečeného tokenu, který robot může použít k odesílání zpráv. Tento token je token typu service-to-service; Nevyžaduje se žádné přihlášení uživatele.
Webový token JSON (JWT)	Webové tokeny JSON slouží ke kódování tokenů odesílaných do a z robota. Klienti by měli plně ověřit všechny tokeny JWT, které obdrží, podle požadavků uvedených v tomto článku.
Metadata OpenID	Služba Bot Připojení or publikuje seznam platných tokenů, které používá k podepisování vlastních tokenů JWT k metadatům OpenID v dobře známém statickém koncovém bodu.

Tento článek popisuje, jak tyto technologie používat prostřednictvím standardního protokolu HTTPS a JSON. Nejsou vyžadovány žádné speciální sady SDK, i když možná zjistíte, že pomocné rutiny pro OpenID a další jsou užitečné.

Ověřování požadavků z robota do služby robota Připojení or

Pokud chcete komunikovat se službou Robot Připojení or, musíte v hlavičce každého požadavku rozhraní API zadat přístupový token Authorization pomocí tohoto formátu:

Authorization: Bearer ACCESS_TOKEN

Získání a použití tokenu JWT pro robota:

Robot odešle požadavek GET HTTP do přihlašovací služby MSA.
Odpověď ze služby obsahuje token JWT, který se má použít.
Váš robot obsahuje tento token JWT do autorizační hlavičky v požadavcích na službu Bot Připojení or.

Důležité

Pokud jste to ještě neudělali, musíte robota zaregistrovat ve službě Bot Framework, abyste získali id aplikace a heslo. K vyžádání přístupového tokenu potřebujete ID a heslo robota.

Identitu robota je možné spravovat v Azure několika různými způsoby.

Jako spravovaná identita přiřazená uživatelem, takže nemusíte spravovat přihlašovací údaje robota sami.
Jako aplikace s jedním tenantem.
Jako aplikace s více tenanty .

Vyžádání přístupového tokenu na základě typu aplikace vašeho robota

Pokud chcete požádat o přístupový token z přihlašovací služby, zadejte následující požadavek a nahraďte MICROSOFT-APP-ID a MICROSOFT-APP-PASSWORD id a heslo robota, které jste získali při registraci robota ve službě 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

Pokud chcete požádat o přístupový token z přihlašovací služby, zadejte následující požadavek a nahraďte MICROSOFT-APP-ID, MICROSOFT-APP-PASSWORD a MICROSOFT-TENANT-ID id appID robota, heslo a ID tenanta, které jste získali při registraci robota ve službě Bot Service.

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

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

App Service a Azure Functions poskytují interně přístupný koncový bod REST pro načtení tokenu. Pokud chcete požádat o přístupový token z koncového MSI/token bodu, vytvořte do koncového bodu požadavek GET. resource Použijte parametry dotazu.client_id https://api.botframework.com Nastavte resource a client_id na ID aplikace spravované identity robota. Požadavek nevyžaduje další parametry dotazu.

Další informace o koncovém bodu tokenu najdete v tématu Připojení ke službám Azure v kódu aplikace.
Další informace o ID aplikací robota najdete v tématu Vytvoření prostředku robota Azure.

Pokud je vaše aplikace autorizována přihlašovací službou, text odpovědi JSON určí váš přístupový token, jeho typ a vypršení platnosti (v sekundách).

Při přidávání tokenu do Authorization hlavičky požadavku je nutné použít přesnou hodnotu zadanou v této odpovědi – neuchovávejte nebo kódujte hodnotu tokenu. Přístupový token je platný až do vypršení jeho platnosti. Pokud chcete zabránit vypršení platnosti tokenu v dopadu na výkon robota, můžete se rozhodnout token uložit do mezipaměti a proaktivně ho aktualizovat.

Tento příklad ukazuje odpověď z přihlašovací služby účtu Microsoft Entra ID:

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

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

Krok 3: Zadání tokenu JWT v autorizační hlavičce požadavků

Když do služby robota Připojení or odešlete požadavek rozhraní API, zadejte přístupový token v Authorization hlavičce požadavku pomocí tohoto formátu:

Authorization: Bearer ACCESS_TOKEN

Všechny požadavky, které odešlete do služby Robot Připojení or, musí obsahovat přístupový token v Authorization hlavičce. Pokud je token správně vytvořený, nevypršela platnost a vygenerovala se přihlašovací službou účtu Microsoft Entra ID, služba robota Připojení or žádost autorizuje. Provádí se další kontroly, které zajistí, že token patří robotovi, který požadavek odeslal.

Následující příklad ukazuje, jak zadat přístupový token v Authorization hlavičce požadavku.

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

(JSON-serialized Activity message goes here)

Důležité

V hlavičce požadavků, které odešlete do služby robota Připojení or, zadejte pouze token Authorization JWT. Neodesílejte token přes nezabezpečené kanály a nezahrnujte ho do požadavků HTTP, které odesíláte do jiných služeb. Token JWT, který získáte z přihlašovací služby účtu Microsoft Entra ID, je jako heslo a měl by být zpracován s velkou opatrností. Každý, kdo má token, ho může použít k provádění operací jménem vašeho robota.

Robot pro Připojení or: příklady komponent JWT

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
}

Poznámka:

Skutečná pole se můžou v praxi lišit. Vytvořte a ověřte všechny tokeny JWT, jak je uvedeno výše.

Ověřování požadavků ze služby robota Připojení or do robota

Když robot Připojení orová služba odešle žádost robotovi, určí v Authorization hlavičce požadavku podepsaný token JWT. Robot může ověřovat volání ze služby Robot Připojení or tím, že ověří pravost podepsaného tokenu JWT.

Ověření volání ze služby robota Připojení oru:

Váš robot získá token JWT z autorizační hlavičky v požadavcích odeslaných ze služby Robot Připojení or.
Robot získá dokument metadat OpenID pro službu bot Připojení or.
Robot získá seznam platných podpisových klíčů z dokumentu.
Váš robot ověří pravost tokenu JWT.

Krok 2: Získání dokumentu metadat OpenID

Dokument metadat OpenID určuje umístění druhého dokumentu se seznamem platných podpisových klíčů služby Bot Připojení or. Pokud chcete získat dokument metadat OpenID, zadejte tento požadavek prostřednictvím protokolu HTTPS:

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

Tip

Jedná se o statickou adresu URL, kterou můžete pevně zakódovat do aplikace.

Následující příklad ukazuje dokument metadat OpenID vrácený v reakci na GET požadavek. Vlastnost jwks_uri určuje umístění dokumentu, který obsahuje platné podpisové klíče služby Bot Připojení or.

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

Krok 3: Získání seznamu platných podpisových klíčů

Pokud chcete získat seznam platných podpisových klíčů, vyžádejte GET požadavek prostřednictvím protokolu HTTPS na adresu URL určenou jwks_uri vlastností v dokumentu metadat OpenID. Příklad:

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

Text odpovědi určuje dokument ve formátu JWK, ale také obsahuje další vlastnost pro každý klíč: endorsements.

Tip

Seznam klíčů je stabilní a může se uložit do mezipaměti, ale nové klíče se můžou kdykoli přidat. Aby se zajistilo, že váš robot má před používáním těchto klíčů aktuální kopii dokumentu, všechny instance robota by měly aktualizovat místní mezipaměť dokumentu alespoň jednou za 24 hodin.

Vlastnost endorsements v rámci každého klíče obsahuje jeden nebo více ověřovacích řetězců, které můžete použít k ověření, že ID kanálu zadané ve vlastnosti v channelId rámci objektu Aktivity příchozího požadavku je autentické. Seznam ID kanálů, které vyžadují doporučení, je možné konfigurovat v rámci každého robota. Ve výchozím nastavení se zobrazí seznam všech ID publikovaných kanálů, i když vývojáři robotů můžou přepsat hodnoty ID vybraného kanálu v obou směrech.

Krok 4: Ověření tokenu JWT

Pokud chcete ověřit pravost tokenu odeslaného službou Bot Připojení or, musíte token extrahovat z Authorization hlavičky požadavku, parsovat token, ověřit jeho obsah a ověřit jeho podpis.

Knihovny parsování JWT jsou k dispozici pro mnoho platforem a většina implementuje zabezpečené a spolehlivé analýzy tokenů JWT, i když je nutné tyto knihovny obvykle nakonfigurovat tak, aby určité vlastnosti tokenu (jeho vystavitel, cílová skupina atd.) obsahovaly správné hodnoty. Při analýze tokenu musíte nakonfigurovat knihovnu parsování nebo napsat vlastní ověření, abyste zajistili, že token splňuje tyto požadavky:

Token byl odeslán v hlavičce HTTP Authorization se schématem Bearer.
Token je platný JSON, který odpovídá standardu JWT.
Token obsahuje deklaraci identity vystavitele s hodnotou https://api.botframework.com.
Token obsahuje deklaraci identity cílové skupiny s hodnotou rovnající se ID aplikace Microsoft robota.
Token je v době platnosti. Standardní hodinová nerovnoměrná distribuce je 5 minut.
Token má platný kryptografický podpis s klíčem uvedeným v dokumentu klíče OpenID načteným v kroku 3 pomocí podpisového algoritmu zadaného ve id_token_signing_alg_values_supported vlastnosti dokumentu metadat Open ID načteného v kroku 2.
Token obsahuje deklaraci identity serviceUrl s hodnotou, která odpovídá serviceUrl vlastnosti v kořenovém adresáři objektu Aktivity příchozího požadavku.

Pokud se vyžaduje doporučení pro ID kanálu:

Měli byste vyžadovat, aby všechny Activity objekty odeslané robotovi s ID kanálu byly doprovázeny tokenem JWT, který je podepsaný doporučením pro daný kanál.
Pokud doporučení není k dispozici, robot by měl požadavek odmítnout vrácením stavového kódu HTTP 403 (Zakázáno).

Důležité

Všechny tyto požadavky jsou důležité, zejména požadavky 4 a 6. Při implementaci všech těchto požadavků na ověření zůstane robot otevřený útokům, což by mohlo způsobit, že robot dojde k divulování tokenu JWT.

Implementátoři by neměli vystavit způsob, jak zakázat ověřování tokenu JWT, který se odesílá do robota.

Připojení or robota: příklady komponent JWT

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

Poznámka:

Skutečná pole se můžou v praxi lišit. Vytvořte a ověřte všechny tokeny JWT, jak je uvedeno výše.

Ověřování požadavků z bot Framework Emulatoru na robota

Bot Framework Emulator je desktopový nástroj, který můžete použít k otestování funkčnosti robota. I když bot Framework Emulator používá stejné technologie ověřování, jak je popsáno výše, nemůže zosobnit skutečnou službu Bot Připojení or. Místo toho používá ID aplikace Microsoft a heslo aplikace Microsoftu, které zadáte při připojení emulátoru k robotovi k vytvoření tokenů, které jsou identické s těmi, které robot vytvoří. Když emulátor odešle požadavek robotovi, určuje token JWT v Authorization hlavičce požadavku – v podstatě pomocí vlastních přihlašovacích údajů robota k ověření požadavku.

Pokud implementujete knihovnu ověřování a chcete přijímat požadavky z bot Framework Emulatoru, musíte přidat tuto další ověřovací cestu. Cesta je strukturálně podobná cestě Připojení oru –> cesta k ověření robota, ale místo dokumentu OpenID Připojení robota používá dokument OpenID msA.

Ověření volání z bot Framework Emulatoru:

Váš robot získá token JWT z autorizační hlavičky v požadavcích odeslaných z bot Framework Emulatoru.
Robot získá dokument metadat OpenID pro službu bot Připojení or.
Robot získá seznam platných podpisových klíčů z dokumentu.
Váš robot ověří pravost tokenu JWT.

Krok 2: Získání dokumentu metadat OPENID MSA

Dokument metadat OpenID určuje umístění druhého dokumentu, který obsahuje platné podpisové klíče. Pokud chcete získat dokument metadat MSA OpenID, vyžádejte tento požadavek přes HTTPS:

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

Následující příklad ukazuje dokument metadat OpenID vrácený v reakci na GET požadavek. Vlastnost jwks_uri určuje umístění dokumentu, který obsahuje platné podpisové klíče.

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

Krok 3: Získání seznamu platných podpisových klíčů

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

Text odpovědi určuje dokument ve formátu JWK.

Krok 4: Ověření tokenu JWT

Pokud chcete ověřit pravost tokenu odeslaného emulátorem, musíte token extrahovat z Authorization hlavičky požadavku, parsovat token, ověřit jeho obsah a ověřit jeho podpis.

Token byl odeslán v hlavičce HTTP Authorization se schématem Bearer.
Token je platný JSON, který odpovídá standardu JWT.
Token obsahuje deklaraci identity vystavitele s jednou ze zvýrazněných hodnot pro nevládní případy. Kontrola obou hodnot vystavitele zajistí, že kontrolujete hodnoty vystavitele v3.1 i v3.2.
Token obsahuje deklaraci identity cílové skupiny s hodnotou rovnající se ID aplikace Microsoft robota.
Emulátor v závislosti na verzi odešle ID aplikace prostřednictvím deklarace identity appid (verze 1) nebo deklarace identity autorizované strany (verze 2).
Token je v době platnosti. Standardní hodinová nerovnoměrná distribuce je 5 minut.
Token má platný kryptografický podpis s klíčem uvedeným v dokumentu klíče OpenID, který byl načten v kroku 3.

Poznámka:

Požadavek 5 je specifický pro cestu ověření emulátoru.

Pokud token nesplňuje všechny tyto požadavky, robot by měl požadavek ukončit vrácením stavového kódu HTTP 403 (Zakázáno).

Důležité

Všechny tyto požadavky jsou důležité, zejména požadavky 4 a 7. Při implementaci všech těchto požadavků na ověření zůstane robot otevřený útokům, což by mohlo způsobit, že robot dojde k divulování tokenu JWT.

Emulátor robota: ukázkové komponenty JWT

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
}

Poznámka:

Skutečná pole se můžou v praxi lišit. Vytvořte a ověřte všechny tokeny JWT, jak je uvedeno výše.

Změny protokolu zabezpečení

Ověřování robotem pro Připojení or

Verze protokolu	Platná hodnota
v3.1 a v3.2	`https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token`

Rozsah OAuth

Verze protokolu	Platná hodnota
v3.1 a v3.2	`https://api.botframework.com/.default`

ověřování robota Připojení orem

Dokument metadat OpenID

Verze protokolu	Platná hodnota
v3.1 a v3.2	`https://login.botframework.com/v1/.well-known/openidconfiguration`

Vystavitel JWT

Verze protokolu	Platná hodnota
v3.1 a v3.2	`https://api.botframework.com`

Ověřování emulátoru do robota

Verze protokolu	Platná hodnota
v3.1 a v3.2	`https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token`

Rozsah OAuth

Verze protokolu	Platná hodnota
v3.1 a v3.2	ID aplikace Microsoftu pro vašeho robota + `/.default`

Cílová skupina JWT

Verze protokolu	Platná hodnota
v3.1 a v3.2	ID aplikace Microsoft vašeho robota

Vystavitel JWT

Verze protokolu	Platná hodnota
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`

Viz také zvýrazněné hodnoty pro nevládní případy.

Dokument metadat OpenID

Verze protokolu	Platná hodnota
v3.1 a v3.2	`https://login.microsoftonline.com/botframework.com/v2.0/.well-known/openid-configuration`

Ověřování pomocí rozhraní API Připojení oru robota

Technologií ověřování

Ověřování požadavků z robota do služby robota Připojení or

Krok 3: Zadání tokenu JWT v autorizační hlavičce požadavků

Robot pro Připojení or: příklady komponent JWT

Ověřování požadavků ze služby robota Připojení or do robota

Krok 2: Získání dokumentu metadat OpenID

Krok 3: Získání seznamu platných podpisových klíčů

Krok 4: Ověření tokenu JWT

Připojení or robota: příklady komponent JWT

Ověřování požadavků z bot Framework Emulatoru na robota

Krok 2: Získání dokumentu metadat OPENID MSA

Krok 3: Získání seznamu platných podpisových klíčů

Krok 4: Ověření tokenu JWT

Emulátor robota: ukázkové komponenty JWT

Změny protokolu zabezpečení

Ověřování robotem pro Připojení or

Rozsah OAuth

ověřování robota Připojení orem

Dokument metadat OpenID

Vystavitel JWT

Ověřování emulátoru do robota

Rozsah OAuth

Cílová skupina JWT

Vystavitel JWT

Dokument metadat OpenID

Další materiály

Další materiály

Ověřování pomocí rozhraní API Připojení oru robota

Technologií ověřování

Ověřování požadavků z robota do služby robota Připojení or

Krok 1: Žádost o přístupový token ze služby přihlášení účtu Microsoft Entra ID

Krok 2: Získání tokenu JWT z odpovědi přihlašovací služby účtu Microsoft Entra ID

Krok 3: Zadání tokenu JWT v autorizační hlavičce požadavků

Robot pro Připojení or: příklady komponent JWT

Ověřování požadavků ze služby robota Připojení or do robota

Krok 2: Získání dokumentu metadat OpenID

Krok 3: Získání seznamu platných podpisových klíčů

Krok 4: Ověření tokenu JWT

Připojení or robota: příklady komponent JWT

Ověřování požadavků z bot Framework Emulatoru na robota

Krok 2: Získání dokumentu metadat OPENID MSA

Krok 3: Získání seznamu platných podpisových klíčů

Krok 4: Ověření tokenu JWT

Emulátor robota: ukázkové komponenty JWT

Změny protokolu zabezpečení

Ověřování robotem pro Připojení or

Přihlašovací adresa URL OAuth

Rozsah OAuth

ověřování robota Připojení orem

Dokument metadat OpenID

Vystavitel JWT

Ověřování emulátoru do robota

Přihlašovací adresa URL OAuth

Rozsah OAuth

Cílová skupina JWT

Vystavitel JWT

Dokument metadat OpenID

Další materiály

Další materiály