Condividi tramite

Autenticazione con l'API bot Connessione or

  • Articolo

Il bot comunica con il servizio Bot Connector usando HTTP su un canale protetto (SSL/TLS). Quando il bot invia una richiesta al servizio Bot Connector, deve includere informazioni che il servizio Bot Connector possa usare per verificarne l'identità. Analogamente, quando il servizio Bot Connector invia una richiesta al bot, deve includere informazioni che il bot possa usare per verificarne l'identità. Questo articolo descrive le tecnologie e i requisiti di autenticazione per l'autenticazione a livello di servizio che ha luogo tra un bot e il servizio Bot Connector. Se si scrive codice di autenticazione personalizzato, è necessario implementare le procedure di sicurezza descritte in questo articolo per consentire al bot di scambiare messaggi con il servizio Bot Connessione or.

Importante

Se si scrive codice di autenticazione personalizzato, è fondamentale implementare correttamente tutte le procedure di sicurezza. Mediante l'implementazione di tutti i passaggi descritti in questo articolo, è possibile ridurre il rischio che un utente malintenzionato possa leggere i messaggi inviati al bot, inviare messaggi che rappresentano il bot e rubare le chiavi private.

Se si usa Bot Framework SDK, non è necessario implementare le procedure di sicurezza descritte in questo articolo, perché l'SDK lo esegue automaticamente. È sufficiente configurare il progetto con l'ID e la password dell'app ottenuti per il bot durante la registrazione e l'SDK gestirà il resto.

Tecnologie di autenticazione

Per stabilire l'attendibilità tra un bot e Bot Connector, vengono usate quattro tecnologie di autenticazione:

Tecnologia Descrizione
SSL/TLS SSL/TLS è usato per tutte le connessioni da servizio a servizio. I certificati X.509v3 vengono usati per stabilire l'identità di tutti i servizi HTTPS. I client devono sempre ispezionare i certificati di servizio per verificare che siano attendibili e validi (i certificati client NON vengono usati nell'ambito di questo schema).
OAuth 2.0 OAuth 2.0 usa il servizio di accesso dell'account Microsoft Entra ID per generare un token sicuro che un bot può usare per inviare messaggi. Questo token è un token da servizio a servizio; non è richiesto un accesso utente.
Token JSON Web (JWT) I token JSON Web vengono usati per codificare i token inviati da e verso il bot. I client devono effettuare una verifica completa su tutti i token JWT che ricevono, secondo i requisiti descritti in questo articolo.
Metadati OpenID Il servizio Bot Connector pubblica un elenco di token validi che usa per registrare i token JWT ai metadati OpenID in un endpoint ben noto e statico.

Questo articolo descrive come usare queste tecnologie tramite HTTPS e JSON standard. Non sono necessari SDK speciali, anche se è possibile che gli helper per OpenID e altri siano utili.

Autenticare le richieste dal bot al servizio Bot Connessione or

Per comunicare con il servizio Bot Connector è necessario specificare un token di accesso nell'intestazione Authorization di ogni richiesta dell'API, usando questo formato:

Authorization: Bearer ACCESS_TOKEN

Per ottenere e usare un token JWT per il bot:

  1. Il bot invia una richiesta HTTP GET al servizio di accesso msa.
  2. La risposta dal servizio contiene il token JWT da usare.
  3. Il bot include questo token JWT nell'intestazione di autorizzazione nelle richieste al servizio Bot Connessione or.

Passaggio 1: Richiedere un token di accesso dal servizio di accesso dell'account Microsoft Entra ID

Importante

Se non è già stato fatto, è necessario registrare il bot con Bot Framework per ottenere l'APPID e la password. Per richiedere un token di accesso sono necessari l'ID app e la password del bot.

L'identità del bot può essere gestita in Azure in diversi modi.

  • Come identità gestita assegnata dall'utente, in modo che non sia necessario gestire manualmente le credenziali del bot.
  • Come app a tenant singolo.
  • Come app multi-tenant.

Richiedere un token di accesso in base al tipo di applicazione del bot.

Per richiedere un token di accesso dal servizio di accesso, eseguire la richiesta seguente, sostituendo MICROSOFT-APP-ID e MICROSOFT-APP-PASSWORD con l'APPID e la password del bot ottenuti quando è stato registrato il bot con il servizio Bot.

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

Passaggio 2: Ottenere il token JWT dalla risposta al servizio di accesso dell'account Microsoft Entra ID

