Autenticação com a API do Bot Connector

  • Artigo

O bot comunica-se com o serviço do Bot Connector usando HTTP em um canal seguro (SSL/TLS). Quando o bot envia uma solicitação ao serviço do Connector, ele deve incluir informações que o serviço do Connector pode usar para verificar a identidade do bot. Da mesma forma, quando o serviço do Connector envia uma solicitação ao bot, ele deve incluir informações que o bot pode usar para verificar a identidade do serviço. 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 do Bot Connector. Se você estiver gravando seu próprio código de autenticação, é necessário implementar os procedimentos de segurança descritos neste artigo para permitir que o bot troque mensagens com o serviço do Bot Connector.

Importante

Se você estiver gravando seu próprio código de autenticação, é essencial implementar corretamente todos os procedimentos de segurança. Ao implementar todas as etapas neste artigo, é possível reduzir o risco de um invasor conseguir ler as mensagens enviadas ao bot, enviar mensagens que representem o bot e roubar chaves secretas.

Caso esteja usando o SDK do Bot Framework, não é necessário implementar os procedimentos de segurança descritos neste artigo porque o SDK faz isso automaticamente para você. Basta configurar o projeto com a ID do aplicativo e a senha que você obteve para o bot durante o registro e o SDK cuidará do restante.

Tecnologias de autenticação

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

Tecnologia Descrição
SSL/TLS SSL/TLS é usada para todas as conexões de serviço a serviço. Certificados X.509v3 são usados para estabelecer a identidade de todos os serviços HTTPS. Os clientes sempre devem inspecionar certificados de serviço para garantir que eles sejam confiáveis e válidos. (Certificados de cliente NÃO são usados como parte desse esquema.)
OAuth 2.0 O OAuth 2.0 usa o serviço de logon da conta do Microsoft Entra ID para gerar um token de segurança que um bot pode usar para enviar mensagens. Esse token é um token de serviço a serviço; nenhum logon de usuário é exigido.
JWT (Token Web JSON) Tokens Web JSON são usados para codificar os tokens que são enviados para e do bot. Os clientes totalmente devem verificar integralmente todos os tokens JWT que recebem, de acordo com os requisitos descritos neste artigo.
Metadados do OpenID O serviço do Bot Connector publica uma lista de tokens válidos que ele usa para assinar seus próprios tokens JWT para metadados do OpenID em um ponto de extremidade estático bem conhecido.

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

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

Para comunicar-se com o serviço do Bot Connector, é necessário especificar um token de acesso no cabeçalho Authorization 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 Logon do MSA.
  2. A resposta do serviço contém o token JWT a ser usado.
  3. O bot inclui esse token JWT no cabeçalho de autorização em solicitações para o serviço do Bot Connector.

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

Importante

Se você ainda não fez isso, é necessário registrar seu bot com o Bot Framework para obter sua AppID e a senha. Para solicitar um token de acesso, são necessárias a ID do aplicativo e a senha do bot.

Sua identidade de bot pode ser gerenciada no Azure de diversas maneiras.

  • Como uma identidade gerenciada atribuída pelo usuário, você não precisa 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 bot.

Para solicitar um token de acesso do serviço de logon, emita a seguinte solicitação, substituindo MICROSOFT-APP-ID e MICROSOFT-APP-PASSWORD pela AppID e a senha do bot, as quais você obteve ao registrar o bot com o Serviço de 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

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

Se o aplicativo estiver autorizado pelo serviço de logon, o corpo da resposta JSON especificará o token de acesso, seu tipo e sua validade (em segundos).

Ao adicionar o token ao cabeçalho Authorization de uma solicitação, você deve usar o valor exato especificado nesta resposta (não escape nem codifique o valor do token). O token de acesso é válido até que ele expire. Para impedir que a expiração do token afete o desempenho do bot, é possível optar por armazenar em cache e atualizar proativamente o token.

Este exemplo mostra uma resposta do serviço de logon da conta do 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: Especificar o token JWT no cabeçalho de autorização das solicitações

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

Authorization: Bearer ACCESS_TOKEN

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

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

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

(JSON-serialized Activity message goes here)

Importante

Especifique apenas o token JWT no cabeçalho Authorization das solicitações que você enviar para o serviço do Bot Connector. Não envie o token por canais não seguros e NÃO o inclua em solicitações HTTP enviadas a outros serviços. O token JWT que você obtém do serviço de logon da conta do Microsoft Entra ID é como uma senha e deve ser manipulado com bastante cuidado. Qualquer pessoa que possua o token pode usá-lo para executar operações em nome do seu bot.

Bot ao Conector: componentes JWT de exemplo

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
}

Observação

Os campos reais podem variar na prática. Crie e valide todos os tokens JWT conforme especificado acima.

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

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

Para autenticar as chamadas do serviço do Bot Connector:

  1. O bot obtém o token JWT do cabeçalho de autorização em solicitações enviadas do serviço do Bot Connector.
  2. O bot obtém o documento de metadados do OpenID para o serviço do 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 OpenID

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

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

Dica

Essa é uma URL estática que você pode codificar no aplicativo.

O exemplo a seguir mostra um documento de metadados do OpenID que é retornado na resposta à solicitação GET. A propriedade jwks_uri especifica o local do documento que contém as chaves de assinatura válidas do serviço do 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 uma lista das chaves de assinatura válidas, emita uma solicitação GET por meio de HTTPS para a URL especificada pela propriedade jwks_uri no documento de metadados do 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.

Dica

A lista de chaves é estável e pode ser armazenada em cache, mas chaves novas podem ser adicionadas a qualquer momento. Para garantir que o bot tenha uma cópia atualizada do documento antes que essas chaves sejam usadas, todas as instâncias do bot devem atualizar o cache local do documento pelo menos uma vez a cada 24 horas.

