Autenticação com a API do Bot Connector

Seu bot se comunica com o serviço Bot Connector usando HTTP em um canal seguro (SSL/TLS). Quando o bot envia uma solicitação para o serviço Connector, ele deve incluir informações que o serviço Connector pode usar para verificar sua identidade. Da mesma forma, quando o serviço Connector envia uma solicitação para seu bot, ele deve incluir informações que o bot pode usar para verificar sua identidade. Este artigo descreve as tecnologias de autenticação e os requisitos para a autenticação de nível de serviço que ocorre entre um bot e o serviço Bot Connector. Se você estiver escrevendo seu próprio código de autenticação, deverá implementar os procedimentos de segurança descritos neste artigo para permitir que seu bot troque mensagens com o serviço Bot Connector.

Se você estiver usando o SDK do Bot Framework, não precisará implementar os procedimentos de segurança descritos neste artigo, porque o SDK faz isso automaticamente por você. Basta configurar seu projeto com o ID do aplicativo e a senha que você obteve para seu bot durante o registro e o SDK cuidará do resto.

Tecnologias de autenticação

Quatro tecnologias de autenticação são usadas para estabelecer confiança entre um bot e o Bot Connector:

Este artigo descreve como usar essas tecnologias via HTTPS e JSON padrão. Nenhum SDK especial é necessário, embora você possa achar que auxiliares para OpenID e outros são úteis.

Autenticar solicitações do seu bot para o serviço Bot Connector

Para se comunicar com o serviço Bot Connector, você deve especificar um token de acesso no Authorization cabeçalho de cada solicitação de API, usando este formato:

Authorization: Bearer ACCESS_TOKEN

Para obter e usar um token JWT para seu bot:

1. Seu bot envia uma solicitação HTTP GET para o Serviço de Login do MSA.
2. A resposta do serviço contém o token JWT a ser usado.
3. Seu bot inclui esse token JWT no cabeçalho de autorização em solicitações para o serviço Bot Connector.

Etapa 1: Solicitar um token de acesso do serviço de login da conta do Microsoft Entra ID

Sua identidade de bot pode ser gerenciada no Azure de algumas maneiras diferentes.

• Como uma identidade gerenciada atribuída pelo usuário, para que você não precise gerenciar as credenciais do bot por conta própria.
• Como um aplicativo de locatário único.
• Como um aplicativo multilocatário .

Solicite um token de acesso com base no tipo de aplicativo do seu 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

Etapa 2: Obter o token JWT da resposta do serviço de login da conta do Microsoft Entra ID

Se seu aplicativo for autorizado pelo serviço de login, o corpo de resposta JSON especificará seu token de acesso, seu tipo e sua expiração (em segundos).

Ao adicionar o token ao Authorization cabeçalho de uma solicitação, você deve usar o valor exato especificado nesta resposta — não escape ou codifique o valor do token. O token de acesso é válido até a sua expiração. Para evitar que a expiração do token afete o desempenho do bot, você pode optar por armazenar em cache e atualizar proativamente o token.

Este exemplo mostra uma resposta do serviço de login da conta Microsoft Entra ID:

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

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

Etapa 3: Especifique o token JWT no cabeçalho Autorização das solicitações

Ao enviar uma solicitação de API para o serviço Bot Connector, especifique o Authorization token de acesso no cabeçalho da solicitação usando este formato:

Authorization: Bearer ACCESS_TOKEN

Todas as solicitações enviadas ao serviço Bot Connector devem incluir o Authorization token de acesso no cabeçalho. Se o token estiver formado corretamente, não tiver expirado e tiver sido gerado pelo serviço de login da conta do Microsoft Entra ID, o serviço Bot Connector autorizará a solicitação. Verificações adicionais são realizadas para garantir que o token pertença ao bot que enviou a solicitação.

O exemplo a seguir mostra como especificar o token de acesso no Authorization cabeçalho da solicitação.

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

(JSON-serialized Activity message goes here)

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

Autenticar solicitações do serviço Bot Connector para seu bot

Quando o serviço Bot Connector envia uma solicitação ao seu bot, ele especifica um token JWT assinado no Authorization cabeçalho da solicitação. Seu bot pode autenticar chamadas do serviço Bot Connector verificando a autenticidade do token JWT assinado.

