Autenticazione con l'API bot Connector

Il bot comunica con il servizio Bot Connector usando HTTP su un canale protetto (SSL/TLS). Quando il bot invia una richiesta al servizio Connector, deve includere informazioni che il servizio Connector può usare per verificarne l'identità. Analogamente, quando il servizio Connector invia una richiesta al bot, deve includere informazioni che il bot può usare per verificarne l'identità. Questo articolo descrive le tecnologie di autenticazione e i requisiti per l'autenticazione a livello di servizio eseguita 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 Connector.

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 app e la password ottenuti per il bot durante la registrazione e l'SDK gestirà il resto.

Tecnologie di autenticazione

Per stabilire un trust tra un bot e Bot Connector vengono usate quattro tecnologie di autenticazione:

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 Connector

Per comunicare con il servizio Bot Connector, è necessario specificare un token di accesso nell'intestazione Authorization di ogni richiesta 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 Connector.

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

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 una applicazione a tenant singolo.
• Come app multi-tenant.

Richiedere un token di accesso in base al tipo di applicazione del 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

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

Passaggio 2: Ottenere il token JWT dalla risposta del servizio di accesso dell'account di 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 impedire che la scadenza del token influisca sulle prestazioni del bot, è possibile scegliere di 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 autorizzazione delle richieste

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

Authorization: Bearer ACCESS_TOKEN

Tutte le richieste 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 Connector autorizza la richiesta. Vengono eseguiti controlli aggiuntivi per assicurarsi che il token appartenga al bot che ha inviato la richiesta.

Nell'esempio seguente viene illustrato 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)

Bot to Connector: 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
}

Autentica le richieste del servizio Bot Connector al tuo 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 Connector:

1. Il bot ottiene il token JWT dall'intestazione di autorizzazione nelle richieste inviate dal servizio Bot Connector.
2. Il bot ottiene il documento di metadati OpenID per il servizio Bot Connector.
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 il percorso di un secondo documento che elenca le chiavi di firma valide del servizio Bot Connector. Per ottenere il documento di metadati OpenID, eseguire questa richiesta tramite HTTPS:

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

Nell'esempio seguente viene illustrato un documento di metadati OpenID restituito in risposta alla GET richiesta. La jwks_uri proprietà specifica il percorso 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, eseguire una GET richiesta tramite HTTPS all'URL specificato dalla jwks_uri proprietà nel documento di metadati OpenID. Per 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.

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 degli ID canale che richiedono l'approvazione è configurabile all'interno di ogni bot. Per impostazione predefinita, sarà l'elenco di tutti gli ID canale pubblicati, anche se gli sviluppatori di bot possono eseguire l'override dei valori id canale selezionati in entrambi i modi.

Passaggio 4: Verificare il token JWT

Per verificare l'autenticità del token inviato dal servizio Bot Connector, è 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. Quando si analizza il token, è necessario configurare la libreria di analisi o scrivere la propria convalida per assicurarsi che il token soddisfi questi requisiti:

1. Il token è stato inviato nell'intestazione HTTP Authorization usando lo schema "Bearer".
2. Il token è JSON valido conforme allo standard JWT.
3. Il token contiene un'attestazione "issuer" con valore di https://api.botframework.com.
4. Il token contiene un'attestazione "audience" con un valore uguale all'ID app Microsoft del bot.
5. Il token rientra nel periodo di validità. Lo sfasamento dell'orologio standard del settore è di 5 minuti.
6. Il token ha una firma di crittografia valida, con una chiave elencata nel documento Chiavi OpenID recuperate nel passaggio 3, usando l'algoritmo di firma specificato nella id_token_signing_alg_values_supported proprietà del documento Metadati OPEN ID recuperato nel passaggio 2.
7. Il token contiene un'attestazione "serviceUrl" con valore corrispondente alla serviceUrl proprietà nella radice dell'oggetto Activity della richiesta in ingresso.

Se è necessaria l'approvazione per un ID canale:

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

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

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
}

Autentica le richieste provenienti da Bot Framework Emulator dirette al tuo 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 Connector reale. Usa invece l'ID dell'app Microsoft e la Password dell'app Microsoft specificati quando si connette l'Emulatore al bot per creare token identici a quelli che il bot crea. 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 convalida Connector -> Bot, ma utilizza il documento OpenID di MSA anziché il documento OpenID del Bot Connector.

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 Connector.
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 MSA

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

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

Nell'esempio seguente viene illustrato un documento di metadati OpenID restituito in risposta alla GET richiesta. La jwks_uri proprietà specifica il percorso 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, eseguire una GET richiesta tramite HTTPS all'URL specificato dalla jwks_uri proprietà nel documento di metadati OpenID. Per 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. Quando si analizza il token, è necessario configurare la libreria di analisi o scrivere la propria convalida per assicurarsi che il token soddisfi questi requisiti:

1. Il token è stato inviato nell'intestazione HTTP Authorization usando lo schema "Bearer".
2. Il token è JSON valido conforme allo standard JWT.
3. Il token contiene un'attestazione dell'autorità emittente per il protocollo di sicurezza applicabile. Per l'implementazione corrente, vedere Microsoft. Agents.Connector.
4. Il token contiene un'attestazione "audience" con un valore uguale all'ID 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 rientra nel periodo di validità. Lo sfasamento dell'orologio standard del settore è di 5 minuti.
7. Il token ha una firma di crittografia valida con una chiave elencata nel documento Chiavi OpenID recuperate nel passaggio 3.

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

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
}

Modifiche al protocollo di sicurezza

Autenticazione da bot a connettore

URL di accesso OAuth

Ambito OAuth

Autenticazione da connettore a bot

Documento di metadati OpenID

Emittente JWT

Autenticazione da emulatore a bot

URL di accesso OAuth

Ambito OAuth

Destinatari JWT

Emittente JWT

Per l'implementazione corrente, vedere Microsoft. Agents.Connector.

Documento di metadati OpenID

Risorse aggiuntive

• Risoluzione dei problemi relativi all'autenticazione di Bot Framework
• Specifica del protocollo di attività
• Informazioni di riferimento sulle API RestConnectorClient
• Json Web Token (JWT) draft-jones-json-web-token-07
• JSON Web Signature (JWS) draft-jones-json-web-signature-04
• Chiave Web JSON (JWK) RFC 7517