Restrict access to your API plugin

If you want to restrict access to your API to just the Microsoft Copilot experience in which your plugin is installed, use the plugin manifest auth field. Without a restriction in place, anyone can access your API by sending requests to your API endpoints.

Important

These features are in Private Preview.

API plugins support two types of API access authorization:

• Service-level, by using a bearer token.
• OAuth client credentials.

These two types of authorization happen directly between Microsoft Copilot and your API server and are transparent to the user of your plugin. This means that Microsoft Copilot is authorized to access your API, but your plugin can't authenticate individual users.

No restriction

You can choose not to restrict access to your API. This is the simplest way to get started building a plugin for Microsoft Copilot.

Even if you don't restrict access to your API, you still need to enter a value for the auth field in your plugin manifest file. The code snippet below shows the manifest for a real estate property search plugin that doesn't restrict requests to its API:

{
  "schema_version": "v1",
  "name_for_model": "contosorealestate",
  "description_for_model": "Plugin for finding properties for sale. Use it whenever a user asks about real estate properties for sale on the market. It can be used to search for properties in a particular city, and with a given number of bedrooms, bathrooms, and amenities.",
  "name_for_human": "Contoso Real Estate",
  "description_for_human": "Find up-to-date and detailed real estate properties for sale on the market",
  "api": {
    "type": "openapi",
    "url": "http://localhost:8080/openapi.yaml",
    "is_user_authenticated": false
  },
  "auth": {
    "type": "none"
  },
  "logo_url": "http://localhost:8080/logo.png",
  "contact_email": "contact@contoso.com",
  "legal_info_url": "https://contoso.com/legal/",
  "privacy_policy_url": "https://contoso.com/privacy-policy"
}

The auth field is required and the type field is set to none.

To view the source code for this sample plugin, see the contoso-real-estate folder in the mslearn-copilot-plugins repo.

Service-level authorization

Service-level authorization relies on a bearer token. A bearer token is a security token that you generate and provide to Microsoft Copilot when publishing your plugin to Partner Center. Microsoft Copilot then uses the bearer token to gain access to your API, by sending the token with every request that's made to your API.

To enable service-level authorization:

1. Generate a security token.
2. Check the security token in your API request handling code.
3. Change the auth field in your plugin manifest.
4. When publishing your plugin at Partner Center, provide the security token to Microsoft Copilot.

These steps are described in more detail below.

Generate a security token

To enable service-level authorization, you must generate a security token that's shared only between Microsoft Copilot and your API. This token is included in every request to your API from the Microsoft Copilot experience in which your plugin is installed.

This token can be any string, and must be kept private. We recommend using a cryptographically secure random string generator to generate the token.

For example, you can generate a token that's 32 characters long, by using the following JavaScript code:

// Create a byte array of 24 bytes.
const bytes = new Uint8Array(24);

// Fill the byte array with random values, by using the Web Crypto API.
crypto.getRandomValues(bytes);

// Convert the byte array to a base64 string, where each group of 3 bytes
// is represented by 4 characters, resulting in a 32-character string.
btoa(String.fromCharCode.apply(null, bytes));

Copy the generated token and save it for later use.

You can also generate such a token by using other programming languages, such as C#, Java, or Python.

Check the security token in your API request handling code

Check that the security token is present in every request made to your API. If the token is missing or invalid, return a 401 Unauthorized response.

Get started building an API plugin for Microsoft Copilot takes you through the process of creating a simple plugin from scratch, including an API, by using Node.js and the Express NPM library. In that guide, the following code is used to handle requests to the API endpoint:

app.get("/get-listings", (req, res) => {
  const city = req.query.city;
  const bedrooms = parseInt(req.query.bedrooms);
  const bathrooms = parseInt(req.query.bathrooms);
  const amenities = req.query.amenities;

  try {
    const listings = getListings(city, bedrooms, bathrooms, amenities);
    res.send(listings);
  } catch (e) {
    res.status(400).send({ error: e.message });
  }
});

To check the security token, add the following code to the function that handles requests to the /get-listings endpoint:

app.get("/get-listings", (req, res) => {
  // Check that the security token is present in the request.
  const auth = req.headers.authorization;
  if (auth !== "Bearer <your-security-token>") {
    res.status(401).send({ error: "Unauthorized" });
    return;
  }

  // The rest of the function is unchanged.
  const city = req.query.city;
  const bedrooms = parseInt(req.query.bedrooms);
  const bathrooms = parseInt(req.query.bathrooms);
  const amenities = req.query.amenities;

  try {
    const listings = getListings(city, bedrooms, bathrooms, amenities);
    res.send(listings);
  } catch (e) {
    res.status(400).send({ error: e.message });
  }
});

In the code snippet above, replace <your-security-token> with the security token that you generated earlier.

Set the authorization type in your plugin manifest

To let Microsoft Copilot know that your plugin requires API authorization, change the auth field in your plugin manifest to the following:

"auth": {
  "type": "service_http",
  "authorization_type": "bearer"
}

Provide the security token to Microsoft Copilot

When you publish your plugin to Partner Center, you're asked to select the authorization type that your plugin API uses, and to provide the security token that you generated earlier. Microsoft Copilot will use this token to access your API, by sending the token with every request made to your API.

To learn more about publishing your plugin to Partner Center, see Publish an API plugin.

OAuth client credentials authorization

OAuth client credentials authorization relies on OAuth 2.0, which is an open standard for access delegation. When using OAuth 2.0, both your API server and Microsoft Copilot rely on a trusted third-party, called an authorization server. The authorization server authorizes requests from the Microsoft Copilot experience in which your plugin is installed, and from your API server.

Unlike service-level authorization, where you generate your own security token, OAuth client credentials authorization uses two credentials: a client ID and a client secret. The client ID and the client secret are provided to you when you register your API with the authorization server. When publishing your plugin to Partner Center, you provide the client ID and the client secret to Microsoft Copilot.

The OAuth client credentials authorization flow works as follows:

1. Microsoft Copilot sends a request to the authorization server, by using a client ID and a client secret, to obtain an access token. The client ID and the client secret are provided to you when you initially register your API with the authorization server.

2. The authorization server validates the client ID and the client secret, and returns an access token to Microsoft Copilot.

3. Microsoft Copilot sends a request to your API, by using the access token.

4. Your API server validates the access token, either by sending a request to the authorization server (Figure 1 below) or by validating the access token locally (Figure 2).

5. Once the token is validated, your API server returns a response to Microsoft Copilot.

Figure 1 shows the flow when the API server validates the access token by calling the authorization server:

Figure 1. The steps involved in the OAuth Client Credentials flow.

Figure 2 shows the flow when the API server validates the access token locally:

Figure 2. The steps involved in the OAuth Client Credentials flow, with local token validation.

Implementing the flow for OAuth client credentials authorization isn't documented here. We recommend reading the documentation of the authorization server that you use, and using an existing OAuth 2.0 client library for your API server.

See also:

• Microsoft identity platform documentation.
• Microsoft identity platform and the OAuth 2.0 client credentials flow.
• Client Credentials Flow.
• OAuth 2.0 Client Credentials Grant.