Autenticação com a API do Bot Connector

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.

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:

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

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.

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

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
}

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

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.

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

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
}

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.

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

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
}

Alterações do protocolo de segurança

Autenticação de Bot ao Conector

URL de logon do OAuth

Escopo do OAuth

Autenticação de Conector ao Bot

Documento de metadados do OpenID

Emissor JWT

Autenticação de Emulador ao Bot

URL de logon do OAuth

Escopo do OAuth

Audiência JWT

Emissor JWT

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

Documento de metadados do OpenID

Recursos adicionais

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