Se l'applicazione è autorizzata dal servizio di accesso, il corpo della risposta JSON specificherà il token di accesso, il tipo e la scadenza (in secondi).

Quando si aggiunge il token all'intestazione Authorization di una richiesta, è necessario usare il valore esatto specificato in questa risposta, non eseguire l'escape o codificare il valore del token. Il token di accesso è valido fino alla scadenza. Per evitare che la scadenza del token si ripercuota sulle prestazioni del bot, è possibile memorizzare nella cache e aggiornare in modo proattivo il token.

Questo esempio mostra una risposta dal servizio di accesso dell'account microsoft Entra ID:

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

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

Passaggio 3: Specificare il token JWT nell'intestazione Authorization delle richieste

Quando si invia una richiesta di API al servizio Bot Connector, specificare un token di accesso nell'intestazione Authorization della richiesta usando questo formato:

Authorization: Bearer ACCESS_TOKEN

Tutte le richieste che vengono inviate al servizio Bot Connector devono includere il token di accesso nell'intestazione Authorization. Se il token è formato correttamente, non è scaduto ed è stato generato dal servizio di accesso dell'account Microsoft Entra ID, il servizio Bot Connessione or autorizza la richiesta. Vengono eseguiti controlli aggiuntivi per verificare che il token appartenga al bot che ha inviato la richiesta.

L'esempio seguente mostra come specificare il token di accesso nell'intestazione Authorization della richiesta.

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

(JSON-serialized Activity message goes here)

Importante

Specificare solo il token JWT nell'intestazione Authorization delle richieste inviate al servizio Bot Connector. NON inviare il token in canali non protetti e NON includerlo nelle richieste HTTP inviate ad altri servizi. Il token JWT ottenuto dal servizio di accesso dell'account Microsoft Entra ID è simile a una password e deve essere gestito con grande attenzione. Chiunque possieda il token può usarlo per eseguire operazioni per conto del bot.

Da bot a connettore: componenti JWT di esempio

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
}

Nota

I campi effettivi possono variare. Creare e convalidare tutti i token JWT come specificato in precedenza.

Autenticare le richieste dal servizio bot Connessione or al bot

Quando il servizio Bot Connector invia una richiesta al bot, specifica un token JWT firmato nell'intestazione Authorization della richiesta. Il bot può autenticare le chiamate dal servizio Bot Connector verificando l'autenticità del token JWT firmato.

Per autenticare le chiamate dal servizio Bot Connessione or:

  1. Il bot ottiene il token JWT dall'intestazione di autorizzazione nelle richieste inviate dal servizio Bot Connessione or.
  2. Il bot ottiene il documento di metadati OpenID per il servizio Bot Connessione or.
  3. Il bot ottiene l'elenco di chiavi di firma valide dal documento.
  4. Il bot verifica l'autenticità del token JWT.

Passaggio 2: Ottenere il documento di metadati OpenID

Il documento di metadati OpenID specifica la posizione di un secondo documento che elenca le chiavi di firma valide del servizio Bot Connector. Per ottenere il documento di metadati OpenID, inviare la richiesta tramite HTTPS:

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

Suggerimento

Questo è un URL statico che è possibile impostare come hardcoded nell'applicazione.

L'esempio seguente mostra un documento di metadati OpenID restituito in risposta alla richiesta GET. La proprietà jwks_uri specifica la posizione del documento che contiene le chiavi di firma valide del servizio Bot Connector.

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

Passaggio 3: Ottenere l'elenco delle chiavi di firma valide

Per ottenere l'elenco delle chiavi di firma valide, inviare una richiesta GET tramite HTTPS all'URL specificato dalla proprietà jwks_uri nel documento di metadati OpenID. Ad esempio:

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

Il corpo della risposta specifica il documento nel formato JWK ma include anche una proprietà aggiuntiva per ogni chiave: endorsements.

Suggerimento

L'elenco delle chiavi è stabile e può essere memorizzato nella cache, ma è possibile aggiungere nuove chiavi in qualsiasi momento. Per assicurarsi che il bot disponga di una copia aggiornata del documento prima che vengano usate queste chiavi, tutte le istanze del bot devono aggiornare la cache locale del documento almeno una volta ogni 24 ore.

