Compartilhar via

Configurar a autenticação para plug-ins de API em agentes

  • Artigo

Pode configurar a autenticação para plug-ins de API em agentes em execução no Microsoft 365 Copilot ao utilizar qualquer um dos quatro esquemas de autenticação suportados para ligar de forma totalmente integrada às respetivas APIs de back-end:

  • Fluxo de código de autorização do OAuth 2.0
  • Microsoft Entra ID autenticação de início de sessão único (SSO)
  • Autenticação da chave de API
  • Sem autenticação (anónimo)

Fluxo de código de autorização do OAuth 2.0

Um plug-in pode aceder a uma API com um token de portador obtido através do fluxo de código de autorização OAuth 2.0, com suporte opcional de Chave de Prova para o Code Exchange (PKCE).

Antes de começar, tem de se registar no seu fornecedor OAuth 2.0 para obter um ID de cliente e um segredo. Se o seu fornecedor de OAuth exigir que especifique URIs de redirecionamento permitidos durante o registo de aplicações, certifique-se de que inclui https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect na lista.

Importante

O suporte de plug-ins de API para o OAuth 2.0 tem as seguintes limitações.

  • Os plug-ins de API só suportam o fluxo de código de autorização para OAuth 2.0.
  • Os servidores OAuth 2.0 que devolvem 307 Temporary Redirect códigos http status do ponto final do token não são suportados.

Pode definir este esquema na securitySchemes propriedade de um documento OpenAPI. Para obter mais informações, consulte OAuth 2.0.

securitySchemes:
  OAuth2:
    type: oauth2
    flows:
      authorizationCode:
        authorizationUrl: <authorization_url>
        tokenUrl: <token_url>
        refreshUrl: <refresh_url>
        scopes:
          scope: description

Para ativar a autenticação OAuth 2.0, tem de registar um cliente OAuth no portal de programador do Teams. Pode registar um cliente OAuth no Teams Toolkit no Visual Studio Code ou ao registar-se manualmente no portal de programador do Teams.

Registar um cliente OAuth com o Teams Toolkit

O Teams Toolkit regista o seu cliente OAuth e atualiza o seu pacote de aplicações automaticamente quando cria um agente com o plug-in da API a partir de um documento OpenAPI existente. Tem de ter a securitySchemes propriedade definida no documento OpenAPI.

Se o seu fornecedor de OAuth suportar PKCE, anule o comentário da seguinte linha de código no teamsapp.yml no projeto do agente antes de aprovisionar o agente.

# isPKCEEnabled: true

Registar um cliente OAuth no portal de programador do Teams

  1. Abra o portal do programador do Teams. Selecione Ferramentas ->Registo de cliente OAuth.

  2. Se não tiver registos existentes, selecione Registar cliente. Se tiver registos existentes, selecione Novo registo de cliente OAuth.

  3. Preencha os seguintes campos.

    • Nome do registo: um nome amigável para o registo.
    • URL base: o URL base da API. Este valor deve corresponder a uma entrada na servers matriz no seu documento OpenAPI.
    • ID de Cliente: o ID de cliente ou O ID da aplicação emitido pelo seu fornecedor OAuth 2.0.
    • Segredo do cliente: o segredo do cliente emitido pelo seu fornecedor OAuth 2.0.
    • Ponto final de autorização: o URL do fornecedor OAuth 2.0 que as aplicações utilizam para pedir um código de autorização
    • Ponto final de token: o URL do fornecedor OAuth 2.0 que as aplicações utilizam para resgatar um código para um token de acesso
    • Atualizar ponto final: o URL do fornecedor OAuth 2.0 que as aplicações utilizam para atualizar o token de acesso
    • Âmbito: o âmbito de permissão definido pela API que permite o acesso.
    • Ativar a Chave de Prova para o Code Exchange (PKCE): ative esta definição se o seu fornecedor de OAuth suportar PKCE.

  4. Selecione Salvar.

  5. A conclusão do registo gera um ID de registo de cliente OAuth.

Adicionar o ID de registo do cliente ao manifesto do plug-in

