Features

Currently, the integration provides the following major features:

  1. Provide end users the ability to schedule a collaboration meeting with any calendar client that is connected to Google’s G Suite Calendar (Google Calendar) without having to install plug-ins or extensions. Just type a keyword into the Location field (for example, @webex or @meet).

  2. Show a meetings list to users in the Webex App app (desktop and mobile) and on physical endpoints.

  3. Pop up a notification with a Join button, also known as One Button to Push (OBTP).

  4. Update a user’s Webex App presence status when the user turns on the vacation responder in Gmail (sometimes referred to as out-of-office status).

This article gives an overview of how the cloud-based Hybrid Calendar Service integrates Google Calendar with the Webex cloud to provide these features.

For similar overviews of the other Hybrid Calendar Service integrations, see the following articles:

For the latest feature and deployment information, see https://www.cisco.com/go/hybrid-services-calendar.

Data handling

The Calendar Service receives meeting details from the calendar system and parses the meeting location and body for URIs and URLs that can be used to join the meetings. The service uses other information, such as start and end time and invitees, to populate the meetings list in the Webex App app and on certain devices, and to provide One Button to Push (OBTP). At no point does the service store or send unencrypted sensitive data such as meeting description, meeting body, or email addresses of invitees. That data is sent encrypted to the Webex cloud (and stored there in encrypted form) for the purposes of providing the meetings list and OBTP.

For data encryption, the Calendar Service uses the same Webex cloud encryption service that the Webex App app uses. As such, key management is provided either by the cloud Key Management Server (KMS), or, if you choose to deploy Hybrid Data Security, by your own on-premises KMS. (For more details, see the Webex App Security Paper.)

Authentication and authorization during deployment

The Calendar Service uses the OAuth 2.0 client credentials grant flow to the Google Authorization Server.

Application authentication process

The Calendar Service is registered as an application with Google. As such, it uses a service account with domain-wide delegation to avoid the need for user consent. (For additional details, see https://developers.google.com/identity/protocols/OAuth2ServiceAccount.)

The Calendar Service must have the following application permissions:

Permission

Usage

Manage user calendars

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

  • Update the meeting text with the join details.

  • Determine the user's language for localization purposes.

Manage basic mail settings

https://www.googleapis.com/auth/gmail.settings.basic
  • Read out-of-office status.

In Control Hub, only administrators with privileged access can provision a customer's organization for the Calendar Service. An administrator must copy and paste the client ID and authorization scopes from Control Hub to the Manage API client access section of the Google G Suite domain's Admin console.

The flow includes the following high-level steps:

  1. Using the service account credentials, the application obtains user-level access tokens from the Google Authorization Server to get access to users' calendars.

  2. The application uses the access token in Google Calendar API calls, to get access to Calendar information.

Provisioning process

Activating users for Calendar access

After successfully provisioning the Hybrid Calendar Service as a registered application, the administrator must explicitly activate users to allow the service to access their respective G suite calendars.

To successfully activate a user for calendar access, the following conditions must be met:

  • The user's email address in Control Hub must match their Google calendar account in the organization's Google G Suite tenant.

  • The administrator must have verified the domain in the user's email address, OR the user needs to have verified their email address by successfully signing into Webex App.

Activating a user notifies the Hybrid Calendar Service to validate that it has the correct permissions to access the user's calendar in G Suite.

Successful validation is a requirement for using the Hybrid Calendar Service functionality. If the service can't validate a user, it puts the user in error state. The service enforces a policy to access only the calendars of successfully activated users for ongoing processing.

Ongoing operations

The Calendar Service uses the Google Calendar REST API. This API supports a broad range of operations with Google Calendar. However, the Calendar Service only uses a subset of commands that are related to calendar use cases.

Table 1. Operations currently used by Hybrid Calendar Service

REST API

Usage

GET calendars/{calendarId}/events

List of calendar events.

GET calendars/{calendarId}/events/{eventId}/instances

Instances of the specified recurring event.

GET /calendars/{calendarId}/events/{eventId}

Information on a single event in a calendar.

PATCH /calendars/{calendarId}/events/{eventId}

Update properties of calendar events (including join information and extended properties). This operation is also used to set accept/decline/tentatively-accept the status of a meeting.

POST /calendars/{calendarId}/events/quickAdd

Creates an event based on a simple text string.

POST /calendars/{calendarId}/events/watch

Subscribe for notifications on changes to a user's calendar.

POST /channels/stop

Unsubscribe from notifications on changes to a user's calendar.

GET /users/me/settings/{setting}

Retrieve the user's locale.

GET /users/{userId}/settings/vacation

Gets the user's vacation responder settings.

POST /calendars/{calendarId}/acl

Creates an access control rule.

DELETE /calendars/{calendarId}/acl

Deletes an access control rule.

POST /calendars/{calendarId}/events

Creates an event in the calendar.

DELETE /calendars/{calendarId}/events/{eventId}

Deletes an event from the calendar.

GET /freeBusy

Displays the user availability and free/busy status for a specified time range.