Office 365 integration

Integrations · Authentication · 1.2

The integration between Gfacility and Office 365 uses a 2-legged approach with an app registration in Microsoft Entra ID (formerly Azure Active Directory). Gfacility signs in with that app’s own identity, with no pop-up or consent per user. That is more stable and more secure.

How does it work?

The integration has four parts. You switch each part on separately in Gfacility, under Integrations & Login → Office 365. They all work through one app registration of your organisation.

User sync · every night

Puts your employees in Gfacility.

Department sync · with the user sync

Links every employee to their department.

Location sync · every night

Puts the meeting rooms in Gfacility, with building and floor.

Calendar sync · instant

Keeps bookings in Gfacility and Outlook the same.

User sync

Every night, Gfacility fetches your employees from Microsoft.

New employee? They are created.
Details changed? Name, email address and phone number are updated.
Left the company? Anyone no longer in Microsoft is set to inactive in Gfacility.

Which fields are copied?

Field in Microsoft	Field in Gfacility
Sign-in name (`userPrincipalName`)	Email address
First name (`givenName`)	First name
Last name (`surname`)	Last name
Mobile phone (`mobilePhone`)	Phone number
Department (`department`)	Primary organization, only when the department sync is on
Licence	Active or inactive

Note: the email address in Gfacility is the Microsoft sign-in name, not the Email field. Usually they are the same.

Not copied: job title, office location, business phone and profile photo. A new employee gets your workspace’s default organization and default location; you can change those in Gfacility afterwards.

Good to know:

Only employees with a Microsoft 365 licence are included. Rooms and shared mailboxes are not.
The user sync does not handle signing in. It only makes sure Gfacility knows your employees. For signing in, choose Sign in with Microsoft or SSO.

Department sync

The department sync is an extra option of the user sync. You switch it on under Integrations & Login → Office 365, directly below the user sync. The switch only appears once the user sync is on. No extra permission is needed: User.Read.All is enough.

On every user sync, Gfacility reads each user’s Department field from Microsoft Entra ID and links the user to the organization with that name, as their primary organization.

Situation	What Gfacility does
An organization with that name exists	The user is linked to that organization. Gfacility looks it up by name first, then by code, ignoring upper and lower case.
No organization exists yet	Gfacility creates a new organization at the top level, with the department name as both name and code, and the organization type Department (or the default type if that does not exist).
The department in Entra is empty	The user keeps their current organization. A new user gets the default organization.
A user's department changes	On the next sync they are linked to the new organization.

Good to know

Entra is leading. A primary organization you change by hand in Gfacility is set back to the Entra department on the next sync.
Existing organizations are never changed or deleted. If a department disappears from Entra, the organization stays in Gfacility.
Already have the organizations? Make sure the name or the code exactly matches the department in Entra before you switch the sync on. Otherwise Gfacility creates a second organization. Want a different name in Gfacility? Put the Entra department name in the code.
Newly created organizations sit at the top level. You may move them in the tree afterwards; the link keeps working because it goes through name or code.
Switching the department sync on while the user sync is on starts a sync straight away.

Location sync (Places)

Every night, Gfacility fetches the meeting rooms from Microsoft. For each room, the name, capacity, building and floor are updated. A building or floor that does not exist yet is created by Gfacility.

Which fields are copied?

Field in Microsoft	Field in Gfacility
Display name (`DisplayName`)	Name
Room email address	Email address (the link to the room calendar)
Capacity (`Capacity`)	Capacity
Building (`Building`)	Building (parent location)
Floor number (`Floor`)	Floor (name and code)
Room ID	Code

Not copied: the floor name (FloorLabel), address and city, equipment (display, audio, video), wheelchair access and tags.

Note: on every sync Gfacility also sets the room back to bookable and fills the description with a fixed text. If you change either in Gfacility, the next sync sets it back. To have a room left alone, switch off the external sync for that room in Gfacility.

How to set that up in Microsoft is explained in Room management in Microsoft.

Calendar sync

The calendar sync works in both directions:

From Gfacility to Outlook. Create a booking in Gfacility and it also appears in the organiser’s Outlook calendar, with the room included. Change or cancel it, and that happens in Outlook too.
From Outlook to Gfacility. Move, change or cancel that meeting in Outlook, and Gfacility updates the booking straight away.
Room calendars. Gfacility also reads the calendars of the meeting rooms. So the planning board and the room displays also show meetings that were only booked in Outlook.

What is synced?

Data	Direction
Title	Both ways
Start and end time, all day	Both ways
Description	Both ways (the Teams text is removed)
Attendees (colleagues and visitors)	Both ways
Rooms	Both ways. In Outlook they appear as attendee and under Location
Teams meeting and its link	Both ways
Cancelling	Both ways
Organiser	From Outlook to Gfacility
Catering and services	Stay in Gfacility. If the time or room changes in Outlook, they are flagged for review

