Autenticazione con l'API bot Connessione or

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.

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:

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

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.

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 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)

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
}

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

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.

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).

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
}

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.

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

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
}

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

Autorità emittente JWT

Autenticazione da emulatore a bot

URL di accesso OAuth

Ambito OAuth

Destinatari di JWT

Autorità emittente JWT

Vedere anche i valori evidenziati per i casi non governativi.

Documento di metadati OpenID

Risorse aggiuntive

• Risoluzione dei problemi relativi all'autenticazione di Bot Framework
• Schema delle attività di Bot Framework
• JSON Web Token (JWT) draft-jones-json-web-token-07
• JSON Web Signature (JWS) draft-jones-json-web-signature-04
• JSON Web Key (JWK) RFC 7517