Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update api-plugin-authentication.md #23

Closed
wants to merge 1 commit into from
Closed

Update api-plugin-authentication.md #23

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
179 changes: 119 additions & 60 deletions docs/api-plugin-authentication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,31 +1,27 @@
---
title: Authentication schemes for API plugins for Microsoft 365 Copilot
description: Learn about the supported authentication schemes for API plugins in Microsoft 365 Copilot
title: Configure Authentication for Custom Actions in M365 Copilot Agents
description: Learn about how you can setup authentication for custom actions in M365 Copilot Agents.
author: jasonjoh
ms.author: jasonjoh
ms.date: 10/09/2024
ms.topic: conceptual
---

# Authentication schemes for API plugins for Microsoft 365 Copilot
# Configure Authentication for Custom Actions in M365 Copilot Agents

[!INCLUDE [api-plugins-declarative-agents-only](includes/api-plugins-declarative-agents-only.md)]

API plugins for Microsoft 365 Copilot support three authentication schemes to connect to their backend APIs.
You can configure authentication for Custom Actions in M365 Copilot Agents using any of the four supported authentication schemes to seamlessly connect to their backend APIs.

- OAuth 2.0 authorization code flow
- API key via [bearer authentication](https://swagger.io/docs/specification/authentication/bearer-authentication/)
- Entra ID SSO authentication
- API key authentication
- No authentication (anonymous)

## OAuth 2.0 authorization code flow

This authentication scheme allows a plugin to access an API using a bearer token acquired by an OAuth 2.0 authorization code flow. This scheme can be represented in an OpenAPI document in the `securitySchemes` property. See [OAuth 2.0](https://swagger.io/docs/specification/authentication/oauth2/) for details.
This authentication scheme allows a plugin to access an API using a bearer token obtained through the OAuth 2.0 authorization code flow. You can define this scheme in the `securitySchemes` property of an OpenAPI document . Refer to [OAuth 2.0](https://swagger.io/docs/specification/authentication/oauth2/) for more details.

> [!IMPORTANT]
> API plugin support for OAuth 2.0 has the following limitations.
>
> - API plugins only support the authorization code flow for OAuth 2.0.
> - OAuth 2.0 servers that return `307 Temporary Redirect` HTTP status codes from their token endpoint are not supported.
> Custom Actions as of today only support authorization code flow for OAuth 2.0.

```yml
securitySchemes:
Expand All @@ -40,92 +36,155 @@ securitySchemes:
scope: description
```

To use this authentication scheme in a plugin, you must register an OAuth client in the [Teams Developer portal](https://dev.teams.microsoft.com/).
You can provision OAuth authorization either through Teams Toolkit in VS Code or manually registering the OAuth client in the Teams apps developer portal.

> [!TIP]
> If your OpenAPI document includes the `securitySchemes` property, Teams Toolkit can register your OAuth client and update your manifest for you when you [generate a plugin from an existing API](build-api-plugins-existing-api.md).
>
> If your OAuth provider supports Proof Key for Code Exchange (PKCE), uncomment the following line in **teamsapp.yml** in your API plugin project.
>
> ```yml
> # isPKCEEnabled: true
> ```
### Provision OAuth for actions using Teams Toolkit in VS Code
Teams Toolkit can register your OAuth client and update your app package for you when you [create a Copilot Agent with custom action from an existing OpenAPI document](build-api-plugins-existing-api.md).

### Register an OAuth client
### Manually register OAuth client and update the app package

> [!NOTE]
> If your OAuth provider requires specifying allowed redirect URIs when registering your app, include `https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect` in the allowed redirect URIs.
> If your OAuth provider requires you to specify allowed redirect URIs during app registration, make sure to include `https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect` in the list.

#### Register OAuth client in Teams apps developer portal

1. Open your browser and browse to the [Teams apps developer portal](https://dev.teams.microsoft.com/tools). Select **Tools** in the left-hand navigation.
1. Open [Teams apps developer portal](https://dev.teams.microsoft.com/tools). Navigate to **Tools** -> **OAuth client registration**.

1. Select **OAuth client registration**. If you have no existing registrations, select **Register client**; if you have existing registrations, select **New OAuth client registration**.
1. If you have no existing registrations, select **Register client**; if you have existing registrations, select **New OAuth client registration**.

1. Fill in the following fields.

- **Registration name**: A friendly name for your registration
- **Base URL**: Your API's base URL
- **Client ID**: The client ID or application ID issued by your OAuth 2.0 server
- **Client secret**: Your client secret issued by your OAuth 2.0 server
- **Authorization endpoint**: The URL from your OAuth 2.0 server that apps use to [request an authorization code](/entra/identity-platform/v2-oauth2-auth-code-flow#request-an-authorization-code)
- **Token endpoint**: The URL from your OAuth 2.0 server that apps use to [redeem a code for an access token](/entra/identity-platform/v2-oauth2-auth-code-flow#redeem-a-code-for-an-access-token)
- **Refresh endpoint**: The URL from your OAuth 2.0 server that apps use to [refresh the access token](/entra/identity-platform/v2-oauth2-auth-code-flow#refresh-the-access-token)
- **Scope**: The permission scope defined by your API that grants access.
- **Enable Proof Key for Code Exchange (PKCE)**: Enable this setting if your OAuth provider supports PKCE.
- **Registration name**: A friendly name for your registration.
- **Base URL**: Your API's base URL, also referred to as server URL in your OpenAPI document.
- **Client ID**: The client ID or application ID issued by your OAuth 2.0 provider.
- **Client secret**: Your client secret issued by your OAuth 2.0 provider.
- **Authorization endpoint**: The URL from your OAuth 2.0 provider that apps use to [request an authorization code](/entra/identity-platform/v2-oauth2-auth-code-flow#request-an-authorization-code)
- **Token endpoint**: The URL from your OAuth 2.0 provider that apps use to [redeem a code for an access token](/entra/identity-platform/v2-oauth2-auth-code-flow#redeem-a-code-for-an-access-token)
- **Refresh endpoint**: The URL from your OAuth 2.0 provider that apps use to [refresh the access token](/entra/identity-platform/v2-oauth2-auth-code-flow#refresh-the-access-token)
- **Scope**: The permission scope defined by your API that allows access.
- **Enable Proof Key for Code Exchange (PKCE)**: Enable this if your OAuth provider supports PKCE.

1. Select **Save**.
1. Click **Save**.

Completing the registration generates an OAuth client registration ID.
1. Completing the registration generates an OAuth client registration ID.

### Adding OAuth 2.0 authentication to the plugin manifest
#### Update action manifest to add OAuth 2.0 authentication

To use OAuth 2.0 authentication in your plugin, set the `type` property of the [runtime authentication object](api-plugin-manifest.md#runtime-authentication-object) to `OAuthPluginVault`, and set the `reference_id` to the client registration ID from the Teams Developer Portal.
To use OAuth 2.0 authentication for your custom action, set the `type` property of the [runtime authentication object](api-plugin-manifest.md#runtime-authentication-object) to `OAuthPluginVault`, and set the `reference_id` to the client registration ID from the Teams Developer Portal.

```json
"auth": {
"type": "OAuthPluginVault",
"reference_id": "client registration ID"
"reference_id": "auth registration ID"
},
```

## API key via bearer auth
### Enable PKCE (Proof Key for Code Exchange) for OAuth

1. Open [Teams apps developer portal](https://dev.teams.microsoft.com/tools), navigate to OAuth client registration and open your client registration. If you don't have an existing registration, refer to the section above to manually register your OAuth client.

2. Toggle on **Enable Proof Key for Code Exchange (PKCE)** and click **Save**.

![alt text](image-13.png)

This authentication scheme allows a plugin to access an API using a long-lived API key or token. This token is sent in API requests in the `Authorization` header as a bearer token. This scheme can be represented in an OpenAPI document in the `securitySchemes` property. See [Bearer Authentication](https://swagger.io/docs/specification/authentication/bearer-authentication/) for details.
3. Uncomment the following line of code in teamsapp.yml in your Copilot Agent project.

```yml
securitySchemes:
BearerAuth:
type: http
scheme: bearer
# isPKCEEnabled: true
```

## Entra ID SSO authentication

Entra ID SSO Authentication allows seamless single sign-on (SSO) integration, enabling users to authenticate with their existing Entra ID credentials. This simplifies access management and ensures secure connections to APIs without requiring additional credentials. Follow the four steps below:

1. Register an SSO client in Teams apps developer portal
1. Update the Microsoft Entra app registration
1. Update the action manifest file with Mircorosft Entra SSO registration ID
1. Update your app service to allow new token audience

### Register an SSO client in Teams apps developer portal

1. Open [Teams apps developer portal](https://dev.teams.microsoft.com/tools). Navigate to **Tools** -> **Microsoft Entra SSO client ID registration** -> **Register client**; if you have existing registrations, select **New client registration**.

1. Fill in the following fields.

- **Registration name**: A friendly name for your registration.
- **Base URL**: Your API's base URL, also referred to as server URL in your OpenAPI document.
- **Restrice usage by org**: Select which M365 organization endpoints will use your app to access API endpoints.
- **Restrice usage by app**: Select which client is this registration for. For testing purposes, you can select **Any Teams app** but before you publish the app, ensure you bind the app with the right client.
- **Client ID**: The client ID of the app registered in Microsoft Entra.

1. Click **Save**.

1. You'll get a **Mircorosft Entra SSO registration ID** and an **Application ID URI**.

### Update the Microsoft Entra app registration

1. Update the Mirosoft Entra app registration that secure your API with the new application ID URI [Microsoft Azure Entra portal](https://ms.portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/Overview). If you have an existing Application ID URI mapped to the Entra app registration, you can use the Manifest Editor to add an additional URI in the **IdentifierURIs** section.

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

> [!NOTE]
> API plugins don't support the OpenAPI [API key security scheme](https://swagger.io/docs/specification/authentication/api-keys/). APIs that use API keys for authentication must use the bearer authentication security scheme and accept the API key in the `Authorization` header. You can't define a custom header or send the key as a query parameter or cookie.
> Adding multiple URIs is not supported through Entra GUI. You hence, should use the manifest editor.
> Entra GUI will only display the first URI in the list. If you add the new URI as the first one in the list, it will be displayed in the Entra GUI.
> This will not impact your existing URIs & scope even if they show differently in the Entra GUI.

To use this authentication scheme in a plugin, you must register an API key in the [Teams Developer portal](https://dev.teams.microsoft.com/).
2. Open **Authentication** section and add the URI https://teams.microsoft.com/api/platform/v1.0/oAuthConsentRedirect.

> [!TIP]
> If your OpenAPI document includes the `securitySchemes` property, Teams Toolkit can register your API key and update your manifest for you when you [generate a plugin from an existing API](build-api-plugins-existing-api.md).
1. Open **Expose an API** section, click on **Add a client application** and add the client ID **ab3be6b7-f5df-413d-ac2d-abf1e3fd9c0b**. This is the client ID of Microsoft's enterprise token store.

### Register an API key
### Update the action manifest file with Mircorosft Entra SSO registration ID

1. Open your browser and browse to the [Teams apps developer portal](https://dev.teams.microsoft.com/tools). Select **Tools** in the left-hand navigation.
Set the `type` property of the [runtime authentication object](api-plugin-manifest.md#runtime-authentication-object) to `OAuthPluginVault`, and set the `reference_id` to the Microsoft Entra SSO registration ID from the Teams apps developer portal.

1. Select **API key registration**. If you have no existing registrations, select **Register client**; if you have existing registrations, select **New API key**.
```json
"auth": {
"type": "OAuthPluginVault",
"reference_id": "SSO registration ID"
},
```

1. Select **Add secret** and enter the API key.
### Update your app service to allow new token audience

1. Fill in the following fields.
1. Update your app service to allow the new identifier URI as the token audience.
2. If you validate the Client application make sure that the Microsoft's enterprise token store (**ab3be6b7-f5df-413d-ac2d-abf1e3fd9c0b**) is added as a valid client application.

- **API key name**: A friendly name for your registration
- **Base URL**: Your API's base URL
## API key authentication

Some APIs use API keys for authorization, where an API key is a shared secret that the client includes in API requests to authenticate and gain access. The key can be sent in three in ways:

1. Bearer token
1. Custom headers
3. Query parameters

### Manually register API key

You can use a long-lived bearer shared secret to access an API. This token is included in API requests in the `Authorization` header. You can define this scheme in the `securitySchemes` property of an OpenAPI document. See [Bearer Authentication](https://swagger.io/docs/specification/authentication/bearer-authentication/) for more details. Follow the steps below to register an API key and update the action manifest file.

1. Define your API key authentication settings in the OpenAPI document as per swagger document for [Bearer Authentication](https://swagger.io/docs/specification/authentication/bearer-authentication/) or [custom header or query paramater](https://swagger.io/docs/specification/v3_0/authentication/api-keys/).

1. Open [Teams apps developer portal](https://dev.teams.microsoft.com/tools). Navigate to **Tools** -> **API key registration** -> **Create an API key**; if you have existing registrations, select **New API key**.

1. Click **Add secret** and enter the API key.

1. Fill in the following fields.

1. Select **Save**.
- **API key name**: A friendly name for your registration.
- **Base URL**: Your API's base URL or server URL.
- **Target tenant**: Limit API access to home tenant or not.
- **Target Teams App**: Select which client is this registration for. For testing purposes, you can select **Any Teams app** but before you publish the app, ensure you bind the app with the right client.

Completing the registration generates an app key registration ID.
1. Click **Save**.

### Adding API key authentication to the plugin manifest
1. Completing the registration generates an **app key registration ID**.

To use API key authentication in your plugin, set the `type` property of the [runtime authentication object](api-plugin-manifest.md#runtime-authentication-object) to `ApiKeyPluginVault`, and set the `reference_id` to the app key registration ID from the Teams Developer Portal.
### Update action manifest to add API key authentication
1. In your action manifest file, set the `type` property of the [runtime authentication object](api-plugin-manifest.md#runtime-authentication-object) to `ApiKeyPluginVault`, and set the `reference_id` to the app key registration ID from the Teams apps developer portal.

```json
"auth": {
Expand Down
Loading