Integrar um plug-in de API a uma API protegida pelo OAuth
Outro padrão comum de proteção de APIs é usar o OAuth. O OAuth é um protocolo padrão do setor para autorização. O OAuth protege o acesso aos recursos usando tokens de acesso. Para obter um token de acesso, registre um aplicativo com o provedor de identidade e especifique seu tipo, como cliente público ou confidencial. Dependendo do tipo do seu aplicativo, talvez seja necessário definir configurações extras, como um segredo ou um certificado.
Quando os usuários abrem seu aplicativo, ele inicia o processo de obtenção de um token de acesso. As etapas exatas que o aplicativo segue dependem do tipo de aplicativo e do fluxo que ele usa. Quando os usuários concluem o fluxo de autorização, eles recebem um token de acesso que podem usar para chamar a API.
Ao integrar plug-ins de API com a API protegida pelo OAuth, você precisa da ID do cliente e do segredo do cliente do aplicativo que protege a API. Você também precisa dos pontos de extremidade de autorização, token e, opcionalmente, atualização do provedor de identidade. O Microsoft 365 Copilot usa essas informações para se autenticar com a API em nome do usuário atual e obter um token de acesso. Como as informações são confidenciais, armazene-as com segurança no local de armazenamento seguro no Microsoft 365, também conhecido como cofre. Em seguida, em seu aplicativo, você faz referência à ID da entrada do cofre. Em tempo de execução, o agente declarativo carrega seu plug-in (2) e recupera 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 ele usa para chamar a API (3c). O esquema a seguir ilustra esse processo.
Ao configurar as informações do OAuth para seu plug-in, você pode, opcionalmente, habilitar a PKCE (Chave de Prova para Troca de Código). Mesmo que você proteja seu plug-in de API com um cliente confidencial, a Microsoft recomenda usar o PKCE porque ele adiciona uma camada extra de segurança ao seu aplicativo com sobrecarga mínima.
Armazenar as informações OAuth no cofre permite mantê-las seguras e não expô-las ao cliente. Como o plug-in se refere apenas à entrada, você também pode atualizar o segredo do cliente sem precisar reimplantar o plug-in.
Durante o desenvolvimento, você mesmo pode registrar suas informações OAuth de desenvolvimento no cofre, manualmente acessando o Portal do Desenvolvedor do Teams e na seção Ferramentas abrindo o registro do cliente OAuth ou usando o Kit de Ferramentas de Agentes do Microsoft 365. Na produção, normalmente um administrador registra as informações do OAuth e fornece a ID da entrada do cofre a ser usada em seu plug-in de API.
