title | description |
---|---|
Configure Staff API |
How to Configure the Staff API on PlaceOS |
The Staff API gives PlaceOS the ability to interact with Calendar and User Resources.
To integrate room booking into your existing calendar environment you must configure Staff API.
Once you have configured Staff API, PlaceOS can:
- Create
- Edit
- Update
- Delete Calendar events in Microsoft 365 or Google Workspace.
To show room status on floor maps, the PlaceOS Calendar driver must also be configured.
To enable room bookings, the PlaceOS Bookings driver must be also configured.
- Access on Microsoft Azure or Google Cloud Console & Workspace to create apps and API permissions
- Administrator access to your PlaceOS Backoffice
To enable Staff API you must complete the necessary configuration in your cloud provider.
Instructions for Microsoft 365 and Google Workspace are below.
To use Staff API with 365 you will need to create an Application in App Registration.
You may have already completed this step if you have configured PlaceOS for Microsoft 365 User Authentication.
If you have already created an app, you ca skip to Grant Graph API Permissions.
If not, you will need to create a new App Registration on Azure.
- Navigate to the Azure Portal
- Log in and select the correct Subscription for your application
- Navigate to App Registrations
- Select New Registration
- Enter the required information
- Register the app
You will now need to grant Graph API Permissions on your App.
-
Select the app you would like to give permissions
-
Click API Permissions
-
Click Add Permission
-
Click Microsoft Graph
-
Select Delegated permissions
-
Grant API Access to the following resources (or whichever resources are approved by the Azure administrator):
openid
offline_access
Calendars.ReadWrite
Calendars.ReadWrite.Shared
Group.Read.All
User.Read
User.Read.All
Contacts.Read
Place.Read.All
-
Click Add Permissions
-
Grant Admin Consent for all the new permissions
You will now need to create the secret to allow PlaceOS Staff API to Authenticate.
-
Navigate to Certificates & Secrets
-
Select New client secret
-
Give your secret a description e.g.
PlaceOS Prod App Secret
and click Add -
Copy and Save the Secret Value (you will need this in the next step)
-
Return to the App Overview
-
Copy and Save the
Client ID
andTenant ID
(you will need these in the next step)
To use Google APIs you will need a server to server OAuth2 application configured.
This involves creating a service account that PlaceOS will use for authentication.
The service account can “act as” staff in the organization.
The service account can perform actions on behalf of a user, such as booking meeting rooms.
For further information see Creating and Managing Service Accounts.
Configure Google Cloud API Project
- Go to Google Cloud Console
- Configure an existing API Project or Create a New API Project
- Open your API Project and select
APIs & Services
followed byDashboard
- Select
Enable APIs and Services
- Search for and enable the following SDK:
- Admin SDK (for staff directory)
- Google Calendar API
- Google Drive API (for attachments)
- For limiting access to a subset of the organization, you may also want to enable:
- Marketplace SDK (not Marketplace API)
- Drive API
-
Under APIs & Services, navigate to Credentials
-
Click on the Create Credentials and select Service Account Key
-
Create a new Service Account
-
You can ignore the next steps in the wizard, click
Done
to return to the list of service accounts -
Click the service account you created and select the
Keys
tab to create an access key -
This will save a JSON File to your computer, you will need this information to configure the service.
-
Once the key has saved, return to the
Details
tab and enable Domain Wide Delegation -
Click Save
{% hint style="success" %} If you want to configure this application for use in a subset of the organization, ignore this step.
Continue with the steps to “Create a marketplace application” {% endhint %}
-
Open the JSON File that we saved in the previous step
-
Copy the
client_id
-
Navigate to Google Workspace Admin
-
Select
Security
-
Scroll down to
API Controls
-
Select
Manage Domain Wide Delegation
-
Click
Add new
and enter theclient_id
you extracted earlier -
Add the following API Scopes:
-
Click
Authorize
-
Ensure you enable API Access by going to
Security -> API Controls
-
Select
Trust internal, domain owned apps
{% hint style="warning" %}
The scope https://www.googleapis.com/auth/drive.file
allows the application to add attachments to calendar events, such as QR codes.
It does not allow for reading or modifying any files not created by the application. {% endhint %}
{% hint style="success" %} This step applies to organizations where a specific region or department (OU) will be using the application.
This step is not applicable to most organizations. {% endhint %}
-
On Google Cloud Console navigate to the API Services Dashboard
-
Select the
Configuration
tab -
Fill in the app name and description, un-check
Enable individual install
-
Upload icons as required
-
A Terms of Service URL is also required, you can set this to your companies homepage
-
Enter the following scope URL:
https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/admin.directory.user.readonly
https://www.googleapis.com/auth/drive.file
-
Fill in the details and icons for the Drive Application
-
Once completed, return to the marketplace application form
-
Ensure you set visibility to
My Domain
-
Click
Save Changes
Deploy the marketplace application to the organizational unit that will be using the application.
Follow the steps to Install a Google Workspace Marketplace App in your Domain.
You will now need to enter the information obtained from the App Registration and API Permissions.
To complete this step, you will need the following information:
- Microsoft Azure (all information obtained from Azure App Register)
Client ID
Tenant ID
Secret
- Google Workspace
Domain
- this is the domain your users use when logging into GoogleService Account Email
- service account user created in previous stepsScopes
- what Google services are we accessing (calendar, admin groups, etc)Private Key
- available via the JSON downloaded from Google Cloud ConsoleService User
- a Google Workspace user with required permissions to read resource calendars/user informationUser Agent
- user defined and helps with looking at Google logs to see application actions
-
Open PlaceOS Backoffice and login as an administrator
-
Navigate to the Admin Tab
-
Select Staff API
-
Select the Domain you want to configure
-
Click Add Tenant
-
Enter the information required\
-
If you are configuring access for Microsoft 365 ensure you tick 'Delegated Access' and enter
teamsForBusiness
in the Conference Type field.
-
Save
The easiest way to test the Staff API Configuration is using the PlaceOS Calendar Driver or Microsoft API Calendar Driver for 365 Delegation.
The staff-api
logs will show any errors in configuration.
We can view these logs by connecting to the server and running docker logs --tail 99 -f staff-api
.
An example log with an authentication error to Microsoft 365:
level=[E] time=2021-06-24T04:10:58Z program=StaffAPI source=action-controller client_ip=218.214.254.247 request_id=50173a7d-a819-4413-8f8a-94adf592f309 domain=poc.placeos.com tenant_id=71 event=error method=GET path=/api/staff/v1/calendars/free_busy?period_start=1624507858&period_end=1624543199&zone_ids=zone-HDvnRd_9lAS status=500 duration=345.62ms
error fetching token UNAUTHORIZED (401)
{
"error": "invalid_client",
"error_description": "AADSTS7000215: Invalid client secret is provided.\r\nTrace ID: 6f090c0f-079f-4930-a123-b1242a4f3f00\r\nCorrelation ID: 0424faa6-2325-4c79-b0e3-726d68db7655\r\nTimestamp: 2021-06-24 04:10:58Z",
"error_codes": [
7000215
],
"timestamp": "2021-06-24 04:10:58Z",
"trace_id": "6f090c0f-079f-4930-a123-b1242a4f3f00",
"correlation_id": "0424faa6-2325-4c79-b0e3-726d68db7655",
"error_uri": "https://login.microsoftonline.com/error?code=7000215"
}