Skip to main content

Microsoft Graph

Overview​

Microsoft Graph or "MS Graph" is a REST API that allows you to access data and insights from data stored within an Organization’s Microsoft 365 instance with access across domains such as Microsoft Core Services, Enterprise Mobility + Security Services, Windows Services, and Dynamics 365 Business Central services. The MS Graph Rest API also allows authorized users to connect and build new applications that deliver value to users within and outside the organization.

This MS Graph Adaptors allows OpenFn users to seamlessly authenticate and integrate with the Microsoft 265 platform to access data or perform specific workflow-driven operations on behalf of a tenant or a user within the Microsoft 365 instance. For example, the MSgraph Adaptor allows users to build OpenFn Workflows to extract documents stored in SharePoint, create or update files, and manage permissions. Another use case is building a workflow to connect with a Microsoft user's emails, calendar, and contacts to read and manage specific information directly.

Authentication and Authorization​

This adaptor requires OAuth authorization to connect with the MS Graph. This authorization can be achieved by a user or organization admin consenting to an OAuth client to access resources. Users can request authorization via the default OpenFn Microsoft OAuth client or choose to Add new (generic) OAuth client(s) for their account and projects. To authorize MS Graph for your OpenFn workflows read our documentation on using OAuth credentials.

info

Setting up your own generic OAuth client requires that you have an OAuth application set up. Please refer to Microsoft's documentation to configure an OAuth App via Microsoft entra app gallery.

Permissions (Scopes)​

Permissions and access in an OAuth instance are defined by scopes which are named differently by providers based on their functions within their platform. For MS Graph, there are two types of scopes: Delegated permission and Application Scopes. Delegated permissions are used by applications that sign in a user and act on behalf of the signed-in user. These permissions require the user to consent and are subject to the same data access restrictions as the user within the organization. Application scopes, on the other hand, are used by applications that run without a signed-in user. They require admin consent and provide access to all data for an organization, typically used by background services or daemons. OpenFn workflows and generic OAuth setup are compatible with both the delegated and application scopes. Below is a list of commonly used OAuth MS Scopes for your reference. The scopes required will depend on your use case, so please refer to the MS Graph documentation on OAuth Scopes), and/or consult with your system administrator.

  1. User scopes:
    • User.Read (Read user profile)
    • User.ReadBasic.All (Read basic user profile)
    • User.ReadWrite (Read and write user profile)
    • User.ManageIdentities.All (Manage user identities)
  2. Mail scopes:
    • Mail.Read (Read mail)
    • Mail.ReadBasic (Read basic mail)
    • Mail.ReadWrite (Read and write mail)
    • Mail.Send (Send mail)
  3. Calendar scopes:
    • Calendars.Read (Read calendars)
    • Calendars.ReadWrite (Read and write calendars)
  4. Contacts scopes:
    • Contacts.Read (Read contacts)
    • Contacts.ReadWrite (Read and write contacts)
  5. Files scopes:
    • Files.Read (Read files)
    • Files.ReadWrite (Read and write files)
    • Files.Read.All (Read all files)
    • Files.ReadWrite.All (Read and write all files)
  6. Groups scopes:
    • Groups.Read.All (Read all groups)
    • Groups.ReadWrite.All (Read and write all groups)
  7. Directory scopes:
    • Directory.Read.All (Read directory)
    • Directory.ReadWrite.All (Read and write directory)
  8. Application scopes:
    • Application.Read.All (Read applications)
    • Application.ReadWrite.All (Read and write applications)
  9. Other scopes:
    • offline_access (Access resources even when the user is offline)
    • openid (Authenticate with OpenID Connect)