Para utilizar a autenticação OAuth 2.0 para o plug-in da API, defina a type propriedade do objeto de autenticação de runtime como OAuthPluginVaulte defina o reference_id para o ID de registo de cliente a partir do Portal do Programador do Teams.

"auth": {
  "type": "OAuthPluginVault",
  "reference_id": "auth registration ID"
},

autenticação do SSO do Microsoft Entra ID

Microsoft Entra ID a autenticação SSO permite a integração totalmente integrada do início de sessão único (SSO), permitindo que os utilizadores se autentiquem com as credenciais de Microsoft Entra ID existentes. Esta integração simplifica a gestão de acessos e garante ligações seguras às APIs sem que sejam necessárias credenciais adicionais. A API tem de utilizar Microsoft Entra ID para controlar o acesso.

Registar um cliente SSO no portal de programador do Teams

  1. Abra o portal do programador do Teams. Selecione Ferramentas ->Microsoft Entra registo de ID de cliente SSO.

  2. Se não tiver registos existentes, selecione Registar ID de cliente. Se tiver registos existentes, selecione Novo registo de cliente.

  3. Preencha os seguintes campos.

    • Nome do registo: um nome amigável para o registo.
    • URL base: o URL base da API. Este valor deve corresponder a uma entrada na servers matriz no seu documento OpenAPI.
    • Restringir a utilização por organização: selecione a organização do Microsoft 365 que tem acesso à sua aplicação para aceder aos pontos finais da API.
    • Restringir a utilização por aplicação: selecione Qualquer aplicação do Teams se não souber o ID final da aplicação. Depois de publicar a sua aplicação, vinculte este registo com o ID da aplicação publicada.
    • ID de Cliente: o ID de cliente da aplicação registada no Microsoft Entra.

  4. Selecione Salvar.

  5. A conclusão do registo gera um ID de registo de SSO Microsoft Entra e um URI do ID da Aplicação.

Atualizar o registo da aplicação Microsoft Entra

  1. Abra centro de administração do Microsoft Entra. Atualize o Microsoft Entra registo de aplicações que protege a sua API com o URI do ID da Aplicação gerado pelo portal do programador do Teams. Se tiver um URI de ID de aplicação existente mapeado para o registo da aplicação, pode utilizar o editor de manifestos para adicionar outro URI na secção identifierUris .

    "identifierUris": [
  "<<URI1>>"
  "<<URI2>>"
]

    Observação

    A adição de vários URIs não é suportada através da IU do centro de administração do Microsoft Entra. A IU só apresenta o primeiro URI na lista. Adicionar vários URIs não afeta os URIs e os âmbitos existentes, mesmo que sejam apresentados de forma diferente na IU.

  2. Selecione Autenticação em Gerenciar. Adicione https://teams.microsoft.com/api/platform/v1.0/oAuthConsentRedirect aos URIs de Redirecionamento na plataforma Web .

  3. Selecionar Expor uma API em Gerenciar. Selecione Adicionar uma aplicação cliente e adicione o ID de cliente do arquivo de tokens empresariais da Microsoft, ab3be6b7-f5df-413d-ac2d-abf1e3fd9c0b.

Adicionar o ID de registo SSO ao manifesto do plug-in

Defina a type propriedade do objeto de autenticação de runtime como OAuthPluginVaulte defina o reference_id para o Microsoft Entra ID de registo de SSO no portal do programador do Teams.

"auth": {
  "type": "OAuthPluginVault",
  "reference_id": "SSO registration ID"
},

Adicionar a nova audiência de tokens à sua API

Atualize a API para permitir o novo URI do identificador como público-alvo do token. Se a API validar o ID da aplicação cliente, confirme que o ID de cliente do arquivo de tokens da Microsoft Enterprise (ab3be6b7-f5df-413d-ac2d-abf1e3fd9c0b) é adicionado como uma aplicação cliente permitida.

Dica

Se a sua API utilizar o fluxo em nome de para obter acesso a outra API Web que exija que o utilizador conceda consentimento, devolva um 401 Unauthorized erro para fazer com que o agente peça ao utilizador para iniciar sessão para conceder consentimento.

Autenticação da chave de API

