Esquemas de autenticação para plug-ins de API para Microsoft 365 Copilot

Artigo
11/22/2024

Importante

Os plug-ins de API só são suportados como ações dentro de agentes declarativos. Não estão ativados no Microsoft 365 Copilot.

Os plug-ins de API para Microsoft 365 Copilot suportam três esquemas de autenticação para ligar às respetivas APIs de back-end.

Fluxo de código de autorização do OAuth 2.0
Chave de API através da autenticação de portador
Sem autenticação (anónimo)

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

Este esquema de autenticação permite que um plug-in aceda a uma API com um token de portador adquirido por um fluxo de código de autorização OAuth 2.0. Este esquema pode ser representado num documento OpenAPI na securitySchemes propriedade . Consulte OAuth 2.0 para obter detalhes.

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.

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

Para utilizar este esquema de autenticação num plug-in, tem de registar um cliente OAuth no portal do Programador do Teams.

Dica

Se o seu documento OpenAPI incluir a propriedade , o securitySchemes Teams Toolkit pode registar o seu cliente OAuth e atualizar o manifesto automaticamente quando gerar um plug-in a partir de uma API existente.

Se o seu fornecedor de OAuth suportar a Chave de Prova para o Code Exchange (PKCE), anule o comentário da seguinte linha no teamsapp.yml no projeto de plug-in da API.

# isPKCEEnabled: true

Registar um cliente OAuth

Observação

Se o seu fornecedor de OAuth precisar de especificar URIs de redirecionamento permitidos ao registar a sua aplicação, inclua https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect nos URIs de redirecionamento permitidos.

Abra o browser e navegue para o portal do programador de aplicações do Teams. Selecione Ferramentas no painel de navegação esquerdo.
Selecione Registo de cliente OAuth. Se não tiver registos existentes, selecione Registar cliente; se tiver registos existentes, selecione Novo registo de cliente OAuth.
Preencha os seguintes campos.
- Nome do registo: um nome amigável para o registo
- URL Base: o URL base da API
- ID de Cliente: o ID de cliente ou O ID da aplicação emitido pelo servidor OAuth 2.0
- Segredo do cliente: o segredo do cliente emitido pelo servidor OAuth 2.0
- Ponto final de autorização: o URL do servidor OAuth 2.0 que as aplicações utilizam para pedir um código de autorização
- Ponto final de token: o URL do servidor OAuth 2.0 que as aplicações utilizam para resgatar um código para um token de acesso
- Atualizar ponto final: o URL do servidor OAuth 2.0 que as aplicações utilizam para atualizar o token de acesso
- Âmbito: o âmbito de permissão definido pela API que concede acesso.
- Ativar a Chave de Prova para o Code Exchange (PKCE): ative esta definição se o seu fornecedor de OAuth suportar PKCE.
Selecione Salvar.

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

Adicionar a autenticação OAuth 2.0 ao manifesto de plug-in

Para utilizar a autenticação OAuth 2.0 no plug-in, 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": "client registration ID"
},

Chave de API através da autenticação de portador

Este esquema de autenticação permite que um plug-in aceda a uma API através de um token ou chave de API de longa duração. Este token é enviado em pedidos de API no Authorization cabeçalho como um token de portador. Este esquema pode ser representado num documento OpenAPI na securitySchemes propriedade . Veja Bearer Authentication (Autenticação do Portador ) para obter detalhes.

securitySchemes:
  BearerAuth:
    type: http
    scheme: bearer

Observação

Os plug-ins de API não suportam o esquema de segurança da chave de API OpenAPI. As APIs que utilizam chaves de API para autenticação têm de utilizar o esquema de segurança de autenticação de portador e aceitar a chave de API no Authorization cabeçalho. Não pode definir um cabeçalho personalizado nem enviar a chave como um parâmetro de consulta ou cookie.

Para utilizar este esquema de autenticação num plug-in, tem de registar uma chave de API no portal do Programador do Teams.

Dica

Se o seu documento OpenAPI incluir a propriedade , o securitySchemes Teams Toolkit pode registar a sua chave de API e atualizar o seu manifesto automaticamente quando gerar um plug-in a partir de uma API existente.

Registar uma chave de API

Abra o browser e navegue para o portal do programador de aplicações do Teams. Selecione Ferramentas no painel de navegação esquerdo.
Selecione Registo de chave de API. Se não tiver registos existentes, selecione Registar cliente; se tiver registos existentes, selecione Nova chave de API.
Selecione Adicionar segredo e introduza a chave de API.
Preencha os seguintes campos.
- Nome da chave da API: um nome amigável para o registo
- URL Base: o URL base da API
Selecione Salvar.

A conclusão do registo gera um ID de registo de chave de aplicação.

Adicionar a autenticação da chave de API ao manifesto de plug-in

Para utilizar a autenticação da chave de API no 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 aplicação 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"
},

Compartilhar via