Autenticação com a API do Bot Connector

Seu bot se comunica com o serviço Bot Connector usando HTTP por meio de um canal seguro (SSL/TLS). Quando o bot envia uma solicitação para o serviço Conector, ele deve incluir informações que o serviço Conector pode usar para verificar sua identidade. Da mesma forma, quando o serviço Conector envia uma solicitação ao 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 no nível do 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 o bot troque mensagens com o serviço do Bot Connector.

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

Tecnologias de autenticação

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

Este artigo descreve como usar essas tecnologias por meio de 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 bot para o serviço do 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 GET HTTP para o Serviço de Logon 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 do Bot Connector.

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

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

• Use uma identidade gerenciada atribuída pelo usuário, para que você não precise gerenciar manualmente as credenciais do bot.
• Como um aplicativo de monousuário.
• 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 for autorizado pelo serviço de logon, o corpo da 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 nessa resposta: não escape nem codifique o valor do token. O token de acesso é válido até a expiração. Para impedir 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 logon 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: Especificar o token JWT no cabeçalho de autorização de solicitações

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

Authorization: Bearer ACCESS_TOKEN

Todas as solicitações enviadas para o serviço do Bot Connector devem incluir o token de acesso no Authorization cabeçalho. Se o token estiver formado corretamente, não estiver expirado e tiver sido gerado pelo serviço de logon da conta Microsoft Entra ID, o serviço Conector de Bot autorizará a solicitação. Verificações adicionais são executadas 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 para Conector: exemplo 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 o seu bot

Quando o serviço Bot Connector envia uma solicitação ao 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 do Bot Connector:

1. Seu bot obtém o token JWT do cabeçalho de autorização em solicitações enviadas pelo serviço Bot Connector.
2. Seu bot obtém o documento de metadados 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 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 do OpenID, emita essa 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 à solicitação GET . 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 a ID do canal especificada na channelId propriedade dentro do objeto Activity da solicitação de entrada é autenticada. A lista de IDs de canal que exigem aprovação é configurável dentro de cada bot. Por padrão, ela será a lista de todas as IDs de canal publicadas, embora os desenvolvedores de bot 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 a análise segura e confiável para tokens JWT, embora você normalmente deva configurar essas bibliotecas para exigir que determinadas 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 gravar sua própria validação para garantir que o token atenda a estes requisitos:

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

Se for necessária aprovação para um identificador de canal:

• Você deve exigir que qualquer Activity objeto 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 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 ao Bot: exemplo 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 á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 do Bot Connector real. Em vez disso, ele usa a ID do aplicativo Microsoft e Microsoft senha do aplicativo que você especifica ao conectar o Emulador ao bot para criar tokens idênticos aos que o bot cria. Quando o Emulador envia uma solicitação ao bot, ele especifica o token JWT no Authorization 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 conector -> bot , mas usa o documento OpenID da MSA em vez do documento OpenID do Bot Connector.

Para autenticar chamadas do Emulador do Bot Framework:

1. Seu bot obtém o token JWT do cabeçalho de autorização em solicitações enviadas do Emulador do Bot Framework.
2. Seu bot obtém o documento de metadados 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 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 à solicitação GET . 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 a análise segura e confiável para tokens JWT, embora você normalmente deva configurar essas bibliotecas para exigir que determinadas 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 gravar sua própria validação para garantir que o token atenda a estes requisitos:

1. O token foi enviado no cabeçalho HTTP Authorization usando o esquema "Bearer".
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 para o protocolo de segurança aplicável. Para a implementação atual, consulte Microsoft. Agents.Connector.
4. O token contém uma declaração "audience" com um valor igual à ID do aplicativo Microsoft do bot.
5. O Emulador, dependendo da versão, envia a 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 de seu período de validade. O desvio de relógio padrão do setor é de 5 minutos.
7. O token tem uma assinatura criptográfica válida com uma chave listada no documento de chaves OpenID que foi recuperada na Etapa 3.

Se o token não atender a todos esses requisitos, o 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 do Bot para Conector

URL de logon do OAuth

Escopo do OAuth

Autenticação do conector para Bot

Documento de metadados do OpenID

Emissor de JWT

Autenticação do Emulador para Bot

URL de logon do OAuth

Escopo do OAuth

Público-alvo do JWT

Emissor de JWT

Para a implementação atual, consulte Microsoft. Agents.Connector.

Documento de metadados do OpenID

Recursos adicionais

• Solucionar problemas de autenticação do Bot Framework
• Especificação do protocolo de atividade
• Referência da API RestConnectorClient
• JSON Web Token (JWT) draft-jones-json-web-token-07
• JWS (JSON Web Signature) draft-jones-json-web-signature-04
• JSON Web Key (JWK) RFC 7517