La endorsements proprietà all'interno di ogni chiave contiene una o più stringhe di verifica dell'autenticità che è possibile utilizzare per verificare che l'ID canale specificato nella channelId proprietà all'interno dell'oggetto Activity della richiesta in ingresso sia autentica. L'elenco di ID canale che richiedono la verifica dell'autenticità può essere configurato all'interno di ogni bot. Per impostazione predefinita, sarà l'elenco di tutti gli ID canale pubblicati, anche se gli sviluppatori di bot possono sostituire determinati valori di ID canale in qualsiasi modo.

Passaggio 4: Verificare il token JWT

Per verificare l'autenticità del token che è stato inviato dal servizio Bot Connector, è necessario estrarre il token dall'intestazione Authorization della richiesta, analizzare il token, verificarne i contenuti e verificarne la firma.

Le librerie di analisi JWT sono disponibili per molte piattaforme e la maggior parte implementa l'analisi sicura e affidabile per i token JWT, anche se in genere è necessario configurare queste librerie per richiedere che determinate caratteristiche del token (l'autorità di certificazione, il gruppo di destinatari e così via) contengano valori corretti. Durante l'analisi del token, è necessario configurare la libreria di analisi o scrivere la propria convalida per garantire che il token soddisfi questi requisiti:

  1. Il token è stato inviato nell'intestazione Authorization HTTP con lo schema "Bearer".
  2. Il token è un oggetto JSON valido conforme allo standard JWT.
  3. Il token contiene un'attestazione "autorità di certificazione" con valore https://api.botframework.com.
  4. Il token contiene un'attestazione "destinatari" con un valore uguale all'ID dell'app Microsoft del bot.
  5. Il token è all'interno del periodo di validità. Lo sfasamento orario standard del settore è 5 minuti.
  6. Il token ha una firma crittografica valida, con una chiave elencata nel documento delle chiavi OpenID recuperato al Passaggio 3, che usa l'algoritmo di firma specificato nella proprietà id_token_signing_alg_values_supported del documento di metadati OpenID recuperato al Passaggio 2.
  7. Il token contiene un'attestazione "serviceUrl" con un valore che corrisponde alla proprietà serviceUrl alla radice dell'oggetto Activity della richiesta in arrivo.

Se è necessaria la verifica dell'autenticità per un ID canale:

  • È consigliabile richiedere che qualsiasi oggetto Activity inviato al bot con tale ID canale sia accompagnato da un token JWT firmato con una verifica dell'autenticità per quel canale.
  • Se l'approvazione non è presente, il bot deve rifiutare la richiesta restituendo un codice di stato HTTP 403 (Accesso negato).

Importante

Tutti questi requisiti sono importanti, in particolare i requisiti 4 e 6. La mancata implementazione di TUTTI questi requisiti di verifica esporrà il bot ad attacchi che potrebbero causare la divulgazione del token JWT.

Gli implementatori non devono esporre un modo per disabilitare la convalida del token JWT inviato al bot.

Da connettore a bot: componenti JWT di esempio

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
}

Nota

I campi effettivi possono variare. Creare e convalidare tutti i token JWT come specificato in precedenza.

Autenticare le richieste da Bot Framework Emulator al bot

Bot Framework Emulator è uno strumento desktop che è possibile usare per testare la funzionalità del bot. Anche se Bot Framework Emulator usa le stesse tecnologie di autenticazione descritte in precedenza, non è in grado di rappresentare il servizio Bot Connessione or reale. Usa invece l'ID app Microsoft e la password dell'app Microsoft specificati quando si connette l'emulatore al bot per creare token identici a quelli creati dal bot. Quando l'emulatore invia una richiesta al bot, specifica il token JWT nell'intestazione Authorization della richiesta, in sostanza, usando le credenziali del bot per autenticare la richiesta.

Se si implementa una libreria di autenticazione e si vogliono accettare richieste da Bot Framework Emulator, è necessario aggiungere questo percorso di verifica aggiuntivo. Il percorso è strutturalmente simile al percorso di verifica del bot Connessione or>, ma usa il documento OpenID di MSA anziché il documento OpenID del bot Connessione or.

Per autenticare le chiamate da Bot Framework Emulator:

  1. Il bot ottiene il token JWT dall'intestazione di autorizzazione nelle richieste inviate da Bot Framework Emulator.
  2. Il bot ottiene il documento di metadati OpenID per il servizio Bot Connessione or.
  3. Il bot ottiene l'elenco di chiavi di firma valide dal documento.
  4. Il bot verifica l'autenticità del token JWT.

Passaggio 2: Ottenere il documento di metadati OpenID di MSA