Algumas APIs utilizam chaves de API para autorização. Uma chave de API é um segredo partilhado que o cliente inclui nos pedidos da API para autenticar e obter acesso. Os plug-ins de API suportam o envio da chave de API de três formas:

  • Como token de portador no Authorization cabeçalho
  • Como um valor num cabeçalho personalizado
  • Como parâmetro de consulta

Adicionar a chave de API ao seu documento OpenAPI

Microsoft 365 Copilot determina como enviar a chave de API com base na securitySchemes entrada no seu documento OpenAPI.

Token de portador

Se a sua API aceitar a chave de API como um token de portador, ative a autenticação do Portador no documento OpenAPI. Para obter mais informações, veja Autenticação de portador.

securitySchemes:
  BearerAuth:
    type: http
    scheme: bearer

Cabeçalho personalizado

Se a API aceitar a chave de API num cabeçalho personalizado, ative a autenticação da chave de API no seu documento OpenAPI com a in propriedade definida como header e a name propriedade definida como o nome do cabeçalho. Para obter mais informações, veja Chaves de API.

securitySchemes:
  ApiKeyAuth:
    type: apiKey
    in: header
    name: X-API-KEY

Parâmetro de consulta

Se a API aceitar a chave de API num parâmetro de consulta, ative a autenticação da chave de API no documento OpenAPI com a in propriedade definida query como e a name propriedade definida como o nome do parâmetro de consulta. Para obter mais informações, veja Chaves de API.

securitySchemes:
  ApiKeyAuth:
    type: apiKey
    in: query
    name: api_key

Registar uma chave de API

Para ativar a autenticação da chave de API, tem de registar a chave de API no portal do programador do Teams. Pode registar a chave de API no Teams Toolkit no Visual Studio Code ou ao registar-se manualmente no portal de programador do Teams.

Registar uma chave de API no Teams Toolkit

O Teams Toolkit regista a sua chave de API e atualiza o pacote de aplicação automaticamente quando cria um agente com o plug-in da API a partir de um documento OpenAPI existente. Tem de ter a securitySchemes propriedade definida no documento OpenAPI.

Observação

O Teams Toolkit só suporta chaves de API como tokens de portador e não pode criar plug-ins de API com base em documentos OpenAPI que utilizem um cabeçalho personalizado ou parâmetro de consulta. Como solução, pode remover temporariamente as securitySchemes propriedades e security do OpenAPI para gerar o pacote de plug-in e, em seguida, adicioná-los novamente ao documento OpenAPI no projeto de plug-in antes do aprovisionamento. Tem de registar manualmente a chave de API.

Registar uma chave de API no portal de programador do Teams

  1. Abra o portal do programador do Teams. Selecione Ferramentas ->Registo de chave de API

  2. Se não tiver registos existentes, selecione Criar uma chave de API. Se tiver registos existentes, selecione Nova chave de API.

  3. Selecione Adicionar segredo e introduza a chave de API.

  4. Preencha os seguintes campos.

    • Nome da chave da API: um nome amigável para o registo.
    • URL base: o URL base da API. Este valor deve corresponder a uma entrada na servers matriz no seu documento OpenAPI.
    • Inquilino de destino: limite ou não o acesso da API ao inquilino principal.
    • Aplicação Teams de Destino: selecione Qualquer aplicação do Teams se não souber o seu ID final da aplicação. Depois de publicar a sua aplicação, vinculte este registo com o ID da aplicação publicada.

  5. Selecione Salvar.

  6. A conclusão do registo gera um ID de registo de chave de API.

Adicionar o ID de registo da chave de API ao manifesto de plug-in
  1. No ficheiro de manifesto do plug-in, defina a type propriedade do objeto de autenticação de runtime como ApiKeyPluginVaulte defina o para o reference_id ID de registo da chave de API no portal do programador do Teams.
"auth": {
  "type": "ApiKeyPluginVault",
  "reference_id": "app key registration ID"
},

Sem autenticação (anónimo)

Para APIs que não necessitam de autenticação ou para ambientes de programador em que a autenticação ainda não está implementada, os plug-ins podem aceder às APIs de forma anónima. Neste caso, defina a type propriedade do objeto de autenticação de runtime como None.

"auth": {
  "type": "None"
},