Skip to main content

Microsoft graph

This plugin adds integration with the Microsoft Graph API. It will have a simple client which allows for authorization and doing requests.

This plugin also adds a Graph (Exchange) mail driver.

Installation​

To install this module​

composer require qore/microsoft-graph
php artisan qore:publish microsoft-graph -f

Upgrade Guide​

To update this plugin​

composer update qore/microsoft-graph
php artisan qore:publish microsoft-graph -fF

Upgrading to v2​

See the upgrade guide on github

Please be aware that v2 uses microsoft/microsoft-graph:^2.0, which brings major changes by itself.
Upgrading is not recommended when the application is doing graph API calls, this would take quite some time.

If the application does not make api calls and merely uses this package for mailing, you can safely upgrade the packaage.

composer require qore/microsoft-graph:^2 -W

Qore plugin changes​

  • The GraphClient is no longer present, instead use qore_graph()
    $client = (new GraphClient)->authenticate(..., ..., ...) would be the same as qore_graph()

Usage​

To use this plugin​

This plugin comes with settings you need to configure on the plugin page:

  • Tenant ID
  • Client ID
  • Client Secret

In order to get these credentials, you will have to set up an App registration in the Azure portal.

Creating an app in Azure portal​

To create an app, go to the Azure portal In the menu, click on Azure active directory (if you aren't already on that page).

Once there, go to App registrations. If you haven't already created an app, create a new one. After creating the app, make sure to copy the App Secret (you will only see it once).

Configuring your app in Azure portal​

The credentials you need, alongside your client secret, can be found here:

Next, we need to configure permissions. It will depend on your application, but let's assume we need to be able to send mails.

Go to API permissions in the menu and add the required permissions:

Using the API​

Version 1 documentation can be found here

This package comes with a qore_graph() helper function. This function uses the credentials set in the plugin settings and returns a scoped container binding of the GraphServiceClient.

Overriding the plugin credentials​

If for some reason you don't want to use the plugin settings, it is possible to provide a GraphCredentials instance to qore_graph() to override the plugin's settings.

Examples​

The new API is fairly straigtforward to use, see microsoftgraph/msgraph-sdk-php/Examples.md for examples.

Credential context​

Setting the credential context can be skipped and replaced by qore_graph():

$tokenRequestContext = new ClientCredentialContext(
    'tenantId',
    'clientId',
    'clientSecret'
);
$graphServiceClient = new GraphServiceClient($tokenRequestContext);

$user = $graphServiceClient->users()->byUserId(<mail_address>)->get()->wait();

becomes

$user = qore_graph()->users()->byUserId(<mail_address>)->get()->wait();

Permissions​

Overview​

Below is a short overview of features and their required permissions

  • Calendar Management:

    • Read and write access to calendars: Calendars.Read, Calendars.ReadWrite, Calendars.Read.Shared, Calendars.ReadWrite.Shared
    • Create, update, and delete events: Calendars.ReadWrite, Calendars.ReadWrite.Shared
    • Respond to events on behalf of users: Calendars.ReadWrite

  • Mail Management:

    • Read and write access to mail: Mail.Read, Mail.ReadWrite, Mail.Read.Shared, Mail.ReadWrite.Shared
    • Send mail on behalf of users: Mail.Send
    • Access mail folders: MailFolder.Read, MailFolder.ReadWrite, MailFolder.Read.Shared, MailFolder.ReadWrite.Shared

  • User Management:

    • Read and write access to user profiles: User.Read, User.ReadWrite, User.Read.All, User.ReadWrite.All
    • Create, update, and delete users: User.ReadWrite.All
    • Reset user passwords: Directory.AccessAsUser.All

  • Group Management:

    • Read and write access to groups: Group.Read, Group.ReadWrite, Group.Read.All, Group.ReadWrite.All
    • Create, update, and delete groups: Group.ReadWrite.All
    • Add and remove group members: GroupMember.ReadWrite.All

  • SharePoint and OneDrive:

    • Read and write access to SharePoint sites and files: Sites.Read.All, Sites.ReadWrite.All
    • Read and write access to OneDrive files: Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All

  • Directory Management:

    • Read and write access to directory objects: Directory.Read.All, Directory.ReadWrite.All
    • Read and write access to organization data: Organization.Read.All, Organization.ReadWrite.All

  • Security and Compliance:

    • Access security-related data: SecurityEvents.Read.All, SecurityEvents.ReadWrite.All
    • Access compliance-related data: Compliance.*