This document describes how to configure Google Workspace to use with Spacewell Reservation Sync Interface.
1. Scope
This configuration guide is applicable for the Google Workplace setup needed for the integration with Workplace Management.
2. Who is this document for?
Google Workspace Administrator who will prepare the Google Suite environment for sync with Reservation Sync Interface.
Information Security Official who will review the administrative actions performed on the customer’s side as part of the above role.
3. Pre-requisites - Google Administration
The following steps implement and/or validate few settings in Google Workspace that are required by the Reservation Sync Interface to establish connectivity with Spacewell Workplace
The following steps require administrative access to Google Workspace, ensure your Google account has the necessary access rights.
3.1 Creation of Service account
3.1.1 Create a Project
The Google Cloud console can be accessed via: https://console.cloud.google.com/
In the menu, select IAM & Admin → Create a Project.
Fill in a Project name and select a Location. Then press Create.
3.1.2 Enable API Access
In the menu, select API’s & Services → Enabled APIs & Services.
Click on + Enable APIs and Services.
Search for ‘calendar’ in the search bar and select Google Calendar API.
Press on Enable. You should be returned to the Google Calendar API overview screen.
Search for ‘admin’ in the search bar and select Admin SDK API.
Press on Enable. You should be returned to the Admin SDK API overview screen.
3.1.3 Service account creation
In the menu, select Credentials followed by + Create Credentials → Service account.
Fill in the Service account details and press Create and Continue.
The Service account name will be visible in the Google reservation ‘Created by’ field. Enter the service account name ‘Workplace Management’.
Grant access for the created service account. Select the role Owner and press on Continue.
Click Done to finish creating service account.
3.1.4 Delegating domain-wide authority to the service account
The Google Admin console can be accessed via: https://admin.google.com/
Select in the main menu Security → Access and data control → API Controls.
In the Domain-wide delegation pane, select Manage Domain-Wide Delegation.
Click Add new.
In the Client ID field, enter the service account's Client ID. (You can find your service account's client ID in the Service accounts page.)
In the OAuth scopes (comma-delimited) field, enter the list of scopes that your application should be granted access to. In our case, application needs domain-wide full access to the Google Directory API and the Google Calendar API.
https://www.googleapis.com/auth/admin.directory.resource.calendar
https://www.googleapis.com/auth/calendar
Copy the above scopes and paste in the required field(s).
Click Authorise.
Please use below screenshot for reference.
Note: Only above two scopes are needed to perform calendar & resource operations. However in order to manage users or domains, the below scopes maybe needed. So add the below only if absolutely required!
https://www.googleapis.com/auth/admin.directory.domain
https://www.googleapis.com/auth/admin.directory.user
Your application now has the authority to make API calls as users in your Workspace domain (to "impersonate" users). When you prepare to make these delegated API calls, you will explicitly specify the user to impersonate. The user to impersonate can be an admin or non-admin with a valid email ID in the current domain (example: random-user@spacewell-test.com).
It is recommended to use Non-Admin account as impersonating user to avoid unauthorized access to irrelevant sections within Google API Management!
It usually takes a few minutes for impersonation access to be granted after the client ID was added, but in some cases, it might take up to 24 hours to propagate to all users of your Google Account.
3.2 Building and Resources
Select in the main menu Directory → Buildings and resources → Manage resources
3.2.1 Creating Buildings
Select Buildings from the Resource Management dropdown.
Click Add building and then fill Name and Floors, then click on Add Building button.
3.2.2 Creating Resources
Select Resources from the Resource Management dropdown.
Click Add new resource (via the yellow + circle).
Enter the Category, Building, Category, Floor and Resource name.
Click Add Resource to confirm the added resource.
Add all applicable resources via the above steps.
4. Application access
4.1 Delegate user
Google Workspace doesn’t allow modification of resources' calendar without a valid delegate user. The delegate user is actually a user account with valid email under the same organization in Google Workspace. Any modification to resources' calendars like create, modify or delete reservation shall be done on behalf of this delegate user.
4.1.1 Create a new delegate user
Open the Google Admin console (https://admin.google.com/)
In the menu, select Directory → Users.
Click Add new user to create a new delegate user.
Enter the First name, Surname, Primary email and the Organizational unit. Automatically generate or enter a Password.
Click Add New User to confirm (blue button in the bottom right corner).
Copy the Primary email from this screen. This email address is needed for configuration in a later chapter.
4.1.2 Use an existing delegate user
Open the Google Cloud console (https://console.cloud.google.com/)
In the menu, select Directory → Users.
Open the desired delegate user and copy the email address from this screen. This email address is needed for configuration in a later chapter.
4.2 Set calendar sharing options
Admins can control how much calendar information is shared with users external to the organization.
Select in the main menu Apps → Google Workspace → Calendar.
Select General Settings.
Select External Sharing options for Secondary Calendars, then select Share all information, and outsiders can change calendars (modify and create events in the room calendar).
Then click Save.
Changes in the external sharing can take up to 24 hours to take affect.
4.3 Share resources to allow delegate user to manage events
4.3.1 Add resources to ‘My calendars' section in Google calendar
Login with the admin user in Google Calendar. The Google Calendar can be accessed via: https://calendar.google.com/
Go to Other calendars → + → Browse resources.
The buildings and resources created in chapter 3.2 Buildings and resources are shown.
Select all applicable resources (per building) which need to be available to be reserved.
Selecting all applicable resources will result in the resources being added to the 'My calendars' section. Via here you can allow the service account to manage events for every resource.
4.3.2 Add delegate to resource
Go to the Google Calendar of the admin user and hover over the resource (in the ‘My calendars’ section) → click on the 3 dots → Settings and sharing.
Scroll down and go to Share with specific people or groups and click + Add people and groups.
Select the delegate user (chapter 4.1 Delegate user) from the drop-down list and select the permission ‘Make changes to events’ and click Send. The permission of the delegate user is crucial for the impersonation account to manage events on a resources calendar.
Please repeat the steps above for all the available/needed resources by sharing the calendar to all Delegate users (impersonate) manually.
If a delegate user is not correctly configured for any resource, the reservation sync for that resource may fail partially or entirely. Therefore, it is essential to ensure that a valid delegate user with appropriate permissions is set up for all necessary resources.
4.4 Generate keys
Open the Google Cloud console (https://console.cloud.google.com/)
In the menu, select IAM & Admin→ Service accounts.
Select the service account created in 3.1.3 Service account creation
Go to Keys → Add key → Create new key.
Select key type JSON and click Create.
The JSON file is downloaded to the local machine and the key is displayed in the service account key overview:
Please save the downloaded JSON file that contains the key at a safe/secure location.
Losing the key may result in repetition of tasks done in Section 4.3 and Section 4.4
4.5 Share credentials
The above generated key serves as the only copy of the private key. You are responsible for storing it securely. If you lose this key pair, you will need to generate a new one.
Upon completing the above steps, the credentials generated for the project must now be shared securely with Spacewell Integration team which will then be configured in the Reservation Sync interface for automated API access.
The following details must be shared in the given format
Attribute | Value |
|---|---|
client_email |
|
Secret Expiry Date |
|
Email Domains |
|
private_key | |
impersonated user email |
impersonated user email - a super user which belongs to your Workspace account
client_email and private_key from section 4.1 above
It is recommended that the key is shared securely. A single-use expirable link can be a good way to share this information.
A secure link can be created via for example: https://onetimesecret.com/?locale=en
Enter the Client Secret in the Secret content goes here text box
Enter a passphrase
Enter a lifetime of the secret link
Click on Create a secret link
Share the link with Spacewell Integration Team
Share the passphrase Spacewell Integration Team
Share the secret link, the passphrase and the other information mentioned above and mail it to integration@spacewell.com. Use your organization name and the Application ID in the email subject.
If we find that the link has been already used, we will ask you to delete the secret generated in chapter 4.2 and repeat the process of generating a new client secret.
This is just a recommended approach to securely share credentials. You can alternately follow any other secure information transmission channel of your choice and policy.