Breaking changes to the Microsoft Graph connectors API (beta)

Raju Nagalinga

We recognize that organizations have a wealth of data in other third-party services and applications. Boundary-less search is only as good as the sources it can access. Last year, we announced a public preview of Microsoft Graph connectors for customers and partners to index content into Microsoft Search. This enabled our customers to add content from several third-party services and applications into Microsoft Graph and make that content searchable in multiple Microsoft 365 search experiences.

Thanks to your feedback during our preview, we have added several enhancements, including granular permissions; cleaner type names; simpler acl and identity types; security trimming on groups (and group-like constructs) in external systems; fine tuning of connection schema, even after set up; support for new experiences such as intelligent discovery and eDiscovery; and the ability to supply the default settings (such as the Adaptive Card display templates) for these experiences, with many more to come.

We have also improved our API shape based on your feedback, to make it more useful and intuitive to developers. Implementing these improvements requires us to introduce some breaking changes.

New fine-grained permissions

During the initial preview, we introduced the permission ExternalItem.ReadWrite.All for applications to create and manage connections as well ingest content into connections that they created (or were explicitly authorized to). Now, we are introducing more fine-grained permissions for customers to control access to their connector content.

Permission Description
ExternalConnection.ReadWrite.OwnedBy This permission allows an application to create new connections or manage existing connections, as well as their settings for any connection that the application created, or was explicitly authorized to use.
ExternalItem.ReadWrite.OwnedBy With this permission, an application can read/write content (external items) into all connections that the application created or was explicitly authorized to use.
ExternalItem.ReadWrite.All Applications with this permission can read/write content (external items) into any connection within the Microsoft 365 tenant. Moreover, these applications will lose the ability to create and manage connections.

We recommend that you choose the permission that works best for your use case. Requesting the least or the right privilege for your application will help improve the chances that an application or global admin will grant admin consent to your app.

Introducing a new Microsoft Graph schema subnamespace

We introduced a dedicated schema subnamespace (microsoft.graph.externalConnectors) to provide clean and simple type names to all Microsoft Graph connector entities. If you have been using Microsoft Graph APIs with the connector entities in the global namespace (microsoft.graph), we recommend that you update your apps to either drop the OData type annotation for Microsoft Graph connector entities from their request payload and nested properties, or update it to the new namespace.

Code example for a drop the OData type annotation

Note that this change applies to all the connector entities. If you used the Microsoft Graph SDK to build your app, make sure to update it to use the latest SDK, and also update all code references to use the new subnamespace.

Updates to resource types and properties

Simplified acl resource type

We are simplifying the  acl resource type by deprecating the identitySource property and rolling the values into the type property. The supported values for the type of acl are `user`, `group`, `everyone`, `everyoneExceptGuests`, and with this change, it will also include `externalGroup`.

Code example using the new ACL resource type

Introducing the identity resource type

Along with simplifying the acl resource type, we are also simplifying the externalGroupMember API. We have introduced a new resource type microsoft.graph.externalConnector.identity with a simpler structure. Note that specifying the OData.type along with this API call isn’t required.

Example of code using the new identity resource type

authorizedApps in the externalConnection object renamed to authorizedAppIds

When creating a connection, developers can optionally supply an array of Azure Active Directory client IDs to authorize more than one application to manage the connection, and read and write its contents. No action is required if you aren’t using authorizedApps.

Code example to Rename to authorizedAppIds

Support during transition

To help ease the transition, we will offer backward compatibility until September 30, 2021. Please update your applications to ensure continued operation.

You will find the updated documentation at https://aka.ms/graphconnectorsapi. If you have questions you can reach out to us on Microsoft Q&A.

Please continue to share your feedback and help us improve the platform. Happy coding!

Feedback usabilla icon