LogoLogo
  • PlaceOS Documentation
  • Overview
    • Key Concepts
      • Drivers
      • Interfaces
      • Modules
      • Settings
      • Systems
      • Triggers
      • Zones
    • Languages
      • Crystal
      • TypeScript
    • Protocols
      • MQTT
      • SAML
      • OAuth2
  • How To
    • Configure PlaceOS for Microsoft 365
      • Step 1: Room Calendar Access
        • Create Azure App Registration (Application Permissions)
        • Exchange Calendar Group
        • Limit Application Permissions
        • Configure PlaceOS Calendar Driver
      • Step 2: User Authentication & Calendar Access
        • Create a PlaceOS Authentication Source
        • Create Azure App Registration (Delegated Permissions)
        • Configure PlaceOS Authentication Source
        • Add User Login Redirects
      • Concierge Access
      • Troubleshooting
        • Blocked or Blacklisted IP Error
    • Configure PlaceOS for Google Workspace
      • Google Configuration
        • Create Google Cloud Project & Enable API
        • Configure Google Cloud Service Account
        • Add Google Workplace Permissions
        • Create Google Marketplace App (optional)
        • Google Workspace Service User (RBAC)
        • Configure Access to Google Resource Calendars
      • User Authentication
        • Create a PlaceOS Authentication Source for Google
        • Create Google Cloud OAuth2 Client App
        • Configure PlaceOS Auth Source for Google
        • Add User Login Redirects
    • Deployment
      • Deploy AWS Fargate on Modular CloudFormation Stacks
      • Deploy AWS Fargate on Nested CloudFormation Stacks
      • Writing Import Scripts
    • Analytics
      • MQTT Integration
    • Backoffice
      • Add a Domain to PlaceOS
      • Backoffice File Upload
      • Configure Staff API
      • Calendar Driver
      • Enable Sensor UI
      • Bookings Driver
      • Configure a webhook
    • Authentication
      • Azure B2C
        • Azure B2C Custom Policy Framework
        • Configure PlaceOS for Azure B2C
        • 365 Room Resources on Azure B2C
      • Configure SAML SSO
        • Configure SAML2 with AD FS
        • Configure SAML2 with Auth0
        • Configure SAML2 with Azure AD
        • Configure SAML2 with Google Workspace
      • Configure OAuth2 SSO
      • X-API Keys
      • Bearer tokens
    • Location Services
      • Location Services
      • Area Management
      • Discovering User Devices
      • Locating Users on a Network
      • People Finding with Cisco Meraki on PlaceOS
      • People Finding with Juniper Mist on PlaceOS
    • Notifications
      • Catering Orders
    • User Interfaces
      • Booking Panel App
      • Workplace App
      • Native Booking Panel App
      • Deploy a Frontend Interface
      • Microsoft Outlook Plugin
      • Configure Endpoint Auto Login
      • SVG Map Creation
      • Configuring a default UI
  • Tutorials
    • Setup a dev environment
    • Backend
      • Troubleshooting Backend Failures
      • Import Bookable Rooms
      • Writing A Driver
        • Testing drivers
        • ChatGPT / LLM Capabilities
          • Native GPT Plugins
      • Testing Internal Builds
    • Backoffice
      • Adding Drivers & Modules
      • Add Zone Structure
    • Common Configurations
      • Asset Manager
      • Catering
      • Locker Booking
      • Webex Instant Connect
      • Desk booking
      • Sensor Data Collection
        • Configure Kontakt IO
        • Configuring Meraki
        • Configuring DNA Spaces
      • Elevated Privileges
  • Reference
    • API
      • Real-time Websocket
      • Rest API
      • Staff API
    • Drivers
      • PlaceOS
        • Bookings
        • Staff API
        • Visitor Mailer
        • Lockers
      • Microsoft
        • Graph API
    • PlaceOS Skills
    • Privacy Policy
    • Recommended Products
    • Supported Integrations
    • System Architecture
    • System Functionality & Requirements
    • Infrastructure Requirements
    • Security Compliance
      • FAQ
      • GDPR
      • Security
    • Microsoft Azure Permissions
  • Glossary
  • 🎯PlaceOS Roadmap
  • 🆘PlaceOS Support
  • 👩‍💻PlaceOS Github
  • 📝PlaceOS Changelog
Powered by GitBook
On this page
  • Prerequisites
  • Configure Providers
  • Microsoft Azure (365)
  • Create Azure App
  • Grant Graph API Permissions
  • Generate Azure API Secret
  • Google Workspace
  • Configure the Service Account
  • Configure Service Account Permissions
  • Creating a Marketplace Application
  • Configure Staff API on PlaceOS
  • Test Staff API Configuration
Export as PDF
  1. How To
  2. Backoffice

Configure Staff API

How to Configure the Staff API on PlaceOS

PreviousBackoffice File UploadNextCalendar Driver

Last updated 2 years ago

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 .

To enable room bookings, the .

Prerequisites

  • Access on Microsoft Azure or Google Cloud Console & Workspace to create apps and API permissions

  • Administrator access to your PlaceOS Backoffice

Configure Providers

To enable Staff API you must complete the necessary configuration in your cloud provider.