A propriedade endorsements dentro de cada chave contém uma ou mais sequências de endosso que você pode usar para verificar se a ID de canal especificada na propriedade channelId dentro do objeto de Atividade da solicitação recebida é autêntica. A lista de IDs de canal que exigem endossos é configurável em cada bot. Por padrão, essa será a lista de todas as IDs de canal publicadas, embora os desenvolvedores de bots possam substituir os valores da ID de canal selecionados de qualquer forma.

Etapa 4: Verificar o token JWT

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

Bibliotecas de análise de JWT estão disponíveis para várias plataformas, e a maioria implementa análise segura e confiável para tokens JWT, embora normalmente seja necessário configurar essas bibliotecas para exigir que certas características do token (seu emissor, audiência etc.) contenham valores corretos. Ao analisar o token, é necessário configurar a biblioteca de análise ou gravar sua própria validação para garantir que o token atenda a esses requisitos:

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

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

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

Importante

Todos esses requisitos são importantes, especialmente os requisitos 4 e 6. A não implementação desses requisitos de verificação deixará o bot aberto a ataques que podem fazer o bot divulgar seu token JWT.

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

Conector ao Bot: componentes JWT de exemplo

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
}

Observação

Os campos reais podem variar na prática. Crie e valide todos os tokens JWT conforme especificado acima.

Autenticar solicitações do serviço do Bot Framework Emulator para o bot

O Bot Framework Emulator é uma ferramenta da área de trabalho que você pode usar para testar a funcionalidade do bot. Embora o Bot Framework Emulator use as mesmas tecnologias de autenticação descritas acima, não é possível representar o serviço verdadeiro do Bot Connector. Em vez disso, ele usa a ID e senha do Aplicativo da Microsoft que você especifica ao conectar o Emulator ao bot para criar tokens que são idênticos aos criados pelo bot. Quando o Emulator envia uma solicitação ao bot, ele especifica o token JWT no cabeçalho Authorization da solicitação (essencialmente, usando as credenciais do próprio bot para autenticar a solicitação).

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

Para autenticar chamadas do Bot Framework Emulator:

  1. O bot obtém o token JWT do cabeçalho de autorização em solicitações enviadas do Bot Framework Emulator.
  2. O bot obtém o documento de metadados do OpenID para o serviço do 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 OpenID da MSA

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

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

O exemplo a seguir mostra um documento de metadados do OpenID que é retornado na resposta à solicitação GET. A propriedade jwks_uri 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 uma lista das chaves de assinatura válidas, emita uma solicitação GET por meio de HTTPS para a URL especificada pela propriedade jwks_uri no documento de metadados do 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 Emulator, é preciso extrair o token do cabeçalho Authorization da solicitação, analisar o token, verificar seu conteúdo e verificar a assinatura.

Bibliotecas de análise de JWT estão disponíveis para várias plataformas, e a maioria implementa análise segura e confiável para tokens JWT, embora normalmente seja necessário configurar essas bibliotecas para exigir que certas características do token (seu emissor, audiência etc.) contenham valores corretos. Ao analisar o token, é necessário configurar a biblioteca de análise ou gravar sua própria validação para garantir que o token atenda a esses requisitos:

  1. O token foi enviado no cabeçalho Authorization HTTP com o esquema de "Portador".
  2. O token é um 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. Verificar ambos os valores de emissor garantirá que você esteja verificando tanto o protocolo de segurança v3.1 como os valores de emissor v3.2.
  4. O token contém uma declaração "audiência" com um valor igual à ID de Aplicativo da Microsoft do bot.
  5. O Emulator, 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 período de validade. A defasagem horária padrão do setor é de 5 minutos.
  7. O token tem uma assinatura de criptografia válida com uma chave listada no documento de chaves do OpenID que foi recuperado na Etapa 3.

Observação

O requisito 5 é específico para o caminho de verificação do Emulator.

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

Importante

Todos esses requisitos são importantes, especialmente os requisitos 4 e 7. A não implementação desses requisitos de verificação deixará o bot aberto a ataques que podem fazer o bot divulgar seu token JWT.

Emulador ao Bot: componentes JWT de exemplo

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
}

Observação

Os campos reais podem variar na prática. Crie e valide todos os tokens JWT conforme especificado acima.

Alterações do protocolo de segurança

Autenticação de Bot ao Conector

URL de logon do OAuth

Versão do protocolo Valor válido
v3.1 e v3.2 https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token

Escopo do OAuth

Versão do protocolo Valor válido
v3.1 e v3.2 https://api.botframework.com/.default

Autenticação de Conector ao Bot

Documento de metadados do OpenID

Versão do protocolo Valor válido
v3.1 e v3.2 https://login.botframework.com/v1/.well-known/openidconfiguration

Emissor JWT

Versão do protocolo Valor válido
v3.1 e v3.2 https://api.botframework.com

Autenticação de Emulador ao Bot

URL de logon do OAuth

Versão do protocolo Valor válido
v3.1 e v3.2 https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token

Escopo do OAuth

Versão do protocolo Valor válido
v3.1 e v3.2 ID do Aplicativo da Microsoft + /.default do bot

Audiência JWT

Versão do protocolo Valor válido
v3.1 e v3.2 ID do Aplicativo da Microsoft do bot

Emissor JWT

Versão do protocolo Valor válido
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

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

Documento de metadados do OpenID

Versão do protocolo Valor válido
v3.1 e v3.2 https://login.microsoftonline.com/botframework.com/v2.0/.well-known/openid-configuration

Recursos adicionais