From the room calendars, Gfacility reads per meeting: title, start and end time, organiser, number of attendees and whether the room accepted. A meeting marked private in Outlook shows in Gfacility as “Private”.

Good to know:

A meeting booked only in Outlook does not become a booking in Gfacility. The room does show as busy.
Every night, Gfacility checks for missed changes and picks them up.

How do you set it up?

It takes four steps:

Create an app registration in Microsoft.
Assign the permissions.
Choose how Gfacility may access calendars.
Enter the details in Gfacility.

Then switch on the parts you want to use in Gfacility.

1. Create an app registration in the Azure Portal

Create a separate app registration for Gfacility, apart from other applications. That way you keep control and security in your own hands.

Step	What to do
1	Sign in to the Azure Portal → App registrations.
2	Click + New registration and enter a name.
3	Choose the appropriate account type (e.g. Accounts in this organizational directory only).
4	Redirect URI can be left blank.
5	Click Register. Note the Application (client) ID and Directory (tenant) ID.
6	Go to Certificates & secrets.
7	Click + New client secret, add a description and an expiry date.
8	Click Add.

2. Assign API permissions

In the app registration, go to API permissions → + Add a permission → Microsoft Graph. Add per use case:

User integration

So Gfacility knows your employees. For signing in itself, see Sign in with Microsoft or SSO.

Application: User.Read.All
Delegated: User.Read

Places / Locations

Automatic sync of meeting rooms from Outlook.

Application: Place.Read.All

Calendars (Outlook events)

For bookings, scheduling, analytics and room displays. For this you choose one of two ways in step 3, so don't add anything here yet.

Shared calendars

Access to shared mailboxes.

Delegated: Calendars.Read.Shared
Delegated: Calendars.ReadWrite.Shared

Finally, click Grant admin consent for [Tenant]. Otherwise the permissions stay pending.

3. Choose how Gfacility may access calendars

Gfacility has to read and write events in the calendars of rooms and users. Choose one of these two ways:

Option A · All calendars

The simplest. Gfacility gets access to every calendar in your tenant.

Application: Calendars.ReadWrite

Add it in Entra ID next to the permissions from step 2 and grant admin consent. Calendars.Read is not needed: ReadWrite already includes reading.

Option B · Restricted via Exchange RBAC

Gfacility only gets access to the mailboxes you choose, for example the rooms and the employees who book.

Do not add a calendar permission in Entra ID. You arrange access in Exchange Online, see the steps below.

Option B step by step (Exchange Online PowerShell)

1. Connect and create the service principal. Use the Application ID and Object ID of the enterprise application, not the app registration:

Connect-ExchangeOnline

New-ServicePrincipal `
  -AppId "<Application ID>" `
  -ObjectId "<Enterprise App Object ID>" `
  -DisplayName "Gfacility Application RBAC"

2. Create a scope. Based on a domain or a mail-enabled group (regular security groups do not work):

# Option 1: by domain (new users fall inside the scope automatically)
New-ManagementScope `
  -Name "Gfacility-DomainScope" `
  -RecipientRestrictionFilter "PrimarySmtpAddress -like '*@contoso.com'"

# Option 2: by mail-enabled group (full control)
$Group = Get-DistributionGroup "Gfacility Scope"
New-ManagementScope `
  -Name "Gfacility-GroupScope" `
  -RecipientRestrictionFilter "MemberOfGroup -eq '$($Group.DistinguishedName)'"

3. Assign the role. Use Application Calendars.ReadWrite, because Gfacility writes bookings into calendars. With only Application Calendars.Read, bookings never reach Outlook.

New-ManagementRoleAssignment `
  -Name "Gfacility-Calendars-Scoped" `
  -Role "Application Calendars.ReadWrite" `
  -App "<Application ID>" `
  -CustomResourceScope "Gfacility-DomainScope"

Get-ManagementRoleAssignment -App "<Application ID>" | Format-List Name,Role,CustomResourceScope

4. Test with one room and one user:

Test-ServicePrincipalAuthorization -Identity "<Application ID>" -Resource "meetingroom1@contoso.com"
Test-ServicePrincipalAuthorization -Identity "<Application ID>" -Resource "employee@contoso.com"

Both must show InScope True, with Calendars.ReadWrite.

4. Enter the details in Gfacility

The Gfacility admin enters these details under Integrations & Login → Office 365 → Service account (app registration) and clicks Test connection. Or share them with us:

Application (client) ID
Directory (tenant) ID
Value of the client secret

Share these sensitive details through a secure method (a password-manager link), never loose in an email.

← Previous: Room management in Microsoft Next: Sign in with Microsoft→