Il documento di metadati OpenID specifica la posizione di un secondo documento che elenca le chiavi di firma valide. Per ottenere il documento di metadati OpenID di MSA, inviare la richiesta tramite HTTPS:

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

L'esempio seguente mostra un documento di metadati OpenID restituito in risposta alla richiesta GET. La proprietà jwks_uri specifica la posizione del documento che contiene le chiavi di firma valide.

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

Passaggio 3: Ottenere l'elenco delle chiavi di firma valide

Per ottenere l'elenco delle chiavi di firma valide, inviare una richiesta GET tramite HTTPS all'URL specificato dalla proprietà jwks_uri nel documento di metadati OpenID. Ad esempio:

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

Il corpo della risposta specifica il documento nel formato JWK.

Passaggio 4: Verificare il token JWT

Per verificare l'autenticità del token inviato dall'emulatore, è necessario estrarre il token dall'intestazione Authorization della richiesta, analizzare il token, verificarne il contenuto e verificarne la firma.

Le librerie di analisi JWT sono disponibili per molte piattaforme e la maggior parte implementa l'analisi sicura e affidabile per i token JWT, anche se in genere è necessario configurare queste librerie per richiedere che determinate caratteristiche del token (l'autorità di certificazione, il gruppo di destinatari e così via) contengano valori corretti. Durante l'analisi del token, è necessario configurare la libreria di analisi o scrivere la propria convalida per garantire che il token soddisfi questi requisiti:

  1. Il token è stato inviato nell'intestazione Authorization HTTP con lo schema "Bearer".
  2. Il token è un oggetto JSON valido conforme allo standard JWT.
  3. Il token contiene un'attestazione "autorità emittente" con uno dei valori evidenziati per i casi non governativi. Se si controllano entrambi i valori dell'autorità emittente, è possibile verificare sia i valori dell'autorità di certificazione del protocollo di sicurezza v3.1 che della versione 3.2.
  4. Il token contiene un'attestazione "destinatari" con un valore uguale all'ID dell'app Microsoft del bot.
  5. L'emulatore, a seconda della versione, invia l'AppId tramite l'attestazione appid (versione 1) o l'attestazione di entità autorizzata (versione 2).
  6. Il token è all'interno del periodo di validità. Lo sfasamento orario standard del settore è 5 minuti.
  7. Il token ha una firma crittografica valida con una chiave elencata nel documento delle chiavi OpenID recuperato al Passaggio 3.

Nota

Il requisito 5 è specifico del percorso di verifica dell'emulatore.

Se il token non soddisfa tutti questi requisiti, il bot deve terminare la richiesta restituendo un codice di stato HTTP 403 (Accesso negato).

Importante

Tutti questi requisiti sono importanti, in particolare i requisiti 4 e 7. La mancata implementazione di TUTTI questi requisiti di verifica esporrà il bot ad attacchi che potrebbero causare la divulgazione del token JWT.

Da emulatore a bot: componenti JWT di esempio

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
}

Nota

I campi effettivi possono variare. Creare e convalidare tutti i token JWT come specificato in precedenza.

Modifiche al protocollo di sicurezza

Autenticazione da bot a connettore

URL di accesso OAuth

Versione del protocollo Valore valido
v3.1 e v3.2 https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token

Ambito OAuth

Versione del protocollo Valore valido
v3.1 e v3.2 https://api.botframework.com/.default

Autenticazione da connettore a bot

Documento di metadati OpenID

Versione del protocollo Valore valido
v3.1 e v3.2 https://login.botframework.com/v1/.well-known/openidconfiguration

Autorità emittente JWT

Versione del protocollo Valore valido
v3.1 e v3.2 https://api.botframework.com

Autenticazione da emulatore a bot

URL di accesso OAuth

Versione del protocollo Valore valido
v3.1 e v3.2 https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token

Ambito OAuth

Versione del protocollo Valore valido
v3.1 e v3.2 ID app Microsoft del bot + /.default

Destinatari di JWT

Versione del protocollo Valore valido
v3.1 e v3.2 ID app Microsoft del bot

Autorità emittente JWT

Versione del protocollo Valore valido
v3.1 1.0 https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/
v3.1 2.0 https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/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

Vedere anche i valori evidenziati per i casi non governativi.

Documento di metadati OpenID

Versione del protocollo Valore valido
v3.1 e v3.2 https://login.microsoftonline.com/botframework.com/v2.0/.well-known/openid-configuration

Risorse aggiuntive