Autenticação de chave de API

A autenticação de chave de API é um método usado para autenticar o acesso ao seu aplicativo de extensão de mensagem usando uma API. Envolve o uso de uma chave de API exclusiva, que é passada com cada solicitação de API para verificar a identidade do usuário ou do aplicativo que iniciou a solicitação. A chave de API deve ser registrada no Microsoft Teams e, quando um usuário interage com sua extensão de mensagem, o Teams usa o segredo para se autenticar com sua API.

As seguintes propriedades de registro de chave de API ajudam você a proteger sua chave e garantir que ela esteja limitada ao seu aplicativo:

• URL base: o Teams transmite o segredo para os pontos de extremidade de URL que começam com o valor nesse campo.
• Locatário de destino: para limitar o acesso à API ao seu locatário do Microsoft 365 ou a qualquer locatário.
• ID do aplicativo: para limitar o acesso da chave a um aplicativo específico ou a qualquer aplicativo.
• Chave de API: para autenticar o acesso ao seu aplicativo.

Você pode registrar uma chave de API por meio do Portal do Desenvolvedor do Teams e gerar uma ID de registro de chave de API. Atualize o manifesto do aplicativo com o apiSecretServiceAuthConfiguration objeto com uma apiSecretRegistrationId propriedade. Esta propriedade deve conter a ID de registro da chave de API retornada quando você enviou a chave de API por meio do Portal do Desenvolvedor do Teams.

Quando uma solicitação de API é iniciada, o sistema recupera a chave de API de um banco de dados criptografado e a inclui no cabeçalho de autorização, usando o esquema de token de portador. O sistema envia o cabeçalho de autorização com a chave de API para o ponto de extremidade definido no manifesto do aplicativo.

O exemplo a seguir mostra a carga com o cabeçalho de autorização usando o esquema de token de portador:

GET https://example.com/search?myQuery=test
Accept-Language: en-US
Authorization: Bearer <MY_API_KEY>

Registrar uma chave de API

Para registrar uma chave de API, siga estas etapas:

1. Vá paraRegistro de chave de API deFerramentas>.

   

2. Selecione + Nova chave de API.

3. Na página de registro de chave de API , selecione + Adicionar segredo. A caixa de diálogo Adicionar uma chave de API é exibida.

4. Insira um valor para a chave e selecione Salvar.

   Observação

   Você pode manter até duas chaves de API. Se precisar substituir uma, você poderá fazê-lo sem interrupção do serviço, pois o Teams usa a outra chave configurada durante o processo de atualização.

   

5. Em Nome da chave de API, adicione um nome significativo para a chave de API. Por exemplo, chave de API para extensão de mensagem da Contoso.

6. Em URL base, especifique uma URL base comum para todos os pontos de extremidade da API que devem ser chamados. Essa URL deve começar com https, incluir um nome de domínio totalmente qualificado e, opcionalmente, um caminho. O Teams transmite a chave para o ponto de extremidade da URL que começa com o valor nesse campo. Por exemplo, https://api.yelp.com.

   A URL base garante que a chave permaneça segura e não vaze para pontos de extremidade aleatórios, mesmo que outro aplicativo adquira ilicitamente a ID de registro da chave de API e a incorpore ao seu próprio aplicativo. Se a URL registrada na configuração da chave de API não for um prefixo para os pontos de extremidade de destino definidos na especificação OpenAPI, a chamada será descartada.

   

7. Em Locatário de destino, selecione uma das seguintes opções:

   • Locatário inicial: a chave de API só funciona no locatário em que está registrada.
   • Qualquer locatário: a chave de API pode ser usada em qualquer locatário.

   

8. Em Aplicativo Teams de Destino, selecione qualquer um dos seguintes:

   • Aplicativo Teams existente: a opção de aplicativo Teams existente vincula a ID de registro da chave de API ao seu aplicativo Teams específico.
   • Qualquer aplicativo do Teams: A chave de API pode ser usada com qualquer aplicativo do Teams.

   

   Uma ID de registro de chave de API é gerada.

   

9. No portal do desenvolvedor para Teams, selecione Aplicativos e selecione um aplicativo ao qual você deseja adicionar a chave de API.

