Allow your AI Agent to call Microsoft Graph APIs securely with Microsoft Entra ID

Fabian Alves

In this blog post, we introduce a new plugin in the Chat Copilot sample app from the Semantic Kernel team. This plugin demonstrates how to allow an AI Agent to call APIs secured by Microsoft Entra ID using the On-Behalf-Of (OBO) flow.

We cover what this plugin is, why it was created it, and how you can build on this sample to create your own AI Agents capable of calling APIs secured by Microsoft Entra ID.

What is the Microsoft Graph OBO sample plugin?

This new plugin enables an app to act as an AI Agent that can call Microsoft Graph APIs adhering to Zero Trust principles. The sample plugin includes code, setup instructions, and deployment scripts.

However, it’s important to note the following considerations:

• The sample currently only implements read operations (GET requests) to Microsoft Graph APIs.
• The sample is not ready for production and should only be used for learning purposes.

Why was this plugin created?

This new plugin demonstrates the correct authorization flow to use in AI Agent scenarios by implementing the OBO Flow.

The OAuth 2.0 On-Behalf-Of (OBO) flow is an extension of the OAuth 2.0 authorization framework that enables a client application to request an access token using a previously obtained token. This is particularly useful in scenarios where a user’s authentication is required for one service, but that service needs to access another service, on behalf of the user, without requiring the user to reauthenticate.

The original Microsoft Graph version of the plugin only allowed a user to call specific “/me” endpoints and could only call APIs that require delegated permission, making it impossible to call APIs that require application permission.

Here are a few key points that show the benefits of using the On-Behalf-Of Flow:

• The API is called using the identity of the end user, which adheres to the “Use least privilege access” principle of Zero Trust.
• Users can consume any API given Admin Consent and permissions are configured.

Sample scenarios

User, groups, and apps

This scenario shows an instance of a Chat Copilot app configured to call Graph API V1 that reads users, groups, and app registration objects.

In the video below, we show a set of simple interactions asking the AI Agent to obtain and summarize information obtained from these APIs.

For this scenario to work the web API must have the following permissions configured with admin consent granted:

• Application.Read.All
• Directory.Read.All
• Group.Read.All
• User.Read.All

Also, the user accessing the Chat Copilot app must have the following roles assigned, directly, or through a group assignment:

• Directory Readers
• Application Administration
• Groups Administrator

How to run the sample plugin in the Chat Copilot app

To get started with the sample plugin, follow these steps:

1. Clone the Repository: Clone the Chat Copilot repository to your local machine.
2. Setup: Use the README.md files to set up the application. The setup instructions guide you through configuring the web app, web API, and enabling the MS Graph OBO plugin.

How to test a specific scenario

1. Admin consent is given for the set of APIs for the scenario to test: Review step 2 of the setup instructions in the MS Graph OBO plugin README.md file
2. Give permissions to the users: Create a group and assign the roles required to call the APIs. Add a user to that group. See “Users, groups, and apps” sample scenario above for details.
3. Log in to the app: Access the Copilot Chat application and log in.
4. Enable the MS Graph OBO plugin: Follow the test instructions in the README.md file.
5. Update the persona definition: Follow the test instructions in the README.md file.
6. Run sample queries: Start testing the AI Agent by using the few-shot learning approach. In few-shot learning, a set of training examples is provided as part of the prompt to give additional context to the model. In few-shot learning, a set of training examples is provided as part of the prompt to give additional context to the model.
   • In the first query, ask the AI Agent if it knows it has the specific ability provided in the plugin.
   • Ask it to run a Graph API query and include the URL, OData filters, and scopes needed in the prompt
   • Ask it to retrieve any information provided by the set of APIs prepared for the scenario in step 1. The AI Agent should be able to provide the results without the need for providing the URL, OData, or scopes for the API.

Three steps to create your own AI Agent

You now have all the information you need to get started with your own AI Agent communicating with Microsoft Graph in just three simple steps:

1. Create your own AI Agent by leveraging this sample plugin: Use the sample code as a template to create your own plugin and integrate it as a kernel function within your Copilot Chat WebApp.
2. Configure the set of APIs in Microsoft Entra ID: Follow the instructions in the README.md file.
3. Change the “persona” definition in the Chat Copilot app to let the AI Agent know that it has this new capability: Update the sample persona definition in the Chat Copilot app to include your own plugin capabilities. You can find the persona definition used in this sample in step 3 of Test Instructions in README.md file.

Let’s recap

This sample plugin demonstrates how to use the On-Behalf-Of flow in an AI Agent scenario using Microsoft Graph APIs that can be extended to any API secured in a Microsoft Entra ID tenant. It allows you to create “scenarios” by grouping a set of APIs, giving admin consent, assigning roles, and refining the prompt for the persona.

For detailed setup instructions and more information, refer to the main README.md file included in the repository.

To learn more or test out other features in the Microsoft Entra portfolio, visit our developer center. Make sure you subscribe to the Identity blog for more insights and to keep up with the latest on all things Identity. And, follow us on YouTube for video overviews, tutorials, and deep dives.

Happy coding!

Fabian Alves

Follow