Para autenticar chamadas do serviço Bot Connector:

1. Seu bot obtém o token JWT do cabeçalho de autorização em solicitações enviadas do serviço Bot Connector.
2. Seu bot obtém o documento de metadados OpenID para o serviço Bot Connector.
3. Seu bot obtém a lista de chaves de assinatura válidas do documento.
4. Seu bot verifica a autenticidade do token JWT.

Etapa 2: Obter o documento de metadados OpenID

O documento de metadados OpenID especifica o local de um segundo documento que lista as chaves de assinatura válidas do serviço Bot Connector. Para obter o documento de metadados OpenID, emita esta solicitação via HTTPS:

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

O exemplo a seguir mostra um documento de metadados OpenID que é retornado em resposta à GET solicitação. A jwks_uri propriedade especifica o local do documento que contém as chaves de assinatura válidas do serviço 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"
    ]
}

Etapa 3: Obter a lista de chaves de assinatura válidas

Para obter a lista de chaves de assinatura válidas, emita uma GET solicitação via HTTPS para a URL especificada pela jwks_uri propriedade no documento de metadados OpenID. Por exemplo:

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

O corpo da resposta especifica o documento no formato JWK, mas também inclui uma propriedade adicional para cada chave: endorsements.

A endorsements propriedade dentro de cada chave contém uma ou mais cadeias de caracteres de endosso que você pode usar para verificar se o ID do canal especificado na channelId propriedade dentro do objeto Activity da solicitação de entrada é autêntico. A lista de IDs de canal que exigem endossos é configurável dentro de cada bot. Por padrão, será a lista de todos os IDs de canal publicados, embora os desenvolvedores de bots possam substituir os valores de ID de canal selecionados de qualquer maneira.

Etapa 4: Verificar o token JWT

Para verificar a autenticidade do token que foi enviado pelo serviço Bot Connector, você deve extrair o token do Authorization cabeçalho da solicitação, analisar o token, verificar seu conteúdo e verificar sua assinatura.

As bibliotecas de análise JWT estão disponíveis para muitas plataformas e a maioria implementa análises seguras e confiáveis para tokens JWT, embora você normalmente deva configurar essas bibliotecas para exigir que certas características do token (seu emissor, público e assim por diante) contenham valores corretos. Ao analisar o token, você deve configurar a biblioteca de análise ou escrever sua própria validação para garantir que o token atenda a estes requisitos:

1. O token foi enviado no cabeçalho HTTP Authorization com o esquema "Portador".
2. O token é JSON válido que está em conformidade com o padrão JWT.
3. O token contém uma declaração de "emissor" com valor de https://api.botframework.com.
4. O token contém uma declaração de "audiência" com um valor igual ao ID do aplicativo Microsoft do bot.
5. O token está dentro do seu período de validade. A inclinação do relógio padrão da indústria é de 5 minutos.
6. O token tem uma assinatura criptográfica válida, com uma chave listada no documento de chaves OpenID que foi recuperado na Etapa 3, usando o algoritmo de assinatura especificado na propriedade do documento Open ID Metadata que foi recuperado na id_token_signing_alg_values_supported Etapa 2.
7. O token contém uma declaração "serviceUrl" com valor que corresponde à serviceUrl propriedade na raiz do objeto Activity da solicitação de entrada.

Se for necessário o endosso para um ID de canal:

• Você deve exigir que qualquer Activity objeto enviado ao seu bot com esse ID de canal seja acompanhado por um token JWT assinado com um endosso para esse canal.
• Se o endosso não estiver presente, seu bot deverá rejeitar a solicitação retornando um código de status HTTP 403 (Proibido).

Os implementadores não devem expor uma maneira de desabilitar a validação do token JWT que é enviado para o bot.

Conector para Bot: exemplos de componentes 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
}

Autenticar solicitações do Bot Framework Emulator para seu bot

O Bot Framework Emulator é uma ferramenta de desktop que você pode usar para testar a funcionalidade do seu bot. Embora o Bot Framework Emulator use as mesmas tecnologias de autenticação descritas acima, ele não pode representar o serviço Bot Connector real. Em vez disso, ele usa a ID do Aplicativo Microsoft e a Senha do Aplicativo Microsoft que você especifica quando conecta o Emulador ao bot para criar tokens idênticos aos criados pelo bot. Quando o emulador envia uma solicitação para seu bot, ele especifica o Authorization token JWT no cabeçalho da solicitação — em essência, usando as próprias credenciais do bot para autenticar a solicitação.

