PlaceOS is a software platform which enriches interaction with physical space. It provides tools to design, build and iterate integrated digital experiences for physical environments. To do this, it merges any and all elements - from lighting and AV to entire BMS - without the legacy baggage.

Integration of disparate systems, devices and services forms a seamless experience for your space.

Automation boosts workplace efficiency and ease of use for any space.

Iteration lets your space constantly improve and grow with you and your needs.

Sections of this site

The documentation for PlaceOS is split into 4 categories.

See the overview for high-level coverage of topic areas.

Try a tutorial to learn in more detail about a process or feature.

Read a how-to guide for docs to help you with a specific task.

See the reference material for detailed technical docs.

Videos and Demonstration Apps

You can watch a short or in-depth video demonstrating the functions of PlaceOS Backoffice.

Take our Workplace or Concierge Demo Apps for a spin.

Settings are the configuration information that define how a deployment should behave. Any level can have defined settings, which are ultimately consumed by modules. Zones, systems, drivers or modules can have settings defined on them. Together, these create a system configuration that is easier to manage at scale.

Examples of some common uses for settings are:

• Available video inputs/outputs

• Source names

• DSP block IDs

• Lighting control IDs

• Device authorization information

• Desk / room auto-release timeouts

Within driver files are definitions for naming conventions and expected values for the settings. They will vary based on each deployment, but the general structure will always be similar.

JSON definitions

Settings are expressed as JSON data, that is, key-value pairs:

{
  "key": "value",
  "foo": [1, 2, 3],
  "bar": true 
  "baz": { 
    "qux": 1.234
  }
}

Settings inheritance

Different layers define settings which then combine to produce the final configuration. This simplifies large deployments, standardizes systems and reduces management overhead.

Systems inherit all the settings from each zone that they are in. Zones pass down their settings to all systems within them. Similarly, Modules inherit all the settings from the driver that they instantiate.

Only Systems and Modules inherit Settings

Systems

Systems inherit settings from their Zones, in the order specified on their Zones tab (highest priority at top).

Zone Settings (in the hierarchical order specified by the System) > System Settings

Modules

