Compartilhar via

Autenticação da chave de API

  • Artigo

A autenticação da chave de API é um método utilizado para autenticar o acesso à sua aplicação de extensão de mensagens com uma API. Envolve a utilização de uma chave de API exclusiva, que é transmitida com cada pedido da API para verificar a identidade do utilizador ou da aplicação que iniciou o pedido. A chave de API tem de estar registada no Microsoft Teams e, quando um utilizador interage com a sua extensão de mensagem, o Teams utiliza o segredo para autenticar com a sua API.

As seguintes propriedades de registo de chave de API ajudam-no a proteger a sua chave e a garantir que está limitada à sua aplicação:

  • URL base: o Teams transmite o segredo para pontos finais de URL que começam com o valor neste campo.
  • Inquilino de Destino: para limitar o acesso da API ao seu inquilino do Microsoft 365 ou a qualquer inquilino.
  • ID da Aplicação: para limitar o acesso da chave a uma aplicação específica ou a qualquer aplicação.
  • Chave de API: para autenticar o acesso à sua aplicação.

Pode registar uma chave de API através do Portal do Programador do Teams e gerar um ID de registo de chave de API. Atualize o manifesto da aplicação com o apiSecretServiceAuthConfiguration objeto com uma apiSecretRegistrationId propriedade. Esta propriedade tem de conter o ID de registo da chave de API devolvido quando submeteu a chave de API através do Portal do Programador para Teams.

Observação

Tem de garantir que protege o ID de registo da chave de API, uma vez que pode ser obtido a partir do manifesto da aplicação Teams. Para obter mais informações sobre como proteger a chave de API, veja melhores práticas.

Quando um pedido de API é iniciado, o sistema obtém a chave de API a partir de uma base de dados encriptada e inclui-a no cabeçalho de autorização, utilizando o esquema de token de portador. O sistema envia o cabeçalho de autorização com a chave de API para o ponto final definido no manifesto da aplicação.

O exemplo seguinte mostra o payload com o cabeçalho de autorização com o esquema de token de portador:

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

Registar uma chave de API

Para registar uma chave de API, siga estes passos:

  1. Aceda a Ferramentas>Registo de chave de API.

    Captura de ecrã a mostrar a opção de registo da chave de API no Portal do Programador do Teams.

  2. Selecione + Nova chave de API.

  3. Na página registo da chave de API , selecione + Adicionar Segredo. É apresentada a caixa de diálogo Adicionar uma chave de API .

  4. Introduza um valor para a chave e selecione Guardar.

    Observação

    Pode manter até duas chaves de API. Se precisar de substituir uma, pode fazê-lo sem interrupção do serviço, uma vez que o Teams utiliza a outra chave configurada durante o processo de atualização.

    Captura de ecrã a mostrar a caixa de diálogo Adicionar uma chave de API para adicionar a chave de API à sua aplicação.

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

  6. Em URL base, especifique um URL base comum para todos os pontos finais da API que têm de ser chamados. Este URL tem de começar com https, incluir um nome de domínio completamente qualificado e, opcionalmente, um caminho. O Teams transmite a chave para o ponto final de URL que começa com o valor neste campo. Por exemplo, https://api.yelp.com.

    O URL base garante que a chave permanece segura e não é divulgada para pontos finais aleatórios, mesmo que outra aplicação adquira ilicitamente o ID de registo da chave de API e a incorpore na sua própria aplicação. Se o URL registado na configuração da chave de API não for um prefixo para os pontos finais de destino definidos na especificação OpenAPI, a chamada é removida.

    Captura de ecrã a mostrar as opções Descrição e Adicionar domínio na página de registo da chave de API no Portal do Programador do Teams.

  7. Em Inquilino de destino, selecione uma das seguintes opções:

    • Inquilino principal: a chave de API só está funcional no inquilino onde está registada.
    • Qualquer inquilino: a chave de API é utilizável em qualquer inquilino.

    Captura de ecrã a mostrar as opções Inquilino principal e Qualquer inquilino em Definir um cabeçalho de inquilino de destino no Portal do Programador para Teams.

  8. Em Aplicação De destino do Teams, selecione uma das seguintes opções:

    • Aplicação Teams existente: a opção da aplicação Teams existente vincula o ID de registo da chave de API à sua aplicação específica do Teams.
    • Qualquer aplicação do Teams: a chave de API pode ser utilizada com qualquer aplicação do Teams.

    Captura de ecrã a mostrar a aplicação Qualquer Teams e as opções da aplicação Teams existentes em Definir um cabeçalho de aplicação do Teams no Portal do Programador para Teams.

    É gerado um ID de registo da chave de API .

    Captura de ecrã a mostrar o ID de registo da chave de API gerado no Portal do Programador para Teams.

  9. No Portal do programador do Teams, selecione Aplicações e selecione uma aplicação onde pretende adicionar a chave de API.

  10. Aceda a Funcionalidades >da aplicaçãoExtensão de mensagem.

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

    Captura de ecrã a mostrar um exemplo da secção Autenticação sem nenhuma e opções de chave de API no Portal do Programador para Teams.

  12. Selecione Salvar.