Se você estiver implementando uma biblioteca de autenticação e quiser aceitar solicitações do Emulador do Bot Framework, deverá adicionar esse caminho de verificação adicional. O caminho é estruturalmente semelhante ao caminho de verificação do Connector -> Bot, mas usa o documento OpenID do MSA em vez do documento OpenID do Bot Connector.

Para autenticar chamadas do Bot Framework Emulator:

1. Seu bot obtém o token JWT do cabeçalho de autorização em solicitações enviadas do Bot Framework Emulator.
2. Seu bot obtém o documento de metadados OpenID para o serviço Bot Connector.
3. Seu bot obtém a lista de chaves de assinatura válidas do documento.
4. Seu bot verifica a autenticidade do token JWT.

Etapa 2: Obter o documento de metadados do MSA OpenID

O documento de metadados OpenID especifica o local de um segundo documento que lista as chaves de assinatura válidas. Para obter o documento de metadados do MSA OpenID, emita esta solicitação via HTTPS:

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

O exemplo a seguir mostra um documento de metadados OpenID que é retornado em resposta à GET solicitação. A jwks_uri propriedade especifica o local do documento que contém as chaves de assinatura válidas.

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

Etapa 3: Obter a lista de chaves de assinatura válidas

Para obter a lista de chaves de assinatura válidas, emita uma GET solicitação via HTTPS para a URL especificada pela jwks_uri propriedade no documento de metadados OpenID. Por exemplo:

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

O corpo da resposta especifica o documento no formato JWK.

Etapa 4: Verificar o token JWT

Para verificar a autenticidade do token que foi enviado pelo emulador, você deve extrair o token do Authorization cabeçalho da solicitação, analisar o token, verificar seu conteúdo e verificar sua assinatura.

As bibliotecas de análise JWT estão disponíveis para muitas plataformas e a maioria implementa análises seguras e confiáveis para tokens JWT, embora você normalmente deva configurar essas bibliotecas para exigir que certas características do token (seu emissor, público e assim por diante) contenham valores corretos. Ao analisar o token, você deve configurar a biblioteca de análise ou escrever sua própria validação para garantir que o token atenda a estes requisitos:

1. O token foi enviado no cabeçalho HTTP Authorization com o esquema "Portador".
2. O token é JSON válido que está em conformidade com o padrão JWT.
3. O token contém uma declaração de "emissor" com um dos valores destacados para casos não governamentais. A verificação de ambos os valores do emissor garantirá que você esteja verificando os valores do emissor do protocolo de segurança v3.1 e v3.2.
4. O token contém uma declaração de "audiência" com um valor igual ao ID do aplicativo Microsoft do bot.
5. O emulador, dependendo da versão, envia o AppId por meio da declaração appid (versão 1) ou da declaração de parte autorizada (versão 2).
6. O token está dentro do seu período de validade. A inclinação do relógio padrão da indústria é de 5 minutos.
7. O token tem uma assinatura criptográfica válida com uma chave listada no documento de chaves OpenID que foi recuperado na Etapa 3.

Se o token não atender a todos esses requisitos, seu bot deverá encerrar a solicitação retornando um código de status HTTP 403 (Proibido).

Emulador para Bot: exemplo de componentes 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
}

Alterações no protocolo de segurança

Autenticação de Bot para Conector

OAuth login URL

Âmbito OAuth

Conector para autenticação de Bot

Documento de metadados OpenID

Emissor JWT

Emulador para autenticação de Bot

OAuth login URL

Âmbito OAuth

Audiência JWT

Emissor JWT

Ver também os valores destacados para casos não governamentais.

Documento de metadados OpenID

Recursos adicionais

• Troubleshooting Bot Framework authentication (Resolver problemas de autenticação do Bot Framework)
• Esquema de atividade do Bot Framework
• JSON Web Token (JWT) rascunho-jones-json-web-token-07
• Assinatura Web JSON (JWS) draft-jones-json-web-signature-04
• Chave Web JSON (JWK) RFC 7517