Logic modules inherit settings from both the Driver from which they are instantiated and the System in which they are added (including the settings that the System has inherited from it's Zones). System settings override Driver settings.

Driver settings > Zone Settings (in the hierarchical order specified by the System) > System Settings > Logic Module Settings

All other Module types (e.g. Device, Service) only inherit Settings from the Driver from which they are instantiated.

Driver settings > Logic Module Settings

Specific Overrules General

Settings inherited from a zone or driver combine with any settings defined directly on the system or module. If an inherited setting has the same key as one defined directly, the latter will override the inherited one. This lets you write general settings at a higher common level, with more specific ones on each lower tier.

Purpose

They serve two main purposes:

1. Logical groupings of systems with common traits, generally:

   • Those in the same physical space, but at a larger scale than systems. For example, if each system is a room then the building would be a zone

   • Systems of the same general concept. For example if you have customer-facing systems zoned separately to internal systems

Settings Inheritance

Zones do not inherit settings from the Parent zones.

Guides

Drivers are the core components of the PlaceOS platform. They combine to help different parts of the digital ecosystem interact with each other. PlaceOS has drivers that fall into one of two categories:

Integration Drivers

• Communicate with external systems and lets them talk to PlaceOS

• Represent hardware or software platforms (i.e. device or service)

• Control any functionality of the external systems and handle any incoming data

Logic Drivers

• Coordinate interactions between modules

• Don't map to specific physical objects

• Represent abstract or conceptual functions

• May use a variety of devices or software platforms

Drivers and Modules

Modules are instances of drivers, letting the rest of PlaceOS access their specific functions.

Driver Map

The driver map shows driver dependencies in PlaceOS.

A system is the main logical building blocks within PlaceOS. They contain three components:

• Basic metadata (name, description etc)

Purpose

Systems often represent physical spaces, such as meeting rooms. They can also represent connected items which run across physical spaces, such as a range of digital signage. Otherwise, they can represent a non-physical system with data inputs and outputs, such as a payment portal.

Systems and Zones

Settings Inheritance

Systems inherit settings from their Zones, in the order specified on their Zones tab (highest priority at top).

Zone Settings (in the hierarchical order specified by the System) > System Settings

Overview

Security Assertion Markup Language (SAML) is an open standard that allows Identity Providers (IdP) to pass authorization credentials to Service Providers (SP).

SAML is an umbrella standard that covers federation, identity management and SSO.

The SAML specification defines three roles:

• The principal (typically a human user)

• The Service Provider (SP)

• The Identity Provider (IdP)

In the primary use case addressed by SAML, the principal requests a service from the Service Provider. The Service Provider requests and obtains an authentication assertion from the Identity Provider.

SAML in PlaceOS

By default, PlaceOS uses a local authentication method. PlaceOS also supports Federated Authentication via SAML as the advised method of user authentication.

Under this configuration, by the SAML Standard, PlaceOS is the Service Provider (SP).

Authentication providers can be associated with Domains in PlaceOS.

• Configure SAML in PlaceOS

• Add Domains in PlaceOS

Resources

• Security Assertion Markup Language (SAML) V2.0 Technical Overview

Crystal is a programming language with the following goals:

• Have a syntax like Ruby (but compatibility with Ruby is not a goal)

• Statically type-checked but without having to specify the type of variables or method arguments

• Be able to call C code by writing bindings to it in Crystal

• Have compile-time evaluation and generation of code, to avoid boilerplate code

• Compile to efficient native code

Why Crystal

Security: we can distribute a single static binary in a docker container, there is little chance of exploit.

Speed: the binaries are fast, see Spider-Gazelle.

Developer happiness: all the benefits of Go Lang with the elegance of Ruby.

Resources

Installing Crystal

Follow these instructions

Crystal Documentation

• Language Reference

• Standard library API

• Roadmap

Overview

MQTT is an OASIS standard messaging protocol for the Internet of Things (IoT). As a lightweight publish/subscribe messaging transport, it's ideal for connecting remote devices with a small code footprint and minimal network bandwidth.

Its versatility makes it suitable for a wide variety of industries. These include automotive, manufacturing, telecommunications, oil and gas, etc.

MQTT allows for messaging between device-to-cloud and cloud-to-device. This simplifies broadcasting messages to groups of receivers. Further information is available from the MQTT Website

MQTT in PlaceOS

PlaceOS supports publishing module state information via MQTT. This provides environment information to external systems such as Amazon MQTT Service

MQTT messages consist of a header and a payload and typically have low bandwidth usage. The header declares the topic of the message, and the payload carries data as key-value pairs.

PlaceOS uses two types of message sent over MQTT: State Changes and Metadata. For further information on configuring MQTT for PlaceOS, see the guide on MQTT Integration

Resources

• MQTT Website

• PlaceOS State Source Service

Triggers provide a way to dynamically link state and behavior across different modules. They define actions that will occur based on certain criteria, such as:

• System state

• Time

• External input such as a webhook

Customization

Triggers permit modules to influence the behavior of other modules directly. In PlaceOS Backoffice, users can create, assign and manage triggers. This way, they can customize extensive event driven behavior. That accompanies more complex core system behavior written in the logic modules.

Overview

OAuth is an open standard for access delegation, commonly used as a way for internet users to grant websites or applications access to their information on other websites but without giving them the passwords.

OAuth provides clients secure delegated access to server resources on behalf of the owner. It specifies a process for resource owners to allow third-party access to their server resources. Most importantly, it allows access without providing credentials.

OAuth works directly with HTTP. It issues access tokens to third-party clients through an authorization server. The resource owner approves which tokens get issued. The third party then uses the token to access the protected resources hosted by the resource server.

OAuth2 in PlaceOS

PlaceOS uses the OAuth Standard (OAuth2) to integrate to third-party services including:

• Microsoft Graph API

• Google API

• Cisco Meraki

OAuth provides PlaceOS access to read and write specific information needed for our application.

The Service Provider (SP) can impose extra permissions and scopes including read/write permissions.

PlaceOS also offers OAuth Access to our Staff and Booking API.

Resources

These steps will help Azure Administrators make the necessary configurations for PlaceOS User Authentication via Microsoft Azure Active Directory (Federated Authentication) and PlaceOS Calendar Driver, for PlaceOS Room Booking.

If you only require User Authentication you do not need to complete the Calendar Access steps.

If your PlaceOS will have room booking enabled, you will need to complete the Calendar Access steps.

Once the above steps are complete, we can add the required driver on PlaceOS and configure it with the Application ID, Tenant ID and Secret generated in previous steps.

Prerequisites

• PlaceOS Administrator Access

• Azure Application ID

• Azure Tenant ID

• Azure Application Secret

Add Calendar Driver

If you have already added the calendar driver, you can skip this step.

1. In PlaceOS Backoffice navigate to the Drivers tab.

3. Select the Drivers Repository.

4. Search for Microsoft Graph API

5. Select the most recent commit.

Configure Calendar Driver

1. In PlaceOS Backoffice navigate to Systems.

2. Select the Organisation System, typically this is *Org Name or similar.

3. Click Modules.

4. Click Add New Module.

5. Search for the Microsoft Graph API Driver.

6. Enter the domain your users will use to access PlaceOS eg. https://yourcompany.placeos.run

8. Click the Microsoft Graph API Module in the Module list to go to the module settings.

9. Click the Unencrypted tab.

10. Enter the following configuration, noting your application ID, tenant ID and secret.

calendar_config:
  tenant: your-tenant-id
  client_id: your-application-id
  client_secret: your-client-secret
  conference_type: teamsForBusiness

Testing Calendar Driver

In order to test the Calendar Driver with Delegated Access for Microsoft 365 you will require at least 1 system configured with a room resource and the Microsoft Graph API Calendar Module and Bookings Module added to the system.

1. Navigate to a system configured with the correct modules and a valid room resource address.

These steps will configure PlaceOS to use Microsoft Azure Active Directory as a federated authentication provider to allow users to sign in using their corporate credentials. The same Azure App Registration will be used to allow users logged in to PlaceOS Apps to book Exchange Online meeting rooms.

PlaceOS prefers to use OAuth2.

One advantage of using OAuth2 over SAML is that it is possible to require individuals to authorise access to certain resources. Thus users grant access to PlaceOS which can maintain a refresh token for offline access as needed.

Prerequisites

• Confirm the final UAT and PROD URLs of the web apps

• Ensure that the DNS entries for these URLs are active and forwarding to the server(s)

• Ensure that the SSL certificates for the above domains are signed and recognized as secure

The PlaceOS Application requires access to read the booking state of room resources within the Microsoft 365 domain.

This is achieved by creating a Microsoft App Registration with Application Permissions, configuration of an Exchange Group for Room Resources and applying an Application Restriction Policy to the Exchange Group.

Complete the following steps to correctly configure calendar access.

The steps should be completed in the following order:

1. Azure App Registration: Create the Azure App Registration PlaceOS will use to authenticate with the MS Graph API.

2. Exchange Calendar Group: Create an exchange calendar group to provide PlaceOS Access with only the required room resource calendars.

3. Limit Application Permissions: Apply an application permission to the Exchange Calendar Group.

4. Configure PlaceOS Calendar Driver: Apply the required configuration in PlaceOS to allow the platform to connect and read your calendar resources.

PlaceOS has made the decision to implement our resource calendar visualisation in this method to heavily restrict the application access to organisation calendars.

This method creates a strict separation of concerns between user authentication and access to PlaceOS and the PlaceOS Room Booking Functions, you can think of this as the PlaceOS Daemon.

Using the documented method will prevent the application from reading all calendars in your domain, such as the CEO's calendar and ensure scope is enforced to only provide access to those room resource calendars required for the correct function of PlaceOS.

Overview

TypeScript is an open-source language which builds on JavaScript by adding static type definitions. Types provide a way to describe the shape of an object, provide better documentation, and allow TypeScript to validate your code.

TypeScript and Angular

Angular applications must be built with TypeScript. As PlaceOS frontend applications are mainly written in Angular, they need TypeScript.

Versioning

TypeScript version depends on your Angular version.

PlaceOS Frontends uses Angular 12 and TypeScript 4.2.4.

TypeScript References and Tooling

The TypeScript Handbook provides detailed documentation specifically related to TypeScript.

PlaceOS uses NX tools to assist with testing and building JavaScript Applications.

NX adds Jest for Unit Testing and Cypress for Integration and End-to-End Testing.

The Angular CLI lets you develop, scaffold and maintain Angular applications. It's used with PlaceOS frontend applications.

Automated Browser Testing

Automated browser testing can check application test cases. Any Selenium based automated test suite would be suitable for this purpose. One possible tool is Katalon Studio.

*[CLI]: Command-line Interface

In this step, we will create a group that will contain the room resources you would like PlaceOS to access. Following this, we will create a restricted access policy applied to the group.

This prevents the PlaceOS Application from reading all calendars in your organisation and negates some security concerns around the applications access to sensitive information such as the CEO’s calendar.

Prerequisites

• Exchange Administrator Access

Procedure

1. Navigate to the Exchange Admin Centre.

2. Click Recipients.

3. Click Groups.

4. Click 'Add a group'.

6. Click Next.

8. Click Next.

10. Click Next.

12. Click Next.

14. Click Next.

15. Click Finish.

16. Note down the group email address as this will be required in the next step.

Prerequisites

• Microsoft Azure Administrator Access or Permission to Create App Registrations

Procedure

In this step, we will create the application access PlaceOS will use to access the room resource calendars in your organisation via Microsoft Graph API.

After completion of this step, we will apply a policy restriction so the application can only access room resource calendars.

1. Login to Microsoft Azure Portal.

2. Navigate to App Registration blade.

3. Create a new App Registration called PlaceOS Bookings Visualiser

   • Supported account types should be ‘Accounts in this organisational directory only’

   • No redirect URI is required.

4. Note down the:

   • Application (client) ID as this will be required in the next step and also to be provided to PlaceOS.
5. Once created, navigate to Certificates and Secrets.

7. Navigate to 'API Permissions'.

8. Click 'Add Permission'.

9. Click 'Microsoft Graph'.

10. Click 'Application Permissions'.

12. Click 'Add permissions'.

14. Configuration of the Azure App is now complete.

15. Supply PlaceOS or your integration partner with (be aware that supplying these credentials to PlaceOS prior to configuring the application policy in exchange will allow PlaceOS to see ALL calendars in your organisation):

    • Application ID

    • Tenant ID

    • Secret

Prerequisites

• PlaceOS Backoffice Administration Access

Procedure

1. In PlaceOS Backoffice navigate to the Domains tab.

2. Select the domain you would like to add Microsoft Authentication to.

3. Click the Authentication Tab.

4. Click New Auth Source.

5. Select OAuth as the auth source type.

6. Provide a name eg. 'Microsoft AD'.

8. Copy the Auth Source ID eg. oauth_strat-Dw9b-5_lO3

9. You will require the Auth Source ID to be used as the Azure App Registration Callback URI, for example: `https://placeos-dev.im/auth/oauth2/callback?id=oauth_strat-Dw9b-5_lO3`

Issue

An issue may arise where users receive an email from Microsoft when attempting to book a room via PlaceOS that states the email was undeliverable to the destination, noting the sender and receiver are both in the same domain.

The specific error:

Diagnostic information for administrators:

Generating server: SEZPR02MB5759.apcprd02.prod.outlook.com

LON-M01.01@l6yy.onmicrosoft.com
Remote Server returned '550 5.7.501 Service unavailable. Spam abuse detected from IP range. For more information please go to http://go.microsoft.com/fwlink/?LinkId=526653. S(2017052602) [SI2PR02MB5562.apcprd02.prod.outlook.com]'

Original message headers:

Received: from SEZPR02MB5759.apcprd02.prod.outlook.com
 ([fe80::2859:6314:4b05:dd7b]) by SEZPR02MB5759.apcprd02.prod.outlook.com
 ([fe80::2859:6314:4b05:dd7b%2]) with mapi id 15.20.5395.021; Tue, 5 Jul 2022
 00:37:40 +0000
MIME-Version: 1.0
Content-Type: text/plain
Date: Tue, 5 Jul 2022 00:37:40 +0000
Message-ID:
	<SEZPR02MB5759F90749FCD41572767AE8C3819@SEZPR02MB5759.apcprd02.prod.outlook.com>
Subject: test

Root Cause

This is caused by API Spam from the PlaceOS application to the Microsoft 365 via the Graph API Endpoint.

This condition is triggered where PlaceOS drivers are set to a running state against your tenant prior to correct configuration and API access been granted.

PlaceOS drivers related to Microsoft Graph API including the Microsoft Graph API, Staff API, Calendar Driver and Bookings Driver should not be put into an active state until configuration of Microsoft Graph API is complete.

Resolution

1. Navigate to the Exchange Admin Centre

2. Click Support

3. Raise a new Support Request

4. Advice you have received an error that email is undelivered due to spam blacklist.

5. A Microsoft agent will contact you and run a diagnostic tool that will resolve the issue typically within an hour.

In this step, we will now apply the restriction to the PlaceOS Room Booking group, restricting it to only see the calendars required for the purposes of room booking.

Prerequisites

• Exchange Resource Group

• Exchange Administrator Access

• Azure App Registration App ID

Procedure

1. From Exchange Online, or any other service with PowerShell connected to Exchange, open a new PowerShell Terminal.

2. Run the following command, replacing the arguments for AppID, PolicyScopeGroupID and Description. We will use the AppID and PolicyScopeGroupID from previous steps:

New-ApplicationAccessPolicy -AppId e7e4dbfc-046f-4074-9b3b-2ae8f144f59b -PolicyScopeGroupId EvenUsers@contoso.com -AccessRight RestrictAccess -Description "Restrict this app to members of distribution group PlaceOS Room Booking."

3. The application policy should now be applied, this can be tested using the `Test-ApplicationAccessPolicy` cmdlet:

Test-ApplicationAccessPolicy -Identity user1@contoso.com -AppId e7e4dbfc-046-4074-9b3b-2ae8f144f59b

4. If we test using a regular user, the result should be denied:

5. If we test using a room resource address, the result should be granted:

Prerequisites

• OAuth2 Callback URL from PlaceOS Authentication Source

• Microsoft Azure Administrator Access or App Registration Role

Procedure

1. Login to Microsoft Azure Portal.

2. Navigate to App Registration blade.

3. Create a new App Registration called PlaceOS User Authentication

   • Supported account types should be ‘Accounts in this organisational directory only’

   • See also: https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app#register-an-application

4. Configure a Web Redirect URI with the PlaceOS Redirect URI created in the previous step eg. https://<YOUR-PLACEOS-DOMAIN>/auth/oauth2/callback?id=<OAUTH_STRAT-XXXX>
5. Note down the:

   • Application (client) ID as this will be required to be provided to PlaceOS.
6. Once created, navigate to Certificates and Secrets.

8. Navigate to 'API Permissions'.

9. Click 'Add Permission'.

10. Click 'Microsoft Graph'.

11. Click 'Delegated Permissions'.

12. Add the following Permissions:

    • Calendars.ReadWrite

    • Calendars.ReadWrite.Shared

    • Group.Read.All

    • User.Read.All

    • offline_access

    • openid

    • profile

13. Click 'Grant admin consent'

14. This completes the App Registration.

Once the Authentication Source is configured, we need to ensure PlaceOS Applications redirect the user to the authentication provider to login.

Prerequisites

• PlaceOS Backoffice Administrator Access

Procedure

1. Login to PlaceOS Backoffice

2. Navigate to the Domains tab.

3. Select the Domain for your organisation.

4. Click on the Edit icon.

5. Set the login URL to /auth/login?provider=[AUTH-TYPE-HERE]&id=[AUTH-ID-HERE]&continue={{url}}, replacing the [AUTH-TYPE-HERE] with one of (adfs, oauth2, ldap) & the [AUTH-ID-HERE] with the authentication source ID created in 'Creating a PlaceOS Authentication Source' instructions, leaving the {{url}} as is.

Debugging

ADFS:

The first step in this process should be to get the raw request.

Often you can see if a request attribute is not lining up to an attribute statement by inspecting the XML.

You can paste the resulting data into this SAML Decoder

Then paste the XML into Pretty Print (so it’s readable)

There are two methods of getting SSO data, described below:

1. If you have an account you can use to test

2. If the client is logging in and you have access to logs

Self Check

1. Open the Chrome or Firefox inspection tool

2. Go to the network tab

3. Select: preserve log

4. Go through the login flow

The request coming back to the assertion URL is the one you want to inspect.

Assertion URL: /auth/[AUTH-TYPE-HERE]/callback?id=[AUTH-ID-HERE]

ADFS: Copy and paste the SAML response into the SAML decoder.

• A specific physical device controlled by PlaceOS,

• A specific digital platform, or

• Logic that controls how a specific set of hardware and software should interact

Purpose

All modules have two broad functions on the system they control:

1. State: status information about the integration or higher level logic they control. Some examples of this kind of data could be:

   • Power status

   • Upcoming booking info

   • Current user

2. Behavior: actions which the device, service, or logic can do. Some examples of these actions could be:

   • Power on/off

   • Create/edit booking

   • Post a chat message

Starting and Stopping Modules

Each module can be individually started or stopped at any time. When started, the driver connects to the physical or digital integration and keeps track of its status. When stopped, the driver disconnects from its integration and will not send or receive any data or commands. For logic modules, this enables / disables its functionality.

Modules and Systems

• A lighting gateway

• Centrally installed audio-visual equipment

• A common service such as a chatbot integration

Logic Modules

Logic modules are different to all other types of Modules (e.g. Device/Service modules) as they do not communicate to external devices/services. They only have access to the other Modules within the same System and co-ordinate actions across then.

As such, Logic Modules are strictly bound to the first System in which they are added, and should not be added to multiple Systems.

Settings Inheritance

Logic modules inherit settings from both the Driver from which they are instantiated and the System in which they are added (including the settings that the System has inherited from it's Zones). System settings override Driver settings.

Driver settings > Zone Settings (in the hierarchical order specified by the System) > System Settings > Logic Module Settings

All other Module types only inherit Settings from the Driver from which they are instantiated.

Driver settings > Logic Module Settings

To use google APIs you’ll need a server to server OAuth2 application configured. This involves creating a service account that will be used for authentication.

The service account can then “act as” staff in the organisation to perform action on their behalf, such as booking meeting rooms.

See: https://cloud.google.com/iam/docs/creating-managing-service-accounts

There are some actions that regular staff do not have permission to perform, such as:

• Listing the users in the organisation

• Interacting directly with resource calendars.

For this functionality a user account should be created that is granted special permissions for these activities.

Interfaces are web pages that provide users with a direct method of interaction with PlaceOS. They are suitable for any experiences that lend themselves to screen-based interaction. Common examples of interfaces are:

• A staff app

• Meeting room control interfaces

• A booking system

Prerequisites

• Google Cloud Console Administrative Access or Permissions to:

  • Create OAuth2 Client ID.

Procedure

Create Service Account

2. Click Create Credentials

5. Ignore the next steps in the Wizard and click return to return to the list of service accounts.

Create Keys

1. Click on the PlaceOS Service Account you just created.

2. Click Add Key

5. This will save a JSON file to your computer, this will be required to complete the PlaceOS Configuration Steps.

7. Click Save.

Follow these steps to configure a Google Cloud Project and Enable API for PlaceOS.

Prerequisites

• Google Cloud Console Administrative Access or Permissions to:

  • Create Projects

  • Enable API's

  • Create OAuth2 Client ID.

Procedure

Configure GCP Project

1. Goto: https://console.cloud.google.com/

2. Click the Projects Dropdown

5. Click Create

Enable API

1. If not directed, open your new project.

3. Select 'ENABLE APIS AND SERVICES'

4. Search for and enable the Following API:

   • Admin SDK (for staff directory)

   • Google Calendar API

   • Google Drive API (for attachments)

   • Marketplace SDK (not Marketplace API

This only applies to organizations where a particular region or department will be using the application.

This step is not applicable to most organizations.

Prerequisites

• Google Cloud Console Administrative Access or Permissions to:

  • Create Marketplace Apps.

• Marketplace SDK Enabled

Procedure

1. Navigate to Google Cloud Console

2. From the navigation menu select API Services then Dashboard

5. Enter an App Name and Description

7. Upload Icons if required

8. Terms of Service URL is required, you can set this to your organisations homepage

9. Enter the Scope URL:

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

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

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

11. Fill in the details and icons for the drive application. This is required to have the application deployed without going through the public marketplace store and onboarding process.

13. Click 'Save Changes'

14. You will now need to deploy the Marketplace App to the segment of the organisation that will be using the application, refer to these instructions: https://support.google.com/a/answer/172482?hl=en

Prerequisites

• Google Workspace Administrator Access

• JSON Service Account File generated in Configure Google Service Account step

Procedure

1. Go to https://admin.google.com

2. Navigate to Security

3. Scroll down to Advanced Settings

4. Select 'Manage API Client Access'.

5. Add the following API Scopes to the client_id you extracted earlier.
6. Click Authorise.

7. Navigate to the Security Tab and select API Controls.

PlaceOS recommends managing your Concierge users directly in 365 or Exchange Administration to allow Concierge users to be added and removed as required by the business.

Once changes are made on 365 or Exchange Admin the changes will be available to the user in real time via the PlaceOS Concierge App.

Prerequisites

• 365 or Exchange Administrator Access

  • Group Creation

  • Resource Management

Procedure

Group Creation

1. Navigate to 365 Admin Centre

9. Click Finish followed by Create Group.

Delegate Room Resources

2. Select the room you want to provide concierge access to.

3. Select Edit Exchange Settings.

4. Select mailbox delegation.

6. Select Save.

7. Repeat these steps for other rooms as required.

You may also apply the Concierge group to a list of rooms via Powershell: https://learn.microsoft.com/en-us/exchange/recipients-in-exchange-online/manage-resource-mailboxes

Prerequisites

• PlaceOS Backoffice Administrator Access

Procedure

1. In PlaceOS Backoffice navigate to the Domains tab.

2. Select the domain you would like to add Microsoft Authentication to.

3. Click the Authentication Tab.

4. Identify the OAuth Source previously created.

5. Click the Edit Icon.

6. Update missing fields per the table below.

These fields are specific to the OAuth2 provider and tend to differ slightly between providers.

PlaceOS Staff API

Once you have completed the above steps, you will also need to create a StaffAPI Record for your domain.

Prerequisites

• Google Cloud Console Administrative Access or Permissions to Enable API's and create OAuth2 Client ID.

Procedure

Follow Google instructions to add a new client application to your Google account and obtain the client_id and secret.

These steps will help Google Cloud & Google Workspace Administrators make the necessary configurations for PlaceOS User Authentication via Google Workspace (Federated Authentication) and Calendar Visualisation for PlaceOS Room Booking.

If you only require User Authentication you do not need to complete the Calendar Access steps.

If your PlaceOS will have room booking enabled, you will need to complete the Calendar Access steps.

One advantage of using OAuth2 over SAML is that it is possible to require individuals to authorise access to certain resources. Thus users grant access to PlaceOS which can maintain a refresh token for offline access as needed.

Prerequisites

1. Confirm the final UAT and PROD URLs of the web apps

2. Ensure that the DNS entries for these URLs are active and forwarding to the server(s)

3. Ensure that the SSL certificates for the above domains are signed and recognized as secure

User Access Tokens

User tokens obtained from the OAuth2 flow are stored in the database and can be used for making requests on behalf of the users logging in.

You can obtain a token via POST /api/engine/v2/users/resource_token It will return a JSON payload

{
  # a valid bearer token for the current user
  token:   "1234567",
  # optional unix timestamp (seconds)
  expires: 122345
}

If the OAuth2 service returned a refresh token then this API will always return a valid token, refreshed as required (there is never direct access to the refresh token)

With multiple authentication sources you may have to specify which source to use for OAuth configuration:

Prerequisites

1. Confirm the final UAT and PROD URLs of the web apps

2. Ensure that the DNS entries for these URLs are active and forwarding to the server(s)

3. Ensure that the SSL certificates for the above domains are signed and recognized as secure

4. PlaceOS Backoffice Administration Access

Procedure

1. In PlaceOS Backoffice navigate to the Domains tab.

2. Select the domain you would like to add Google Authentication to.

3. Click the Authentication Tab.

4. Click New Auth Source.

5. Select OAuth as the auth source type.

6. Provide a name eg. 'Google Workspace'.

8. Copy the Auth Source ID eg. oauth_strat-Dw9b-5_lO3

9. You will require the Auth Source ID to be used as the Azure App Registration Callback URI, for example: `https://placeos-dev.im/auth/oauth2/callback?id=oauth_strat-Dw9b-5_lO3`

To perform actions on resource calendars, like reject meetings, the PlaceOS Service User account needs to have delegated access to these calendars.

Prerequisites

• Google Workspace Administrative Access

Procedure

3. Select the Room Resource Calendar

4. Under Share with Specific People add the PlaceOS Service User

There are some actions that regular staff do not have permission to perform, such as:

• listing the users in the organisation

• interacting directly with resource calendars

Prerequisites

• Google Workspace Administrative Access

Procedure

Create a New User

The new user may sit in a different OU to your regular users for security purposes.

Assign Permissions

2. Click the Roles and Privileges tab.

3. Click Edit.

4. Click create Custom Role.

5. On the privileges selection screen, under the 'Admin API Privileges' select the following permissions:

   1. Organization Units: Read

   2. Users: Read

   3. Groups: Read

Overview

This page assists with deploying PlaceOS on AWS using CloudFormation templates. The templates configure a PlaceOS Fargate deployment including an optional VPC configuration. The basic premise is:

1. Upload the nested templates to an S3 bucket

2. Orchestrate the deployment using a root stack template

You can use the upload-s3.sh script in the AWS command-line tool to upload the required files to a configurable S3 bucket.

A CloudFormation template specifies all the components. Each component is designed to deploy as its own CloudFormation stack.

The root stack requires the following files and directory structure:

• Security Groups: infra/sec_groups.yml

• Application Load Balancer: infra/load-balancer-https.yml

• Elastic File System: infra/EFS.yml

• Elasticsearch: managed/elasticsearch.yml

• ElastiCache: managed/elasticache-redis-cluster.yml

• Fargate Cluster: fargate/ecs-cluster.yml

• RethinkDB: fargate/rethinkdb/single/rethinkdb-primary.yml

• etcd: fargate/etcd-service.yml

• dispatch: fargate/dispatch-service.yml

• NGINX: fargate/nginx-service.yml

• Frontends: fargate/frontends-service.yml

• auth: fargate/auth-service.yml

• core: fargate/core-service.yml

• triggers: fargate/triggers-service.yml

• rubber-soul: fargate/rubber-soul-service.yml

• REST API: fargate/rest-api-service.yml

• init: fargate/init-service.yml

VPC Architecture infra/vpc.yml

The VPC root stack template infra/vpc.yml deploys two private and two public subnets. For each of these the user can configure:

• CIDR ranges

• An internet gateway

• Two NAT gateways

• Routes and route tables

The application load balancer is the only component that should deploy in public subnets.

Configuring the root stack template

Once you have uploaded the files to S3, use root-stack-templates/placeos/deploy.yml to deploy PlaceOS. The required parameters are:

• BucketName S3 Bucket name where nested templates live

• CertificateId Certificate Identifier from AWS ACM - required for TLS/SSL

• EnvironmentName An environment name that is a suffix for resource names

• PLACEEMAIL Email address to login initially to the application

• PLACEPASSWORD Password to login initially to Backoffice

• PLACEUSERNAME Users Name

• PrivateSubnet1 Select a private subnet

• PrivateSubnet2 Select another private subnet

• PublicSubnet1 Select a public subnet

• PublicSubnet2 Select another public subnet

• VPC Select the VPC containing the public and private subnets

• VpcCIDR IP range (CIDR notation) for the VPC

AWS EnvironmentName parameter and Stack naming

The EnvironmentName parameter's uses include:

• Tagging

• Service discovery

• Linking outputs of templates with inputs of later templates

PlaceOS is the default but each deployment in the same VPC should configure its own EnvironmentName. The Stack name you choose for each component has no effect on the function of the deployment.

init: fargate/init-service.yml

Accessing the deployed PlaceOS Backoffice application

You can expect the deployment to take 20-30 minutes, most of which is Elasticsearch. The Backoffice application will be available at:

https://{Application_Load_Balancer_DNS_NAME}/login?continue=/backoffice

The credentials are the email and password set by the init service. You can also find the application URL listed as an output for the init nested stack.

The advantage of writing a script is that you can update multiple aspects of the system at once, ensure consistency and ideally allow running multiple times as data changes.

Once the Authentication Source is configured, we need to ensure PlaceOS Applications redirect the user to the authentication provider to login.

Prerequisites

• PlaceOS Backoffice Administrator Access

Procedure

1. Login to PlaceOS Backoffice

2. Navigate to the Domains tab.

3. Select the Domain for your organisation.

4. Click on the Edit icon.

Debugging

The first step in this process should be to get the raw request.

Often you can see if a request attribute is not lining up to an attribute statement by inspecting the XML.

There are two methods of getting SSO data, described below:

1. If you have an account you can use to test

2. If the client is logging in and you have access to logs

Self Check

1. Open the Chrome or Firefox inspection tool

2. Go to the network tab

3. Select: preserve log

4. Go through the login flow

The request coming back to the assertion URL is the one you want to inspect.

Assertion URL: /auth/adfs/callback?id=[ADFS-ID-HERE]

Copy and paste the SAML response into the SAML decoder.

Prerequisites

• PlaceOS BAckoffice Administrator Access

• client_id and secret obtained from Google.

Procedure

1. In PlaceOS Backoffice navigate to the Domains tab.

2. Select the domain you would like to add Microsoft Authentication to.

3. Click the Authentication Tab.

4. Identify the OAuth Source previously created.

5. Click the Edit Icon.

6. Update missing fields per the table below

Configuring fields

These fields are specific to the OAuth2 provider and tend to differ slightly between providers.

Details on how Google handles OAuth2 will be used to describe the following fields

• name: a friendly name for this authentication configuration

• client_id: the id provided by the OAuth2 provider when you added a new application

• client_secret: as above

• site: the URL of the application requesting access (https://poc.placeos.com in the screenshot above)

• scope: the scopes, space separated, for the APIs that are intended to be accessed

• token_method: POST or GET, Google uses a POST to obtain a token

• authentication_scheme: do we use request params or request body to obtain a token, Google uses the body

• token_url: the URL to obtain a token from, Googles is https://oauth2.googleapis.com/token

• authorize_url: this is the URL that initialises the OAuth2 request. Google details here.

• user_profile_url: the is is the URL we can use to test the OAuth2 token and obtain user details

• info_mappings: this maps PlaceOS fields to User Profile fields

• authorize_params: query params to pass along with the authorize URL

• ensure_matching: authorization response fields that should match

Google Example

An example configuration that works with Google

• scope: profile email

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

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

  • https://www.googleapis.com/auth/userinfo.email

• token method: POST

• Auth Scheme: Request Body

• Token URL: https://oauth2.googleapis.com/token

• Authorize URL: https://accounts.google.com/o/oauth2/auth

• User Profile URL: https://openidconnect.googleapis.com/v1/userinfo

• Info Mappings: (PlaceOS -> Google)

  • email -> email

  • first_name -> given_name

  • last_name -> family_name

  • uid -> sub

  • image -> picture

  • access_token -> token

  • refresh_token -> refresh_token

  • expires -> expires

  • expires_at -> expires_at

• Authorise Params

  • access_type -> offline (this will return a refresh token)

  • prompt -> consent (ensures we are always sent a new refresh token on login)

• Ensure Matching

  • hd -> my.google.apps.domain (typically the domain after the @ in your login name)

The above stores a refresh token against each user for scoped directory access. A simpler version if token based access isn't required could be:

The PlaceOS Calendar Driver connects to Microsoft Graph API (365) or Google Workspace.

The Calendar Driver and the Bookings Driver work together to get resource calendar events.

The Calendar Driver can also make ad-hoc bookings from kiosks or room booking panels.

Prerequisites

• Administrator access to your PlaceOS Backoffice

• PlaceOS Drivers Repository Configured in Backoffice

• Systems have a valid calendar resource address from Microsoft 365 or Google Workspace

Add Driver

Before we can use the PlaceOS Calendar Driver we must instantiate it as a driver.

1. Navigate to the Drivers tab

2. Click the + icon to add a new driver

3. Select PlaceOS Drivers Repository

4. Select the drivers > place > calendar.cr Driver Base

5. Select the latest commit

6. Click Save

Add to System

You need to instantiate a single instance of the PlaceOS Calendar Driver.

We recommend instantiating the driver in a generic system e.g. *Tracking.

That module is then added to each system that requires booking or calendar functionality.

Instantiate the Driver

1. Navigate to the system you will instantiate the driver in

2. Select the Modules tab

3. Click Add New
4. Search for the PlaceOS Calendar driver
5. Click Save

Configure Driver

The driver is now instantiated as a module, we need to configure the API Credentials.

1. Navigate to the Drivers tab

2. Select the Calendar Driver

3. In the Settings view select unencrypted tab

4. Delete all the example configuration provided by the driver

5. If using Google Calendar API, paste this configuration into the encrypted tab:

   Copy

   calendar_config:
         scopes:      ["https://www.googleapis.com/auth/calendar", "https://www.googleapis.com/auth/admin.directory.user.readonly"],
         domain:      "primary.domain.com", #Your Google Workspace Domain
         sub:         "default.service.account@google.com", # User or Service User Account
         issuer:      "placeos@organisation.iam.gserviceaccount.com", # client_id from the JSON
         signing_key: "PEM encoded private key" # private_key from the JSON

6. If using Office 365, paste this configuration into the encrypted tab:

   Copy

   calendar_config:
         tenant:          "",
         client_id:       "",
         client_secret:   "",
         conference_type: nil # This can be set to "teamsForBusiness" to add a Teams link to EVERY created Event

Add Module to Systems

You can now add the module to other systems as required.

1. Navigate to an existing system

2. Select the Modules tab

3. From the drop down, select the Calendar Module

4. Click Add Existing

Test Module

You can test by creating a booking or inspecting the state of the Calendar Driver.

Inspecting State should return a valid response.

This should return:

{
    "connected": true
}

You can also execute a function on the module and view the response.

As a test, executing the list_users function should return a list of users if connected properly.

MQTT messages consist of a header and a payload and typically have low bandwidth usage. The header declares the topic of the message, and the payload carries data as key-value pairs. PlaceOS uses two types of message sent over MQTT: State Changes and Metadata.

State Change

Changes to module state propagate in real time. All change messages share the following topic structure:

In this structure, each section is a unique identifying tag to represent part of the system.

• <org>: Organization ID

• <idx>: Module Index

• <state>: State Key

On a state change, the module will publish a message with the payload containing the new state value as a JSON entity. The associated driver defines the structure and frequency of this state change.

Some systems may not have a building, level, or area. If they generate a state change, the missing topic level will be an underscore character (_).

State Change Payload

The payload is the value of the status variable paired with a timestamp

Metadata

Metadata is available for building, level, area, system and driver tiers. The format is this persistent topic:

Metadata Payloads

Metadata payloads are JSON objects that contain model info for the publishing entity. This includes the human-readable "friendly name", e.g.

Wildcard Subscriptions

Wildcards can replace any topic level to catch state information across different services. Some common examples are:

All events within a building:

Connected status of all devices:

Power status for all displays:

Call status information for Cisco VC endpoints (dep-123 is the driver ID for Cisco VC):

Privacy

Some deployment requirements may include filtering of sensitive information. The system parses state changes for content such as email addresses or user IDs before they propagate. A match can lead to actions such as:

• Replacing the value with a hashed version of itself

• Masking the value

• Dropping the associated event

Cloud Brokers

PlaceOS can integrate with MQTT Brokers including the major service providers listed below.

*[MQTT]: Message Queuing Telemetry Transport *[VC]: Video Conferencing

Websocket MQTT API

PlaceOS provides an out of the box MQTT solution via the API, delivered over websockets using standard JWTs or X-API-keys for authentication.

Secure WSS available at the route /api/mqtt/ it expects the following MQTT authentication message details:

• Username: users JWT token or X-API-Key

• Password: users JWT token or X-API-Key

Regular users have read and subscribe permissions.

MQTT Clients

We've found the following clients useful

Example configuration for explorer

Overview

Backoffice supports uploading files to cloud storage for secure temporary access or public read. This is useful for device documentation, SVG Floor Maps or Room Photos.

Prerequisites

1. Configure your storage bucket on the cloud storage platform

2. Ensure CORS is enabled for the domain Backoffice will be uploading from

3. Note the storage bucket name

4. Generate access credentials for the storage bucket

Backoffice configuration

2. You can optionally configure a default storage solution or a per-domain one

3. Enter the bucket name and access keys, examples below:

Cloud configuration

S3 Configuration

You will find this under bucket permissions -> CORS configuration.

You will want to configure the access key with minimal permissions too:

1. In IAM, create a new user to act as the service account

2. Grant the user no permissions except S3 List, Read, Write, Object permissions management

3. Generate some access keys to use for signing upload requests

An example IAM user policy for file uploads:

If you don't want the user to have object permission management then you also override the bucket level policy, where all objects are public

Upload Files

Once the above configuration steps are completed, you should be able to upload files to PlaceOS.

To upload a file, drag and drop it into Backoffice in your browser.

The file upload status will be displayed.

Once the upload is complete, you can copy the file URL and use this as required.

:::tip The uploaded file will be given a discrete URL on the storage bucket, for example: https://s3-ap-southeast-2.amazonaws.com/bucket.name/directory.name/16221818379492128.svg. Characters will be automatically encoded, if present. :::

*[CORS]: Cross-Origin Resource Sharing *[IAM]: Identity & Access Management

PlaceOS Supports a range of authentication providers, both SAML and OAuth2 can be used for authentication.

This section lists configuration for some common authentication providers using SAML.

To configure PlaceOS for Microsoft 365 or Google Authentication, it is best to use OAuth2 detailed in these articles:

• Configure PlaceOS for Microsoft Azure/365.

• Configure PlaceOS for Google Workspace.

This section also provides instructions to configure X-API Keys and bearer tokens which can be used for interacting with the PlaceOS API.

Overview

This page assists with deploying PlaceOS on AWS using CloudFormation templates. From VPC configuration to a functioning application, it's all modular by design.

A CloudFormation template specifies all the components. Each component is designed to deploy as its own CloudFormation stack.

The configurable components and the templates used, in order of recommended steps, are:

• VPC vpc.yml

• Security Groups sec_groups.yml

• Elasticsearch elasticsearch.yml

• ElastiCache elasticache-redis-cluster.yml

• Application Load Balancer load-balancer-https.yaml

• Elastic File System EFS.yml

• Fargate Cluster ecs-cluster.yml

• RethinkDB rethinkdb-primary.yml

• etcd etcd-service.yml

• dispatch dispatch-service.yml

• NGINX nginx-service.yml

• Frontends frontends-service.yml

• Auth auth-service.yml

• Core core-service.yml

• triggers triggers-service.yml

• Rubber Soul rubber-soul-service.yml

• REST API rest-api-service.yml

• init init-service.yml

AWS EnvironmentName parameter and Stack naming

The EnvironmentName parameter's uses include:

• Tagging

• Service discovery

• Linking outputs of templates with inputs of later templates

For example, the RethinkDB service uses EFS shares for it's /data directory. To pick up the correct EFS share, the templates for EFS and RethinkDB must have the same EnvironmentName.

Use the same EnvironmentName variable throughout the deployment process. PlaceOS is the default but each deployment in the same VPC should configure its own EnvironmentName. The Stack name you choose for each component should be descriptive but has no effect on the function of the deployment.

VPC Architecture: vpc.yml

The VPC template deploys two private and two public subnets. For each of these, you can configure:

• CIDR ranges

• An internet gateway

• Two NAT gateways

• Routes and route tables

The application load balancer is the only component that should deploy in public subnets.

These values have presets, but you can specify any EnvironmentName and CIDR ranges you want.

Security Groups: sec_groups.yml

Once the VPC is available, use this template to configure all the AWS Security Groups for the remaining stacks. The stacks and services are on a serverless and managed architecture. Use security groups to prevent unnecessary communications between the application components.

Use the same EnvironmentName parameter as the VPC and select the VPC created in the previous step.

Elasticsearch (AWS Managed Service): elasticsearch.yml

After configuring the security groups, you can begin configuring the components that use them. By default, this template deploys an Elasticsearch cluster version with 2 instances of t2.small.Elasticsearch.

AWS tags which identify the associated components are:

Security Group

(Elasticsearch | {EnvironmentName} | security group).

Private Subnets

(Private Subnet 1 | {EnvironmentName}) (Private Subnet 2 | {EnvironmentName})

ElastiCache (AWS Managed Service): elasticache-redis-cluster.yml

By default, this template deploys an ElastiCache Redis cluster with Multi-AZ support. It comprises of one Node.js Group and two cache.t2.micro replicas as default. The Redis port, snapshot and maintenance window parameters have default values but are configurable.

Here you should use the security group with AWS tags

Security Group:

(ElastiCache | {EnvironmentName} | security group)

Subnets:

(Private Subnet 1 | {EnvironmentName}) (Private Subnet 2 | {EnvironmentName})

Application Load Balancer: load-balancer-https.yaml

This template deploys an external, public facing load balancer. It forwards public traffic to internal services.

The application load balancer is the only component that should deploy in public subnets. It requires you use your own preconfigured certificate from AWS Certificate Manager. It's configured with a certificate Identifier from ACM.

A Secure Listener serves HTTPS traffic. All inbound HTTP traffic redirects to its matching HTTPS.

Subnets:

(Public Subnet 1 | {EnvironmentName}) (Public Subnet 2 | {EnvironmentName})

VPC:

({EnvironmentName} | VPC)

Elastic File System: EFS.yml

As the application deployment consists of ephemeral containers, EFS is the persistent storage layer. RethinkDB, NGINX and Frontends services use the Elastic File System created by this template. EFS is the RethinkDB data directory. NGINX and Frontends us it for file storage of the Backoffice user interface.

Security Groups:

• SecurityGroupEFSNginxFrontends:

(NGINX and Frontends -> EFS | {EnvironmentName} | security group)

• SecurityGroupEFSRethinkDB:

(RethinkDB -> EFS | {EnvironmentName} | security group)

Subnets:

(Private Subnet 1 | {EnvironmentName}) (Private Subnet 2 | {EnvironmentName})

VPC:

({EnvironmentName} | VPC)

Fargate Cluster: ecs-cluster.yml

This template deploys the Elastic Container Service (ECS) cluster for all PlaceOS container services. The ECS Cluster configuration requires the same EnvironmentName parameter as prior steps.

Notes on deploying the Fargate services.

The Fargate components of the deployment still need configuration. They share a lot of common parameters. Each template configures and deploys an ECS Task Definition, Service and Task. You can configure the ECS parameters as required but the default values specified are okay for this example.

The ServiceName parameter configured will result in creation of a Service Discovery record as

{ServiceName}.{EnvironmentName}

For example, rethinkdb-primary.placeos would be the record for the RethinkDB template. All future services that need configuration with the database can use this value as an input parameter.

The security groups to use for each template will appear in the appropriate sections below. Tags for VPC and Private subnets are:

Subnets:

(Private Subnet 1 | {EnvironmentName}) (Private Subnet 2 | {EnvironmentName})

VPC:

({EnvironmentName} | VPC)

Configure the EnvironmentName parameter as in all previous steps.

RethinkDB rethinkdb-primary.yml

RethinkDB serves as the database for PlaceOS. RethinkDB can operate as a cluster but for the purposes of this example you will deploy a single primary member.

The RethinkDB /data directory uses an EFS share as created earlier by the Elastic File System stack. Data stored by the database will persist if the container task gets restarted or destroyed.

Service Discovery created:

{ServiceName}.{EnvironmentName}

E.g. rethinkdb-primary.placeos

Security Group:

(RethinkDB | {EnvironmentName} | security group)

etcd: etcd-service.yml

etcd is the service discovery layer for PlaceOS.

Service Discovery created:

{ServiceName}.{EnvironmentName}

E.g. etcd.placeos

Security Group:

(etcd | {EnvironmentName} | security group)

Dispatch: dispatch-service.yml

Dispatch allows drivers to register new servers to enable devices to connect to PlaceOS.

Service Discovery created::

{ServiceName}.{EnvironmentName}

E.g. dispatch.placeos

Security Group:

(Dispatch | {EnvironmentName} | security group)

NGINX: nginx-service.yml

NGINX is the web server for PlaceOS. See more on our implementation here

Service Discovery created:

{ServiceName}.{EnvironmentName}

E.g. nginx.placeos

Security Group:

(NGINX | {EnvironmentName} | security group)

Frontends: frontends-service.yml

Frontends is a sidecar to the web server. It listens for published frontend repositories and clones them to the NGINX static folder on EFS.

Required Services:

• RethinkDB

Service Discovery created:

{ServiceName}.{EnvironmentName}

E.g. frontends.placeos

Security Group:

(Frontends | {EnvironmentName} | security group)

Auth: auth-service.yml

Auth provides the authentication service and API gatekeeper.

This service references the ElastiCache cluster configured earlier. Configure the Primary Endpoint from Redis here. The RedisURL parameter will have the form redis://{Primary Endpoint}:{port}

Required Services:

• Redis

• RethinkDB

Service Discovery created::

{ServiceName}.{EnvironmentName}

E.g. auth.placeos

Security Group:

(Auth | {EnvironmentName} | security group)

Core: core-service.yml

Core is the coordination service for running drivers on PlaceOS.

Required Services:

• Redis

• RethinkDB

• etcd

Service Discovery created:

{ServiceName}.{EnvironmentName}

E.g. core.placeos

Security Group:

(Core | {EnvironmentName} | security group)

Triggers: triggers-service.yml

Triggers is the PlaceOS service for handling events and conditional triggers.

Required Services:

• Redis

• RethinkDB

• etcd

Service Discovery created:

{ServiceName}.{EnvironmentName}

E.g. triggers.placeos

Security Group:

(Triggers | {EnvironmentName} | security group)

Rubber Soul: rubber-soul-service.yml

Rubber Soul is a service that connects to rethinkdb-orm models and generates Elasticsearch indices.

This service references the Elasticsearch cluster configured earlier. Configure the ESURI with the Elasticsearch VPC Endpoint which will have the form https://xxxxxx...es.amazonaws.com.

Required Services:

• Elasticsearch

• RethinkDB

Service Discovery created::

{ServiceName}.{EnvironmentName}

E.g. rubber-soul.placeos

Security Group:

(Rubber Soul | {EnvironmentName} | security group)

REST API: rest-api-service.yml {REST-API}

This template configures and deploys the REST API ECS Task Definition, Service and Task. REST API is an API service for interacting with PlaceOS.

Required Services:

• Elasticsearch

• RethinkDB

• Redis

• etcd

• Frontends

• Rubber Soul

• Triggers

Service Discovery created::

{ServiceName}.{EnvironmentName}

E.g. rest-api.placeos

Security Group:

(Rest-api | {EnvironmentName} | security group)

init: init-service.yml

init initializes the PlaceOS instance and is the final step in the deployment. This service requires the DNS Name of the ALB as it's the URL for accessing the application. The email and password configured here will also create a login you can use once you deploy the application.

Required Services:

• RethinkDB

• Auth

• Application Load Balancer {DNS Name}

Service Discovery created::

{ServiceName}.{EnvironmentName}

E.g. init.placeos

Security Group:

(init | {EnvironmentName} | security group)

Accessing the deployed PlaceOS Backoffice application

Once you have completed the above steps, the Backoffice application will be available at:

https://[Application_Load_Balancer_DNS_NAME]/login?continue=/backoffice

The credentials are the email and password set by the init service.

To use Azure B2C with PlaceOS you will need to configure a Custom Policy Framework, using the existing User Flows provided by Azure B2C is not sufficient for use with OAuth2 as it does not provide a User Info endpoint.

Without a User Info endpoint, PlaceOS is unable to correctly create the user record in our users table.

Create Custom Policy

The first step in configuration is to create a custom policy framework and the supporting application registrations.

Microsoft have prepared extensive documentation to complete this process and we recommend following this documentation to complete this step: Microsoft Azure B2C - Create Custom Policy Framework

To complete this step, you will also require the Custom Policy Provider templates.

Download the Custom Policy Templates from Github or git clone https://github.com/Azure-Samples/active-directory-b2c-custom-policy-starterpack

Add User Info Endpoint

To allow PlaceOS to obtain your users information from Azure B2C via the Graph API, you will need to modify the custom policy to support a User Info endpoint.

Microsoft have prepared extensive documentation to complete this process and we recommend following this documentation to complete this step: Microsoft Azure B2C - Add User Info Endpoint to Custom Policies

Add Custom User Attributes

You may also opt to collect additional data from your users when they sign up to the application, these are referred to as Custom User Attributes.

Custom User Attributes may include additional information such as:

• Users phone number

• Address

• Company

• Department

This information will be stored against the user record in the Azure B2C Directory and can be claimed by PlaceOS where required.

Microsoft have prepared extensive documentation to add Custom User Attributes to your B2C Custom Policy, we recommend following this documentation to complete this step: Microsoft Azure B2C - Add Custom User Attributes

Password Reset Policy

By default, the self serve password reset user flow is not enabled.

You will need to add a custom user sub-journey to your policy to enable self serve password reset facilities, to do this you can follow this guide by Microsoft: Microsoft Azure B2C - Add Password Reset Journey

Examples

We have provided an example Custom User Policy that includes:

• Local user sign-up/sign-in i.e. using a email address and password.

• User Info endpoint enabled.

• Custom User Attributes added.

You can download our example policies from Github or git clone git@github.com:place-labs/azure-b2c-custom-policy-sample.git

Where sensors are installed, the Sensor Management User Interface provides an interface to plot the sensors on the floor map.

This will enable custom zone capacity and enhanced capacity reporting via the zones.

The Sensor Management User Interface is able to plot the following types of sensors:

Prerequisites

• Administrator access to your PlaceOS Backoffice

• A Valid Org, Building and Zone Configuration

Enable the Sensor Extension

The first step is to enable the sensor extension.

1. In PlaceOS Backoffice Navigate to the Admin Tab

4. Configure the new extension as below:

• Type: zones

• Name: Sensors

• URL: https://editor.place.tech/sensor-map/#/editor/{{map_id}}

1. Click Add Condition and add the following condition:

• Condition Field: map_id

The Extension is now enabled.

Using The Sensor Manager

Once enabled, you can place sensors on the floor maps of Level Zones.

1. Navigate to Zones and select a zone with a tag of level

You will now be able to select sensors from the list and place them according to their physical location on the map.

Azure B2C (Business to Consumer) is an authentication service provided by Microsoft designed to enable any users to register and authenticate against a web application.

Azure B2C may be used with PlaceOS where the organisation wish to provide external access to users not part of their organisation, this is commonly used for shared working or co-working spaces.

Under this configuration, Azure B2C is configured and added to PlaceOS as a OAuth2 Provider.

To use Azure B2C, you will require:

• An active Azure Tenant

• An Azure Subscription with valid payment method

• Administrator Access to an Azure B2C Tenant and/or sufficient access to create and deploy the Azure B2C Tenant from your existing tenant.

These instructions will assume you are able to configure an Azure B2C Tenant under your existing tenant and will only cover the specific requirements for PlaceOS Configuration.

There are two steps to this process:

1. Create Azure B2C Custom Policy Framework in your Azure B2C Tenant

2. Configure PlaceOS Authentication Source & Azure App Registration

Overview

This guide will step through the process of creating a domain and the associated application(s) that will exist on it.

You must create a domain before adding authentication sources (such as SAML) to it.

Prerequisites

1. PlaceOS has been deployed

2. You know the domain(s) required for the deployment and the applications on them

Step 1: Create the New Domain

1. Log in to Backoffice on the domain created during deployment and select the Domains tab

2. Select the + button to bring up the New Domain form

3. Add the following fields:

   • Name: Can be anything to identify the domain, like the domain itself i.e. placeos.domain.com

   • Domain: The actual domain, without a protocol i.e. placeos.domain.com

   • Login URL: The URL redirected to when a user logs in

     • You should usually set this to /login?continue={{url}}

   • Logout URL: The URL redirected to when a user logs out

     • You should usually set this to /auth/logout

Step 2: Add an Application to the Domain

1. Select the Applications tab

2. Choose New Application

3. Add the following fields:

   • Name: Can be anything to identify the applications

     • Usually the folder path where the application resides but capitalized i.e. Backoffice

   • Scopes: Leave this blank

   • Skip Authorizaiton: Check the box to set this to true

   • Login URL: The location that users are redirected to after completing authentication

     • This will generally be something like https://<domain>/<application path>/oauth-resp.html

Step 3: Add a User to the Domain

1. Select the Users tab

2. Select the New User button

3. Add or select the following fields:

   • Domain: Select the domain you created in Step 1

   • First Name: Add the first name of the user, this is required

   • Last Name: Add the last name of the user, this is required

   • Email: This will be the username and is required

   • System Admin: Denotes whether the user will be an admin (and thus can access and make changes in Backoffice)

     • This will usually be set to true when creating users in this interface

   • Password and Confirm Password: Enter the password which the user will use to login (when not using SSO)

You can now login with this new user on the domain created.

Webhooks are defined as a condition of a trigger. Add a new trigger that represents the webhook.

• Supported methods are the HTTP Verbs that should be accepted by the webhook URI

• The debounce period can be used to prevent multiple triggers occurring over a short period of time. (in seconds)

Once configured this trigger needs to be applied to a system before it's active.

Once you've added the trigger, you can obtain the webhook URL by clicking the link icon

The webhook URL

The webhook URL will look something like:

https://my.placeos.domain/api/engine/v2/webhook/trig-DHgkU1~p/notify?secret=kfwu5WYc3a1su

Webhooks that map to module functions

If this webhook is intended to provide data to modules in the system, not just as a condition to execute the trigger actions, then it needs a little more configuration.

1. in the System trigger list, click the edit button

2. ensure execute enabled is selected

3. click save

You will have to be aware of the methods that support Webhooks, which might involve looking at the driver code or driver documentation. Examples of webhook methods

• Meraki Dashboard

• Rhombus Interop

To build the execute URL you'll need the following information:

• Module name, i.e. Display

• Module index, i.e. 1, 2, 3 (Display_2 is index 2)

• Module method name: i.e. request

Then you can update the Webhook URL from above with this information

/api/engine/v2/webhook/trig-DHgkU1~p/notify?secret=kfwu5WYc3a1suZ&exec=true&mod=Display&index=2&method=request

An alternative form of this URL is (note that the secret is part of the route)

/api/engine/v2/webhook/trig-DHgkU1~p/notify/kfwu5WYc3a1suZ/Display/2/request

This URL can then be used to pass HTTP data to the module and should be provided to the service that uses websockets.

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.

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.

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.

Create Azure App

1. Navigate to the Azure Portal

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

3. Navigate to App Registrations

4. Select New Registration

5. Enter the required information

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

   • Optionally paste the PlaceOS Assertion URL
6. 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

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

For further information see Creating and Managing Service Accounts.

Configure Google Cloud API Project

1. Go to Google Cloud Console

4. Select Enable APIs and Services

5. Search for and enable the following SDK:

   • Admin SDK (for staff directory)

   • Google Calendar API

   • Google Drive API (for attachments)

6. 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
3. Create a new Service Account
4. You can ignore the next steps in the wizard, click Done to return to the list of service accounts

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

8. Click Save

Configure Service Account Permissions

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

2. Copy the client_id
3. Navigate to Google Workspace Admin

4. Select Security

5. Scroll down to API Controls

6. Select Manage Domain Wide Delegation

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

8. Add the following API Scopes:

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

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

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

11. Select Trust internal, domain owned apps

Creating a Marketplace Application

1. On Google Cloud Console navigate to the API Services Dashboard

3. Select the Configuration tab
5. Upload icons as required

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

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

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

10. Once completed, return to the marketplace application form

11. Ensure you set visibility to My Domain
12. 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.

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

8. Save

Test Staff API Configuration

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

As Azure B2C does not explicitly provide us access to end user calendars, or a tenant for room resources you may optionally configure a 365 Tenant to be used for room booking/reservations.

Once Calendar Access has been configured, you will need to configure room resources to accept external meeting requests, this is done via PowerShell:

For example:

By default, PlaceOS uses local authentication. An admin account is generated upon initial deployment. The administrator can manually create user accounts in Backoffice (on the Users tab). We recommend switching to federated authentication.

Prerequisites

1. Confirm the final UAT and PROD URLs of the web apps

2. Ensure that the DNS entries for these URLs are active and forwarding to the server(s)

3. Ensure that the SSL certificates for the above domains are signed and recognized as secure

Step 1: Adding Authentication

1. Login as an admin to Backoffice

2. On the Domains tab, select the Domain that represents the URL where you wish to enable SAML

3. In the Authentication section click Add new

This will open up the SAML form. Here is a description of each field:

• Name: generic field for identifying the SSO

• Issuer (Identifier / Entity ID): this is what the SSO will use to identify this SSO integration

  • Can be anything, typically use the DNS entry i.e. staffapp.company.com

  • Azure will be in the format: spn:**client-id** - "Application (client) ID" can be found on the Overview page of your App Registration

  • OKTA will need the Issuer to be configured in the OKTA Application to match the value set here

• IDP target URL: This is the URL where SSO will occur - the login page

  • You can often guess it, but you can set it to any valid URL and change it later

  • Request this URL when sending the metadata URL

  • Azure AD URLs are often in the format: https://login.microsoftonline.com/**tenant-ID**/saml2

  • OKTA URLs are often in the format: https://**okta.domain.com**/app/**app-name**/**app-id-number**/sso/saml

  • AD FS URLs are often in the format: https://adfs.myorganistaion.com/adfs/ls

  • Auth0 URLs are often in the format: https://myorganisation.auth0.com/samlp/

• Name Identifier Format: the format of the response data

  • Set to urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

• Request Attributes: these are the Active Directory fields requested to be sent to us

  • Typically leave this blank on first save, and it will fill in the default value

  • Clients sometimes request you change these to match their system

  • Example:
• Assertion URL (Reply URL / Callback URL): the PlaceOS URL that SSO sends data back to - to log someone in

  • First set this to the base domain of the application. After saving this configuration for the first time, it will generate an ID (adfs_strat-XXXXXX)

  • See the image below and use the generated unique ID to build the Assertion URL

• Certificate Fingerprint / Full Certificate: used for verifying a signed login request

  • Not required until after SSO configuration on the client-side

• UUID Attribute: allows you to override the default unique ID returned by SSO to one of the requested attributes

• Attribute Statements: This maps requested attributes to database fields

  • Typically leave this blank on first save, and it will fill in the default value

  • Example: