Configuring Google Workspace for One-Touch Join

This topic describes how to configure Google Workspace in order to implement Pexip Infinity's One-Touch Join feature in a Google Workspace environment.

The process involves the following steps, described in more detail in the sections that follow:

  1. Creating a Service Account to use for One-Touch Join.
  2. Creating a room resource for each physical room that will have a One-Touch Join endpoint in it.
  3. Configuring the room resource with the necessary permissions and settings to support One-Touch Join.
  4. Updating the quota for the number of user requests per 100 seconds.
  5. For larger deployments, Requesting an increase to API limits.
  6. Adding a One-Touch Join Google Workspace integration on Pexip Infinity.

If you have already set up a One-Touch Join Google Workspace integration and simply wish to add an existing room to it, you need only configure the room resource in Google Workspace and then add the endpoint to the Google Workspace integration in Pexip Infinity.

We recommend that you authorize One-Touch Join to access calendar information using a service account, as described in the following steps. This method (sometimes referred to as two-legged OAuth) offers the easiest setup for One-Touch Join, and is recommend by Google because it is designed for server-to-server applications (for more information, see https://developers.google.com/identity/protocols/oauth2/service-account). Alternatively, you may need to use a Google Workspace domain user for authorization (sometimes refered to as three-legged OAuth); for instructions on how to do this, see Configuring Google Workspace for domain user authorization.

Prerequisites

In the deployment model described below, the service account will require access to the endpoints' calendars. Google Workspace service accounts always use the iam.gserviceaccount.com domain rather than your own domain, so you will need to configure Google Workspace to allow endpoint calendars to be shared externally. This does not in itself allow any external accounts to access the calendars — each calendar must then also explicitly nominate the accounts with whom it is to be shared.

Some enterprises will require internal approval for this configuration, so you should confirm that it will be permitted within your deployment. If not, you can consider Configuring Google Workspace for domain user authorization as an alternative.

In this step, you create a project to use for One-Touch Join. You then create the service account that One-Touch Join will use to access the room resources' calendars, and generate a private key that One-Touch Join will use to authenticate when signing in to Google Workspace as the service account.

The service account belongs to the project you have created for OTJ. It can be used for multiple One-Touch JoinGoogle Workspace integrations.

  1. Creating a new project:
    1. Go to https://console.developers.google.com (logged in as a Google Workspace administrator).

    2. From the top left of the page, select the down arrow:

    3. Select New Project.
    4. Enter a Project name (e.g. One-Touch Join) and select Create.
  2. Enabling the Calendar API for the project:
    1. Go to https://console.developers.google.com

    2. From the top left of the page, select the down arrow, select your newly-created project, and select Open. Your new project should now be showing at the top left of the page:

    3. From the navigation menu on the left of the screen, select APIs & Services > Library, then scroll down and select the Google Calendar API tile:

    4. Select Enable:

  3. Creating the service account:
    1. Go to https://console.developers.google.com

    2. From the navigation menu on the left of the screen, select IAM & admin > Service accounts.

    3. Select Create Service Account:

    4. Enter a name (e.g. One-Touch Join Calendar Reader) and select Create:

    5. On the next page, which asks about permissions, select Cancel (the account does not need any of these permissions):

  4. Generating a key file:

    1. From the Service accounts page, select the service account.

      Take note of the service account's Email address here - you will need it in later steps:

    2. From the Service account details page, select Edit, then Create Key:

    3. Select a Key type of JSON and select Create:

    This will download a JSON file containing the private key. This key will be required when Adding a One-Touch JoinGoogle Workspace integration.

For more information on using OAuth 2.0 to authenticate the service account, see https://developers.google.com/identity/protocols/OAuth2ServiceAccount.

(Required only if your room resources do not already exist - otherwise you can skip this step.)

In this step, you create a room resource in Google Workspace for each physical room that is to be used for One-Touch Join. Google Workspace will automatically assign an email address to the room.

  1. If a building for the room resource does not already exist, create one as follows:

    1. Go to https://admin.google.com (logged in as a Google Workspace administrator).

    2. Select the Buildings and resources tile, and then from the Resource management section select Open:

      From the drop-down along the top left of the screen, select Buildings:

    3. Select + to Add new building:

    4. Enter a Name and the list of Floors, and select Add Building.

  2. Create the room resource:

    1. Go back to the Resources page and Select + to Add new resource:

    2. For the Category, select Meeting space (room, phone booth,...).

    3. Select the Building and Floor in which the room is located, enter a Name and the room's Capacity, then select Add Resource:

The resource will be created and added to the list. You can click on the new resource to view information about it, such as the email address it was automatically assigned.

For more information on setting up buildings and other resources in Google Workspace, including how to add buildings and resource in bulk and using CSV imports, see https://support.google.com/a/answer/1033925.

In these steps, you permit the One-Touch Join service account to access the calendar of each room resource that you want to use for One-Touch Join, and then set the calendar to auto-accept invitations. We also recommend that you make the calendar available to all users in your domain in such a way that allows them to book meetings using the resource, without being able to view the details of any other meetings in the resource's calendar.

Sharing calendars externally

In this step, you configure Google Workspace to permit endpoint calendars within your domain to be shared externally. This permission is required because the service account uses the external iam.gserviceaccount.com domain and is therefore considered an "outsider". Granting this permission does not in itself allow any external accounts to access the calendars — each calendar must then be shared with the service account. For more information, see Prerequisites.

To enable calendars to be shared externally:

  1. Go to https://admin.google.com/ (logged in as a Google Workspace administrator) and select Apps > Google Workspace > Calendar.

  2. In the Sharing settings section, ensure that External sharing options for primary calendars is set to Share all information, and outsiders can change calendars:

  3. In the General Settings section, under External sharing options for secondary calendars, select Share all information, and outsiders can change calendars:

    4. Selecting these options to ... and outsiders can change calendars will enable users to use One-Touch Join to join all meetings, including private meetings. If you will not be using One-Touch Join with private meetings in your deployment, both these options can be set to ... but outsiders cannot change calendars.

Sharing individual calendars with the service account

Note that the Google calendar API limits the number of calendars that can be shared within a 24 hour period to 750 (for more information, see this Google article). This means that if you have more than 750 room resources that you wish to use for OTJ, they will need to be set up over a period of days.

For deployments with more than around 50 rooms, we have developed a Python script that can be used to share your room resource calendars with the service account, and create a CSV that can be used to import endpoint configuration to One-Touch Join. You must be familiar with Python in order to use this script; contact your Pexip authorized support representative for more information.

To share calendars with the service account:

  1. Go to https://calendar.google.com (logged in as a Google Workspace administrator so that you have permission to share the calendars).
  2. From the left-hand panel, select the + next to Other calendars and then select Browse resources.

  3. Expand the sections if necessary, and tick the boxes of all the room resources whose calendars you want to share with the service account.

    This will add the room resources to the Settings for other calendars section in the left-hand panel.

  4. For each of the rooms:

    1. From the Settings for my calendars section, select the room resource and then select Share with specific people.
    2. Select Add people.

    3. In the Share with specific people dialog, enter the email address of the One-Touch Join service account. Ensure the Permissions are set to either:

      • Make changes to events (if you want users to be able to use OTJ to join all meetings, including private meetings, from this endpoint)
      • See all event details (if you don't want to offer OTJ for private meetings on this endpoint).

      If the option to Make changes to events is grayed out, then check that you have selected the options to Share all information, and outsiders can change calendars when Sharing calendars externally.

      4. If your deployment includes personal endpoints that are associated with a user's personal calendar, then either you or the end user will need to ensure that their calendar allows the One-Touch Join service account to Make changes to events if they wish to use OTJ to join their own private meetings from their endpoint.

For more information on sharing room and resource calendars in Google Workspace, see https://support.google.com/a/answer/1034381.

Auto-accepting invitations

By default, when creating room resources in Google Workspace, calendar processing is set to Auto-accept invitations that do not conflict. You must ensure you keep this setting for all room resources, so that the room will automatically accept meeting requests if it is available, and automatically decline an invitation if it is already booked.

To check this setting:

  1. Go to https://calendar.google.com (logged in as a Google Workspace administrator so that you have permission to share the calendars).
  2. From the left-hand panel, select the room resource and select Settings and sharing.

  3. In the Auto-accept invitations section, ensure that Auto-accept invitations that do not conflict is selected:

Allowing users to book resources

We recommend that you configure your Google Workspace calendar settings to allow end users to book a room resource without seeing details of the room's other bookings. To do this, you configure the room resource's calendar so that all users in your domain have permission to see its free/busy status, without being able to see the invitation details. You then on a global basis permit users to book resources to which they have free/busy access.

To do this:

  1. Go to https://calendar.google.com (logged in as a Google Workspace administrator so that you have permission to share the calendars).
  2. From the left-hand panel, select the room resource and select Settings and sharing.

  3. In the Access permissions section, select Make available for <your domain>, and ensure that See only free/busy (hide details) is selected:

  4. Go to admin.google.com (logged in as a Google Workspace administrator).
  5. From the left-hand menu, select Apps > Google Workspace > Calendar.
  6. Scroll down to General settings and select Resource booking permissions.

  7. Ensure that Allow users to book resources that are shared as See only free/busy is set to ON:

In this step you increase the limit on the number of queries per 100 seconds per user to the Google Calendar API.

The default number of queries per 100 seconds per user is 500. In this context, the "user" is the service account. In deployments with fewer than around 180 rooms, each room resource calendar is queried every 30 seconds by two conferencing nodes (both using the same service account), resulting in 5,760 queries per room per day. (In larger deployments, room resource calendars are queried less frequently.)

We recommend that you increase the number of queries per 100 seconds per user to 10,000 to provide sufficient processing overhead and room for expansion (there is currently no additional cost to this increase).

To increase this quota to 10,000:

  1. Go to https://console.developers.google.com (logged in as a Google Workspace administrator).

  2. From the top left of the page, select the project you created for One-Touch Join:

  3. From the navigation menu at the top left of the page, select IAM & admin > Quotas.

  4. From the Quotas page, select Edit Quotas and then select Google Calendar API - Queries per 100 seconds per user.

    You will be taken to the Google Calendar API > Quotas page.

  5. Change Queries per 100 seconds per user to 10,000:

    You may also need to request an increase to the number of Queries per day for larger deployments - for more information, see Requesting an increase to API limits.

This optional step applies to larger deployments only (more than around 170 room resources), and should be performed if you wish to reduce the amount of time taken for endpoints to be updated with additions or changes to their corresponding room resource calendar.

The maximum frequency with which an endpoint will be updated with meeting information is every 30 seconds. For deployments with more than around 170 endpoints, this frequency will decrease in line with the number of endpoints (up to around 20 minutes for deployments with around 6,000 endpoints). This is due to a limit on the number of Calendar API requests permitted by Google in a 24-hour period — for more information, see https://developers.google.com/calendar/pricing.

To reduce the time taken to update endpoints in these larger deployments, you can request an increase to the number of Calendar API requests One-Touch Join can make.

When your request has been implemented by Google, you must then increase the Maximum Google Workspace API requests on Pexip Infinity in order to take advantage of the increase.

To request an increase to the API limits:

  1. If you do not already have one, create a Cloud Billing Account (note that this is different from a Google Workspace billing account).

    Full instructions are available via https://cloud.google.com/billing/docs/how-to/manage-billing-account#create_a_new_billing_account.

  2. Link the Cloud Billing Account to the project you created when Creating a service account:

    1. Go to https://console.developers.google.com (logged in as a Google Workspace administrator).
    2. Ensure that the project shown in the top left corner is the one you created for One-Touch Join when Creating a service account.

    3. Select the burger menu from the top left of the page and select Billing. When the following message appears, select Link a billing account:

    4. Select the account to link to:

  3. Request an increase to your quota:

    1. From the navigation menu at the top left of the page, select IAM & admin > Quotas.

    2. From the Quotas page, select Edit Quotas and then select Google Calendar API.

      In the panel that appears on the right, enter the New quota limit that you wish to request, and in the Request description field, enter the reason for requesting the increase:

    3. Select Submit request.

Quota increase requests typically take two business days to process.

In this step you configure Pexip Infinity with details of the Google Workspace deployment configured above, including details of the service account used to access calendars.

From the Pexip Infinity Administrator interface, go to One-Touch Join > OTJ Google Workspace integrations.

Option Description
Name The name of this One-Touch JoinGoogle Workspace integration.
Description An optional description of this One-Touch JoinGoogle Workspace integration.
Account email

If you are authorizing using a service account, enter the email address of the service account that One-Touch Join will use to log in to Google Workspace.

If you are authorizing using a Google Workspace domain user, enter the email address of the user.
Enable user authorization

If you are authorizing using a service account — the recommended method — this should be left blank.

Select this option only if you will be authorizing using a Google Workspace domain user.
Private key

(Available when authorizing using a service account, i.e. user consent authorization has not been enabled)

The private key used by One-Touch Join to authenticate the service account when logging in to Google Workspace. For instructions on how to obtain this, see Generating a key file.

This must include all the text in the file between (and including) -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY-----
Advanced options
Maximum Google Workspace API requests

The maximum number of API requests that can be made by One-Touch Join to your Google Workspace Domain in a 24-hour period.

We recommend you set this value to 90% of your total permitted requests. Google's default is 1,000,000 so by default this is set to 900,000 on Pexip Infinity. If you increase the number of API requests, you should also increase this setting to 90% of that number.

For more information, see Frequency of and limitations on calendar requests.
Google OAuth 2.0 endpoint The URI of the Google OAuth 2.0 endpoint.
Google authorization server The URI of the Google authorization server.

Next steps

You must now configure the remainder of the One-Touch Join components on Pexip Infinity, as described in Configuring Pexip Infinity for One-Touch Join.