10. Acesse Recursos> do aplicativoExtensão de mensagem.

11. Em Autenticação, selecione a chave de API e adicione a ID de registro da chave de API.

    

12. Selecione Salvar.

A ID de registro da chave de API é atualizada como o valor da propriedade no manifesto apiSecretRegistrationId do aplicativo. Você pode verificar sua ID de registro de chave de API no manifesto do aplicativo no Portal do desenvolvedor do Teams.

Atualizar manifesto do aplicativo

Adicione um apiSecretServiceAuthConfiguration objeto com uma apiSecretRegistrationId propriedade, que contém a ID de referência ao enviar a chave de API por meio do Portal do Desenvolvedor do Teams. Para obter mais informações, consulte composeExtensions.commands.

"composeExtensions": [
    {
      "composeExtensionType": "apiBased",
      "authorization": {
        "authType": "apiSecretServiceAuth",
        "apiSecretServiceAuthConfiguration": {
            "apiSecretRegistrationId": "9xxxxb0f-xxxx-40cc-xxxx-15xxxxxxxxx3"
        }
      },

Práticas recomendadas

• Chave de API:

  • A chave de API deve ter pelo menos 10 caracteres e no máximo 2048 caracteres.
  • Depois de atualizar a chave de API, leva até uma hora para que ela seja refletida em todo o sistema.

• URL base:

  • A URL base deve começar com https para garantir a comunicação segura.
  • Você deve incluir o nome do host completo para especificar o domínio exato.
  • Você pode adicionar um caminho opcional para definir um ponto de entrada específico para a API.

  Essa estrutura é crucial para a segurança de suas chaves de API, pois o Teams envia a chave de API para pontos de extremidade que começam com a URL Base especificada.

• Locatário de destino: à medida que você desenvolve seu aplicativo em seu locatário do Microsoft 365, você o testará inicialmente como um aplicativo personalizado criado para sua organização (aplicativo LOB) ou aplicativo personalizado. Durante esse estágio, você deve registrar a chave de API com seu locatário doméstico como o locatário de destino para garantir que a chave permaneça exclusiva para seu locatário.

  Depois de concluir o teste e estiver pronto para enviar o manifesto do aplicativo para o Partner Center da Teams Store, você precisará alternar a configuração do locatário de destino para Qualquer locatário. Essa alteração permite que sua ID de registro de chave de API seja usada em vários locatários assim que seu aplicativo estiver disponível na Teams Store.

• ID do aplicativo Teams: à medida que você desenvolve seu aplicativo em seu locatário do Microsoft 365 e começa a testá-lo como um aplicativo personalizado criado para sua organização (LOB) ou aplicativo personalizado, você deve definir a ID de registro da chave de API com a ID do aplicativo Teams como Qualquer aplicativo do Teams. Essa configuração permite que a chave seja usada com qualquer aplicativo do Teams carregado como um aplicativo personalizado e aplicativos personalizados criados para sua organização (aplicativos LOB) para gerar IDs após serem carregados. Você não terá a ID do aplicativo neste estágio.

  A segurança da sua chave ainda é mantida por meio do Locatário Inicial e da URL Base. Quando estiver pronto para lançar seu aplicativo para o mundo, você precisará alterar a configuração de ID do aplicativo do Teams para Aplicativo do Teams existente e inserir sua ID do aplicativo do Teams. Por fim, envie o manifesto do aplicativo ao Partner Center para inclusão na Teams Store. O registro da sua chave de API agora está vinculado ao seu aplicativo específico do Teams e não pode ser usado com outros.

  Para um aplicativo personalizado criado para sua organização (LOB) ou aplicativo personalizado, há uma ID de aplicativo interno que é difícil de acessar. Nesse cenário, limite a configuração ao locatário em que o aplicativo é usado. Para outros aplicativos, vincule o registro da chave de API à ID do aplicativo publicado depois de publicá-lo na Teams Store.

Confira também

• Criar extensão de mensagem baseada em API
• Configurar sua extensão de mensagem baseada em API no Microsoft Entra ID
• Autenticar usuários no Microsoft Teams
• Habilitar autenticação OAuth para extensão de mensagem baseada em API