Organization Connect - multiple service accounts ^DESIGN

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 additional enterprise calendar connections alongside an existing connection at an Organizational Unit level.

This allows an integrator to support multiple calendar providers for a single customer, multiple tenants from a single calendar provider, and of course a combination of those things.

This often crops up with larger enterprise customers where different business units may run on different tenants, and potentially even different providers.

This can be considered as an extension of the existing Enterprise Connect model for connecting a single calendar tenant. 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. two or more calendar services, in order to provide a single interface across them.

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

Prerequisites #

We will start with the assumption that your application already has access to a calendar service account through Enterprise Connect. This is represented by Domain A in the diagrams.

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

1. A token generated to require the authorization process include the previously authorized Domain A calendar service account
2. A query string parameter instructing Cronofy that the process must also authorize an enterprise-level calendar 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 connect to the additional calendar service 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 an already authorized calendar service account and another calendar service account, 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_TBD
    &capabilities[]=calendars
    &ou_link_token={OU_LINK_TOKEN}

Request URL parameters #

scope required  #

organizational_unit_TBD is the only supported scope at present.

capabilities[] required  #

A single value of calendars to force the administrator to authorize access to a calendar provider 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.

Future usage #

With the link established, any attempts to provision calendar accounts through the original calendar service account will attempt to connect through the additional calendar service accounts if necessary.

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