Getting started with Enterprise Connect

An introduction to using Enterprise Connect with your application.

Enterprise Connect is alternative way of applications obtaining authorization to access user's calendars. Instead of each end-user giving authorization individually, a Service Account is used to obtain authorization programmatically.

The Authorization Process

To get started, you will need the following:

  1. A web application
  2. A client_id and client_secret for your application from the Cronofy Developer Dashboard
  3. A Service Account on a G-Suite, Office 365 or Exchange installation configured to access one or more user mailboxes.

Once you have these you are then in a position to proceed with the first stage of authorization which is for the Service Account. More details below but this process is modelled as an OAuth2 flow. You redirect from your application to an authorization page and which in return redirects back to your application with a code  for subsequent access_token  redemption.

Once you have an access_token  for a Service Account you then use that to request individual access_tokens for user and resource calendars. You then store and use the  access_tokens in exactly the same way with the Cronofy API as you do with those generated through direct end-user authorization.

Service Accounts

Service Accounts are organization level accounts that can be created in both Microsoft and G-Suite domains. They can be granted permissions on a set of mailboxes within the domain. They can also be given permissions to access Resource Calendars (eg meeting rooms) and Shared Mailboxes.

The Enterprise Connect - Guide for System Administrators gives more information on how to setup and configure Service Accounts.

Service Account Authorization

As described above, obtaining an authorization for a Service Account is modelled as an OAuth2 flow. The outcome of this flow is an access_token  for the Service Account. 

The documentation describes the full set of parameters but of particular note are scope and delegated_scope

scope refers to the permissions you are requesting that directly apply to the Service Account. For instance if you want access to User mailboxes you would request service_account/accounts/manage and if you also want Resource Calendars then you would add service_account/resources/manage . These are presented as a space separated list.

delegated_scope refers to the maximum set of possible permissions your application will need for the User and Resource calendars. These are similar to the scope values you would request as part of direct end-user authorization. 

User and Resource Calendar Account Authorization

Once you have a Service Account authorization, you can then request access to an individual User or Resource Calendar. This is similar to an OAuth flow but without user involvement. 

A request for Delegated Access is made which has similar parameters to an OAuth2 authorization. The redirect_uri  is replaced by a callback_url

The callback_url will need to be publicly accessible so during development we recommend using a service like ngrok

The code is returned to this callback_url and an Access Token Request is made with the code. 

Again, replace redirect_uri with callback_url.

{
  "client_id": "{CLIENT_ID}",
  "client_secret": "{CLIENT_SECRET}",
  "grant_type": "authorization_code",
  "code": "{CODE}",
  "callback_url": "{CALLBACK_URL}"
}

You can then store the access_token  and refresh_token returned against the user in your application. 

Refreshing Access Tokens Obtained Through Enterprise Connect

This is identical to the process for tokens generated by end-user authorization. Refresh an Access Token.

Using Access Tokens Obtained Through Enterprise Connect

We've designed the Enterprise Connect process to ensure you can use the tokens generated with the Cronofy API in exactly the same way as those generated by end-user authorization.