Integrate an API plugin with an API secured with OAuth

Another common pattern of securing APIs is by using OAuth. OAuth is an industry-standard protocol for authorization. OAuth secures access to resources using access tokens. To get an access token, you register an application with the identity provider and specify its type, such as public- or confidential client. Depending on the type of your application, you might need to configure extra settings such as a secret or a certificate.

When users open your application, it starts the process of getting an access token. The exact steps the application follows depend on the type of application and the flow that it uses. When users complete the authorization flow, they get an access token which they can use to call the API.

When you integrate API plugins with API secured with OAuth, you need the client ID and client secret of the application that secures the API. You also need the identity provider's authorization-, token-, and optionally refresh endpoints. Microsoft 365 Copilot uses this information to authenticate with the API on behalf of the current user and get an access token. Because the information is confidential, you store it securely in the secure storage ___location in Microsoft 365, also known as vault. Then, in your app, you reference the ID of the vault entry. At runtime, the declarative agent loads your plugin (2) and retrieves the information from the designated entry (3a). The declarative agent follows the authorization code grant type, also known as auth code flow, to get an access token (3b) that it uses to call the API (3c). The following schema illustrates this process.

When configuring OAuth information for your plugin, you can optionally enable the Proof Key for Code Exchange (PKCE). Even though you secure your API plugin with a confidential client, Microsoft recommends using PKCE because it adds an extra layer of security to your application with minimal overhead.

Storing the OAuth information in the vault allows you to keep it secure and not expose it to the client. Because your plugin only refers to the entry, you can also update the client secret without having to redeploy your plugin.

During development, you can register your development OAuth information in the vault yourself, either manually by going to the Teams Developer Portal and from the Tools section opening OAuth client registration, or using Microsoft 365 Agents Toolkit. In production, typically an administrator registers the OAuth information and gives you the ID of the vault entry to use in your API plugin.