Engine integrates with Microsoft Office 365 via Graph API. An Azure Active Directory admin must use Azure Portal to create an "App Registration" for Engine, and then details of this app registration will be configured in Engine.
The below Microsoft article and video can be referred to for additional context:
Article: Register an application with the Microsoft identity platform
Video: Getting Started with Microsoft Graph and Application Registration
An Azure user with admin permissions for Azure Active Directory will need to perform these actions:
Login to the Azure Portal and view the "App Registrations" page of the "Azure Active Directory" blade.
If an existing App has been registered for Engine for use with Azure Single-Sign-On (SAML2), then we can re-use this app - select it. If not, then click "New registration"
Type a descriptive name for the application, set the Supported account Type to "Accounts in this organizational directory only" and leave the Redirect URI blank. Click "Register".
While still in Azure Portal on the page for the above registered App:
In the menu on the left, select “API permissions” and click “Add a permission”. Then select “Microsoft Graph” as the API and select “Application Permissions” as the permission.
Typically, allow the below permissions (the list may vary depending on the desired functionality/restrictions on the web applications that will be using this Graph API integration):
If there is a requirement for the application to know which groups (e.g. AD Security group or mailing list) user's exist in, then add the below additional Application permissions:
If there is a requirement for the application to read/write user's Contacts, then add the below additional Application permissions:
After adding the required Application permissions, click "Grant admin consent for ACA Projects" on the "API Permissions" page of the registered App, then click Yes.
On the "Overview" page of the App, copy the below two values, which will be used in the next section to configure Engine to connect to this Registered App:
Application (client) ID
Directory (tenant) ID
On the "Certificates & secrets" page of the App, click "New client secret":
Add a meaningful description
Set Expiry to "Never", or as appropriate (ACA will no longer be allowed to use this credential after expiry)
Copy the Value of the secret, as it will be used in the next section to configure Engine.
Now you should have collected 3 text values that will be used in the next section:
Application (client) ID
Directory (tenant) ID
To restrict the Graph App's access to only the objects that exist in given AD groups, Application Access Policies **can be used.
Ensure those resources (users, rooms) exist in those AD groups
Use powershell to add the new policy, e.g:
# Restrict to a group of Rooms
New-ApplicationAccessPolicy -AppId <Graph App ID> -PolicyScopeGroupId <AD group that all bookable rooms exist in> -AccessRight RestrictAccess -Description "Restrict this app to Engine bookable rooms"
# Restrict to a group of Users
New-ApplicationAccessPolicy -AppId <Graph App ID> -PolicyScopeGroupId <AD group that all staff app users exist in> -AccessRight RestrictAccess -Description "Restrict this app to Engine app users"
Login to https://<your-engine-url>/backoffice/#/drivers/ and select an existing or create a new “Office365 Room Booking Panel Logic” driver and click edit (pen icon at top right). Note down the driver ID, which you will see in the browser URL bar and looks like “dep-xxxxxxxx” (you will need this later)
Enter the o365 values (client, secret, tenant) into the the placeholders which you should see. These values are on the portal.azure.com page where you created the Azure App Registration (above), then click Save.
Tip: Sensitive values (like office_secret) can be encrypted by inserting
$ in front of the setting name (e.g.
Test the configuration by navigating to a System which has a Device (module) instance of the above Driver (or create a Device instance).
Edit the System: Set the System’s Email to a real email address that exists on the o365 tenant
On the About page of the system, Select
Bookings 1 from "Execute command", then select the function
fetch_bookings and click “Send”.
An array of booking details (blue) should be returned (it might be empty
 if there are no bookings), or an error (red), if there is an issue grabbing the events from o365.
If blue, then the settings are correct and is currently being used for all Room Booking Panels. In the next step we'll configure Engine Staff API to use the same credentials.
Navigate to Domains (menu bar on left). Select the Domain that you’d like integrated with this Office 365 tenant and click it, then click edit (pen icon at top right).
In the "Config" box, ensure that the “o365_driver” value exactly matches the driver ID of the “Office365 Room Booking Panel Logic” driver which you gathered in step 1 (e.g. "dep-xxxxxxxx”"). Click Save. If there is none, then create one like this:
Test the Staff API integration by logging into an app that uses Staff API (e.g. Engine template Staff App) with a user who’s Calendar exists in the configured o365 tenant’s Exchange directory. You should be able to view/create events as this user.
If there are issues, note down the error information from requests like
/api/staff/bookings which will be shown in Chrome/Firefox Debug tools, on then Network tab.
Full backend error logs can also be viewed when ssh'ed into the VM:
docker logs --tail 99 -f engine