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 vendor:publish --tag=qore.graph.frontend

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​

To make use of the API, start by creating a new GraphClient:

use Qore\Graph\GraphClient;

$client = new GraphClient();

Now you can authenticate:

$client->authenticate($tenantId, $clientId, $clientSecret);
// Or:
$client->authenticate(
    tenantId: setting('qore/microsoft-graph', 'graph_tenant_id'),
    clientId: setting('qore/microsoft-graph', 'graph_client_id'),
    clientSecret: setting('qore/microsoft-graph', 'graph_client_secret'),
);

Below you can find a few examples that might help you get started. The full Microsoft Graph documentation can be found here.

Examples​

info

It might be easier to find examples using ChatGPT. For example:

Provide me PHP code to create an event in Microsoft Graph with the following conditions:
- We are authorized as a tenant and not as a user
- We are using a Guzzle client

Send e-mail​

Once authenticated, you can start doing requests. For example, let's send an e-mail:

caution

Please be aware of the json => [ ... ] array key that is prefixed before the body. If you don't do this, your request will fail.

$client = new GraphClient();
$client->authenticate($tenantId, $clientId, $clientSecret);

$sender = 'koen@qlic.nl';
$receiver = 'koen@qlic.nl';
$content = 'Hello <strong>World</strong>';

$client->post("v1.0/users/$sender/sendMail", [
    'json' => [
        'message' => [
            'subject' => 'Your test e-mail',
            'body' => [
                'contentType' => 'HTML',
                'content' => $content
            ],
            'toRecipients' => [
                [
                    'emailAddress' => [
                        'address' => $receiver
                    ]
                ]
            ]
        ],
        'saveToSentItems' => 'false'
    ]
]);

Above example requires the following permission: Graph -> Application permissions -> Mail -> Mail.Send

Get users​

$client = new GraphClient();
$client->authenticate(
    tenantId: setting('qore/microsoft-graph', 'graph_tenant_id'),
    clientId: setting('qore/microsoft-graph', 'graph_client_id'),
    clientSecret: setting('qore/microsoft-graph', 'graph_client_secret'),
);


$users = json_decode($client->get('v1.0/users')->getBody()->getContents(), true);

Above example requires the following permission: Graph -> Application permissions -> User -> Users.Read.All

Find user by e-mail​

$client = new GraphClient();
$client->authenticate(
    tenantId: setting('qore/microsoft-graph', 'graph_tenant_id'),
    clientId: setting('qore/microsoft-graph', 'graph_client_id'),
    clientSecret: setting('qore/microsoft-graph', 'graph_client_secret'),
);

$user = json_decode(
    $client->get("v1.0/users?\$filter=mail eq 'koen@qlic.nl'")->getBody()->getContents(),
    true
)['value'][0];

Above example requires the following permission: Graph -> Application permissions -> User -> Users.Read.All

Create outlook event​

  • $start: 2024-06-26T12:00:00
  • $end: 2024-06-26T14:00:00
$client = new GraphClient();
$client->authenticate(
    tenantId: setting('qore/microsoft-graph', 'graph_tenant_id'),
    clientId: setting('qore/microsoft-graph', 'graph_client_id'),
    clientSecret: setting('qore/microsoft-graph', 'graph_client_secret'),
);

$event = [
    'subject' => 'Test event!',
    'body' => [
        'content' => 'hello',
        'contentType' => 'HTML'
    ],
    'start' => [
        'dateTime' => $start,
        'timeZone' => "Europe/Amsterdam"
    ],
    'end' => [
        'dateTime' => $end,
        'timeZone' => "Europe/Amsterdam"
    ]
];

$response = $client->post('v1.0/users/koen@qlic.nl/events', ['json' => $event]);
$object = json_decode($response->getBody()->getContents(), true);

Above example requires the following permission: Graph -> Application permissions -> Calendars -> Calendars.ReadWrite

Find scheduled events for user​

$client = new GraphClient();
$client->authenticate(
    tenantId: setting('qore/microsoft-graph', 'graph_tenant_id'),
    clientId: setting('qore/microsoft-graph', 'graph_client_id'),
    clientSecret: setting('qore/microsoft-graph', 'graph_client_secret'),
);

$response = $client->post(
    "v1.0/users/koen@qlic.nl/calendar/getSchedule",
    [
        'json' => [
            'schedules' => ['koen@qlic.nl'],
            'startTime' => [
                'dateTime' => '2023-06-27T09:00:00',
                'timezone' => 'Europe/Amsterdam'
            ],
            'endTime' => [
                'dateTime' => '2023-06-29T18:00:00',
                'timezone' => 'Europe/Amsterdam'
            ],
            'availabilityViewInterval' => 60
        ]
    ]
);

$items = json_decode($response->getBody()->getContents(), true);

Above example requires the following permission: Graph -> Application permissions -> Calendars -> Calendars.Read

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.*

Upgrade Guide​

To upgrade this plugin​

composer update qore/microsoft-graph

If you need to upgrade migrations or Vue components:

php artisan vendor:publish --tag=qore.graph.frontend --force