Instructions for Microsoft 365 and Google Workspace are below.

Microsoft Azure (365)

To use Staff API with 365 you will need to create an Application in App Registration.

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.

Create Azure App

  1. Log in and select the correct Subscription for your application

  2. Select New Registration

  3. Enter the required information

    • Name it and select the appropriate "Support Account types" (typically "Single tenant")

    • Optionally paste the PlaceOS Assertion URL

  4. Register the app

Grant Graph API Permissions

You will now need to grant Graph API Permissions on your App.

  1. Select the app you would like to give permissions

  2. Click API Permissions

  3. Click Add Permission

  4. Click Microsoft Graph

  5. Select Delegated permissions

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

  7. Click Add Permissions

  8. Grant Admin Consent for all the new permissions

Generate Azure API Secret

You will now need to create the secret to allow PlaceOS Staff API to Authenticate.

  1. Navigate to Certificates & Secrets

  2. Select New client secret

  3. Give your secret a description e.g. PlaceOS Prod App Secret and click Add

  4. Return to the App Overview

Google Workspace

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.

Configure Google Cloud API Project

  1. Select Enable APIs and Services

  2. Search for and enable the following SDK:

    • Admin SDK (for staff directory)

    • Google Calendar API

    • Google Drive API (for attachments)

  3. For limiting access to a subset of the organization, you may also want to enable:

    • Marketplace SDK (not Marketplace API)

    • Drive API

Configure the Service Account

  1. Under APIs & Services, navigate to Credentials

  2. Create a new Service Account

  3. You can ignore the next steps in the wizard, click Done to return to the list of service accounts

  4. This will save a JSON File to your computer, you will need this information to configure the service.

  5. Click Save

Configure Service Account Permissions

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”

  1. Open the JSON File that we saved in the previous step

  2. Copy the client_id

  3. Select Security

  4. Scroll down to API Controls

  5. Select Manage Domain Wide Delegation

  6. Click Add new and enter the client_id you extracted earlier

  7. Add the following API Scopes:

    • https://www.googleapis.com/auth/calendar

    • https://www.googleapis.com/auth/admin.directory.user.readonly

  8. Click Authorize

  9. Ensure you enable API Access by going to Security -> API Controls

  10. Select Trust internal, domain owned apps

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.

Creating a Marketplace Application

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.

  1. Select the Configuration tab

  2. Upload icons as required

  3. A Terms of Service URL is also required, you can set this to your companies homepage

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

  5. Fill in the details and icons for the Drive Application

  6. Once completed, return to the marketplace application form

  7. Ensure you set visibility to My Domain

  8. Click Save Changes

Deploy the marketplace application to the organizational unit that will be using the application.

Configure Staff API on PlaceOS

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 Google

    • Service Account Email - service account user created in previous steps

    • Scopes - what Google services are we accessing (calendar, admin groups, etc)

    • Private Key - available via the JSON downloaded from Google Cloud Console

    • Service User - a Google Workspace user with required permissions to read resource calendars/user information

    • User Agent - user defined and helps with looking at Google logs to see application actions

  1. Open PlaceOS Backoffice and login as an administrator

  2. Navigate to the Admin Tab

  3. Select Staff API

  4. Select the Domain you want to configure

  5. Click Add Tenant

  6. Enter the information required

  7. Save

Test Staff API Configuration

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"
}

You may have already completed this step if you have configured

Navigate to the

Navigate to

Copy and Save the Secret Value (you will need this in the next step)

Copy and Save the Client ID and Tenant ID (you will need these in the next step)

For further information see .

Go to

Configure an existing API Project or Create a New API Project

Open your API Project and select APIs & Services followed by Dashboard

Click on the Create Credentials and select Service Account Key

Click the service account you created and select the Keys tab to create an access key

Once the key has saved, return to the Details tab and enable Domain Wide Delegation

Navigate to

https://www.googleapis.com/auth/drive.file

On navigate to the API Services Dashboard

Select the G Suite or Google Workspace Marketplace SDK

Fill in the app name and description, un-check Enable individual install

Enable drive extension and click Configure drive SDK

Follow the steps to .

If you are configuring access for Microsoft 365 ensure you tick 'Delegated Access' and enter teamsForBusiness in the Conference Type field.

The easiest way to test the Staff API Configuration is using the or .

PlaceOS Calendar driver must also be configured
PlaceOS Bookings driver must be also configured
PlaceOS for Microsoft 365 User Authentication.
Azure Portal
App Registrations
Creating and Managing Service Accounts
Google Cloud Console
Google Workspace Admin
Google Cloud Console
Install a Google Workspace Marketplace App in your Domain
PlaceOS Calendar Driver
Microsoft API Calendar Driver for 365 Delegation
API Permissions
New App Registration
Add Permission
Graph
Graph Application Grants
Graph Application Grants
New Secret
New Secret
Client ID and Tenant
Google API Project
Google New API Project
Google API Service
Google New Service Account
Google API Credentials
Google Service API Key
Google Domain Wide Delegation
Google JSON Key
Google Scopes
Google Trust Internal Apps
Google G Suite Marketplace
Google G Suite Config Tab
Google Client ID
Google G Suite App
Google Drive Extension
Google Visibility
Staff API Admin