Building Graph API Custom Plugins for Copilot for Security

Creating custom plugins in Microsoft Copilot for Security involves several steps:

• Define Plugin Descriptor:

  - The descriptor outlines the plugin's name, display name, description, and authorization type.

  - Required scopes: Graph API, Azure Management

• Define the Skill Group:

  - In the descriptor you must add a link to the OpenAPI  specification file.

  - This OpenAPI specification must include all the Skills with its corresponding endpoint and endpoint parameters. 

• Deploy and Test the Plugin:

  - Deploy the plugin to the Copilot for Security platform.

  - Test the plugin to ensure it works as expected and can interact with the required Graph API endpoints.

For more details about developing and deploying plugins you can go the official Microsoft documentation and community posts:

• https://learn.microsoft.com/en-us/copilot/security/custom-plugins
• https://techcommunity.microsoft.com/t5/microsoft-security-copilot-blog/how-to-build-a-copilot-for-security-api-plugin-part-1/ba-p/4107604
• https://rogierdijkman.medium.com/part-1-develop-a-basic-security-copilot-plugin-bb2d317f76ef

There are some things that need explanation before the development of the plugin.

Azure Access Model

In Azure, access management can be handled through delegated access and application access using Service Principal Names (SPNs), each serving distinct purposes. Delegated access allows an application to act on behalf of a user, inheriting the user's permissions and performing actions within the user's context. It's ideal for scenarios where user-specific data or actions are required, such as a web application retrieving a user's email from Microsoft Graph API.

On the other hand, application access using SPNs enables an application to access resources independently of any user, with permissions assigned directly to the application's service principal. It's suited for background services, automated processes, or any application that needs to perform tasks without user intervention, like a background service syncing data between systems.

Understanding these differences is crucial for implementing secure and efficient access management in Azure, ensuring that applications have the right level of access based on their operational context.

Scope Limitations

For this type of plugins we will use Delegated access model (AADDelegated authorization), so we first need to understand how it works and its current limitations.

In the descriptor of a Graph API plugin we need to specify the Authorization type as AADDelegated and the Entra ID Scope(s) that the plugin will request access for. We can limit the scope to specific permissions (i.e. User.Read.All, Group.Read.All or Policy.Read.All) or we can use the GraphAPI Default Scope. You can find additional information in the official learn page.

Sample Descriptor Authorization Section:

Authorization:
Type: AADDelegated
EntraScopes: https://graph.microsoft.com/.default

However, there are limitations in the Scopes you can use in the plugins. This limitation comes from how the Graph API access token is generated. Under the hood, Copilot for Security is using its own Entra ID Enterprise Application (Medeina Service, Client ID: bb3d68c2-d09e-4455-94a0-e323996dbaa3) to make the call to the GraphAPI on behalf of the user. This application lives in every tenant where Copilot for Security has been enabled and it is owned by Microsoft.

The permissions this application has currently authorized to use on behalf of the user are listed below:

So, these are the permissions we can use in our custom Graph API plugins. To get this list of permissions you can review the Scopes field in your MicrosoftGraphActivityLogs table in Sentinel/LogAnalytics using the following query:

MicrosoftGraphActivityLogs
| where UserAgent == "MicrosoftCopilotforSecurity.DirectorySkillDispatcher`1/0.1.0.0"

We could potentially try to use an Entra Scope outside this list, for example Mail.Read to be able to fetch email content (interesting for Phishing analysis) inside Copilot for Security. To do that we can change the EntraScopes property of our plugin to request this permission like this:

Authorization:
Type: AADDelegated
EntraScopes: https://graph.microsoft.com/Mail.Read

However, using this EntraScopes will make the plugin fail when triggering any skill. Looking at the API logs we can see this error message (it is not shown in the UI):

AADSTS65002: Consent between first party application 'bb3d68c2-d09e-4455-94a0-e323996dbaa3' and first party resource '00000003-0000-0000-c000-000000000000' must be configured via preauthorization - applications owned and operated by Microsoft must get approval from the API owner before requesting tokens for that API

This indicates that the Copilot Application is managed by Microsoft, and additional permissions need to be preauthorized by Microsoft. Unfortunately, this means that you cannot modify the permissions for the Copilot Application yourself and that Microsoft would need to add other permissions to Medeina (CfS) application to allow additional access from the plugins.

Define the Plugin Descriptor

So now that we understand the limitations of the platform and the available permissions, we can decide what kind of things our GraphAPI plugin is going to do.

The plugin descriptor should be simple. Below you can find an example:

The OpenAPI specification must be publicly accessible and can reference any GraphAPI endpoint that is allowed by the permissions specified above. You can see all the available endpoints here.

To test the endpoints you can use Microsoft Graph Explorer.

One tip to speed up the creation of these specs is to use Copilot for Security to create it. You can leverage the Fetch Public Web plugin to feed the official endpoint website and ask Copilot to create the OpenAPI spec for you.

Below you can find a simplified sample spec based on the Copilot answer above for Conditional Access Policies endpoint. This spec will allow us to retrieve the available conditional access policies and ask questions about them:

You can see the whole code of this example in our public GitHub repo.

Deploy and Test the Plugin

Once the OpenAPI spec is uploaded to a public site you can import the plugin into Copilot for Security. Learn more about the upload process for custom plugins.

After the plugin is uploaded you can start using it by using the right prompts. You can see some examples in the screenshots below:

Creating custom plugins for Microsoft Copilot for Security using the Microsoft Graph API can significantly enhance the platform's capabilities. However, it's essential to be aware of the scope limitations. By following the outlined steps and understanding the constraints, you can successfully develop and deploy Graph API plugins that meet your organization's security needs.