Integrar um plug-in de API com uma API protegida pelo OAuth

Outro padrão comum de proteção de APIs é a utilização de OAuth. O OAuth é um protocolo padrão da indústria para autorização. O OAuth protege o acesso aos recursos através de tokens de acesso. Para obter um token de acesso, registe uma aplicação no fornecedor de identidade e especifique o respetivo tipo, como cliente público ou confidencial. Dependendo do tipo da sua aplicação, poderá ter de configurar definições adicionais, como um segredo ou um certificado.

Quando os utilizadores abrem a sua aplicação, inicia o processo de obtenção de um token de acesso. Os passos exatos que a aplicação segue dependem do tipo de aplicação e do fluxo que utiliza. Quando os utilizadores concluírem o fluxo de autorização, recebem um token de acesso que podem utilizar para chamar a API.

Quando integra plug-ins de API com a API protegida pelo OAuth, precisa do ID de cliente e do segredo do cliente da aplicação que protege a API. Também precisa dos pontos finais de autorização, token e atualização do fornecedor de identidade. Microsoft 365 Copilot utiliza estas informações para autenticar com a API em nome do utilizador atual e obter um token de acesso. Uma vez que as informações são confidenciais, armazena-as em segurança na localização de armazenamento segura no Microsoft 365, também conhecido como cofre. Em seguida, na sua aplicação, faz referência ao ID da entrada do cofre. No runtime, o agente declarativo carrega o plug-in (2) e obtém as informações da entrada designada (3a). O agente declarativo segue o tipo de concessão de código de autorização, também conhecido como fluxo de código de autenticação, para obter um token de acesso (3b) que utiliza para chamar a API (3c). O esquema a seguir ilustra esse processo.

Ao configurar as informações do OAuth para o plug-in, pode ativar opcionalmente a Chave de Prova para o Code Exchange (PKCE). Apesar de proteger o plug-in da API com um cliente confidencial, a Microsoft recomenda a utilização do PKCE, uma vez que adiciona uma camada adicional de segurança à sua aplicação com um overhead mínimo.

Armazenar as informações de OAuth no cofre permite-lhe mantê-la segura e não expô-la ao cliente. Uma vez que o plug-in se refere apenas à entrada, também pode atualizar o segredo do cliente sem ter de reimplementar o plug-in.

Durante o desenvolvimento, pode registar as suas informações OAuth de desenvolvimento no cofre manualmente ao aceder ao Portal do Programador do Teams e à secção Ferramentas que abre o registo de cliente OAuth ou ao utilizar o Toolkit de Agentes do Microsoft 365. Em produção, normalmente, um administrador regista as informações do OAuth e dá-lhe o ID da entrada do cofre a utilizar no plug-in da API.