Enterprise Conferencing ^BETA

Table of contents #

• Background
• Prerequisites
• Creating an Organizational Unit link token
• Organizational Unit OAuth authorization
• Future usage

Background #

We have introduced a mechanism to authorize enterprise conferencing services like Zoom and Webex at an Organizational Unit level. This allows multiple accounts to use an enterprise’s conferencing provider after a single administrator has set it up, without each account having to authorize independently.

This can be considered as an extension of the existing Enterprise Connect model for connecting calendars. The reason the model differs is that for the functionality to work, we need an entity through which to associate the two enterprise-level connections, eg. calendars and conferencing services, in order to correlate the two.

We have introduced the concept of Organizational Units for this purpose.

Throughout the examples in this document, we have used Zoom as an example of an enterprise conferencing provider. Authorizing other providers, like Webex, are supported by the same approach.

Prerequisites #

We will start with the assumption that your application already has access to a calendar service account through Enterprise Connect.

From this state, an Organizational Unit authorization will be initiated with:

1. A token generated to require the authorization process include the previously authorized calendar service account
2. A query string parameter instructing Cronofy that the process must also authorize an enterprise-level Zoom connection

The administrator will then go through a process where:

1. They prove they have administrative access to the existing calendar service account (if necessary)
2. They authorize permission for Cronofy to generate conferencing details for any user or room within their Zoom account
3. They approve the association of the two entities via a new or existing Organizational Unit within Cronofy
4. They are returned to the originating application with a code for gaining tokens for an authorization to the Organizational Unit (optional but recommended)

Creating an Organizational Unit link token #

Gives the integrating application a way to provide a single-use token that seeds the authorization flow with constraints.

For example, requiring a previously authorized calendar service account is used within the Organizational Unit authorization flow as relevant.

This is the example we will document here.

Example request #

POST /v1/organizational_unit_authorization_link_tokens HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {API_KEY}
Content-Type: application/json

{
  "service_account_id": "ser_64b17f9b8090ea21640c9151"
}

Request parameters #

API_KEY required  #

The client_secret of the client.

service_account required  #

A String sub value for a service account already authorized for the OAuth client.

Example response #

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "organizational_unit_authorization_link_token": {
    "ou_link_token": "{random_string}"
  }
}

Response parameters #

organizational_unit_authorization_link_token.ou_link_token  #

A short-lived String token to be passed as a querystring parameter to an Organizational Unit OAuth authorization flow.

Organizational Unit OAuth authorization #

To establish a link between a calendar service account and a Zoom account-level connection, an administrator from the organization needs to pass through an OAuth authorization flow.

From an integrators perspective, this is similar to an Enterprise Connect. authorization flow where an administrator is redirected to a crafted URL within their browser and later return with a code that can be redeemed for OAuth tokens at the end of the process.

The main difference here is that the resulting authorization will relate to an Organizational Unit rather than a calendar service account.

Example request #

Spread over multiple lines for clarity.

https://{data_center_app_url}/organizational_unit_oauth
    ?response_type=code
    &client_id={CLIENT_ID}
    &redirect_uri={REDIRECT_URI}
    &state={STATE}
    &scope=organizational_unit_use_integrations
    &capabilities[]=conferencing
    &ou_link_token={OU_LINK_TOKEN}

Request URL parameters #

scope required  #

organizational_unit_use_integrations is the only supported scope at present.

capabilities[] required  #

A single value of conferencing to force the administrator to authorize access to a conferencing provider, such as Zoom, as part of the overall authorization flow.

ou_link_token required  #

A token referencing the desired calendar service account from creating an Organizational Unit link token.

conferencing_provider_name optional  #

A optional value when you want the administrator to connect a specific conferencing provider rather than choosing their preferred one from a list.

Currently supported values are:

• indeed
• webex_enterprise
• zoom_enterprise

If a value is provided but not supported or recognized, the flow will default to showing the list of available conferencing providers.

You can control the providers shown to your users by setting the conferencing categories.

Future usage #

With the link established, any calendar accounts provisioned via the calendar service account will be automatically cross-referenced with the enterprise conferencing service account and appropriate conferencing profiles provisioned when an email-based match is found.

No further intervention will be required by the integrator or the adminstrator for this to happen.

Details of conferencing profiles linked in this way will be available through the UserInfo endpoint when authenticated as the individual accounts.