O ID de registo da chave de API é atualizado como o valor da apiSecretRegistrationId propriedade no manifesto da aplicação. Pode verificar o ID de registo da chave de API no manifesto da aplicação no Portal do Programador do Teams.

Atualizar manifesto do aplicativo

Adicione um apiSecretServiceAuthConfiguration objeto com uma apiSecretRegistrationId propriedade, que contém o ID de referência quando submete a chave de API através do Portal do Programador para 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 tem de ter, pelo menos, 10 carateres e, no máximo, 128 carateres.
    • Depois de atualizar a chave de API, a chave demora até uma hora a refletir em todo o sistema.

  • URL base:

    • O URL base tem de começar por https para garantir uma comunicação segura.
    • Tem de incluir o nome completo do anfitrião para especificar o domínio exato.
    • Pode adicionar um caminho opcional para definir um ponto de entrada específico para a API.

    Esta estrutura é crucial para a segurança das suas chaves de API, uma vez que o Teams envia a chave de API para pontos finais que começam com o URL Base especificado.

  • Inquilino de destino: à medida que desenvolve a sua aplicação no seu inquilino do Microsoft 365, irá testá-la inicialmente como uma aplicação personalizada criada para a sua organização (aplicação LOB) ou aplicação personalizada. Durante esta fase, tem de registar a chave de API no seu inquilino Home Page como o inquilino de destino para garantir que a chave permanece exclusiva do seu inquilino.

    Depois de concluir os testes e estar pronto para submeter o manifesto da aplicação para o Centro de Parceiros da Loja Teams, terá de mudar a definição de inquilino de destino para Qualquer inquilino. Esta alteração permite que o ID de registo da chave de API seja utilizado em vários inquilinos assim que a sua aplicação estiver disponível na Loja Teams.

  • ID da aplicação teams: à medida que desenvolve a sua aplicação no seu inquilino do Microsoft 365 e começa a testá-la como uma aplicação personalizada criada para a sua organização (LOB) ou aplicação personalizada, tem de definir o ID de registo da chave de API com o ID da aplicação Teams como qualquer aplicação do Teams. Esta configuração permite que a chave seja utilizada com qualquer aplicação do Teams carregada como uma aplicação personalizada e aplicações personalizadas criadas para a sua organização (aplicações LOB) para gerar IDs após serem carregados. Não terá o ID da aplicação nesta fase.

    A segurança da sua chave continua a ser mantida através do Inquilino Principal e do URL Base. Quando estiver pronto para lançar a sua aplicação para o mundo, tem de alterar a definição ID da aplicação Teams para a aplicação Teams existente e introduzir o ID da aplicação Teams. Por fim, submeta o manifesto da aplicação para o Centro de Parceiros para inclusão na Loja Teams. O registo da chave de API está agora associado à sua aplicação específica do Teams e não pode ser utilizado com outras pessoas.

Confira também