How Happeo Integrates with Google

This article explains the different ways Happeo integrates with Google and the use cases for those integrations.

Google integrations in Happeo

The following Happeo components have integrations with Google:

1. User Provisioning
2. User Login (Single Sign-on with Google)
3. Happeo Web application
4. Happeo Mobile application

The Happeo Web and Mobile applications have user-facing integrations to Google services where Happeo retrieves users' data in Google services such as Calendar, Drive, Gmail, etc. This integration manifests in the form of Mail, Calendar, Folder widgets on Pages, Happeo Search, Folder, and Member authorizations on Channels.

The user login functionality integrates with Google in order to retrieve the user’s identity so that Happeo can authenticate them to allow access to the Happeo application.

OAuth 2.0

The integrations are using the standard OAuth 2.0 framework to access the Google APIs. 

Here’s a link to the general Google documentation for applications trying to access the Google API. This link explains how to set up client-side applications, server-side applications, or other scenarios.

In short, there needs to be application credentials, scopes, and access tokens sent to the Google APIs for the APIs to respond.

•  The application credentials are credentials that identify an application (like Happeo)
•  The scopes are a set of access requests for a certain API
•  The access tokens are a user’s access tokens

So when combining all three, you get an application requesting a type of access for a user.

Access tokens expire (generally in 1 hour). For continuous integration with Google, Happeo needs to obtain new access tokens from Google. The process of refreshing an access token is determined by the OAuth flow used to obtain that access token.

With implicit flow, the access token is refreshed by re-running the flow, whereas with the code flow, the access token is refreshed by using a refresh token (that is obtained in the first run of the flow). We explain these two flows in the following sections and in more detail in subsequent sections.

Authorisation Code Flow

The authorization code flow works as follows:

1. Happeo sends the user to the Google OAuth endpoint requesting a particular scope
2. The user logs in to Google and authorizes Happeo
3. Google redirects back to Happeo with an authorization code
4. Happeo exchanges the authorization code with an access token and refresh token
5. Happeo uses the access token to access Google APIs, and the refresh token is used to ask for a new access token

This means that Happeo can refresh the user’s access token without prompting the user to log in again or showing a screen for a token refresh, thus improving the user experience.

Implicit flow

An implicit flow works as follows:

1. Happeo sends the user to the Google OAuth endpoint requesting a particular scope
2. The user logs in to Google and authorizes Happeo
3. Google redirects back to Happeo with the access token
4. Happeo calls the Google APIs with the access token
5. When the access token expires, Happeo runs step 1 again to obtain a new access token

This means that the user must always be logged in to Google for Happeo to be able to refresh the access token. Thus, Happeo servers cannot use the user’s token to call Google APIs without the user being present. 

Happeo web app

The Happeo web app integrates with Gmail, Drive, and Calendar. The integration is a client-side integration, where all the calls to the Google APIs are made directly between the web clients (the browser) and Google.

There is no user data flowing through or processed by Happeo’s servers. The web app, however, needs to have an access token to access Google APIs, which is then obtained via either the implicit flow or the authorization code flow. The administrator can configure which flow to be used for the web app

Authorization code flow

The authorization code flow for the web app works as follows:

1. Happeo app opens up a popup that sends the user to the Google OAuth endpoint requesting a particular scope
2. The user logs in to Google (if not already logged in), and authorizes Happeo (if not already authorized)
3. Google redirects back to Happeo with an authorization code
4. Happeo’s backend exchanges the authorization code with an access token and refresh token
   1. A refresh token is stored on the backend (encrypted with Google’s Key Management Service and stored in Firestore Database).
   2. An access token is exposed to the app and stored on the browser
5. When the access token expires, the Happeo app asks the backend for a new access token. The backend uses the refresh token stored in its database to call Google APIs and gets a new access token, which is then exposed to the app (step 4b)

When to use an authorization code flow?

The authorization code flow is the default way for users to authorize Happeo to access Google. The flow is generally considered more secure than the implicit flow as the access token is not exposed in the URL. 

The user’s refresh token in the authorization code flow is stored by the backend in the Firestore database. It is encrypted by Google’s Key Management Service (KMS) before it is stored in the database. This is to prevent the leaking of tokens to people who have access to the database or if the database is compromised. The KMS does not give any access to keys used to encrypt/decrypt the data. To encrypt the token, the backend identifies itself using a service account to KMS and provides data to encrypt. Finally, keys in the KMS are rotated every 90 days.

The Happeo backend endpoints for token storage and token refresh always authenticate the user (by verifying the user session). This means that the user must be logged in when the Happeo app needs to exchange the authorization code for tokens (access and refresh tokens) or when it needs to refresh the access token.

Implicit flow

The implicit flow for the web app works as follows:

1. Happeo app opens up a popup, sends the user to the Google OAuth endpoint requesting a particular scope
2. The user logs in to Google (if not already logged in) and authorizes Happeo (if not already authorized)
3. Google redirects back to Happeo with the access token
4. Happeo stores the access token in the browser’s session storage for later usage
5. When the access token expires, Happeo UI (i.e. the Happeo app in the browser) runs the steps again to obtain a new access token. 

This means that the user must be always logged in to Google for Happeo to be able to refresh the access token. 

When to use implicit flow?

Use the implicit flow if you do not want Happeo to store user tokens on the server side.

Some considerations for implicit flow

Since the user must be always logged in to Google, this may at times negatively affect the user experience. Whenever the user logs off from Google, a pop-up asking the user to authorize Happeo to access Google APIs will show up. A small pop-up may open up every hour for a fraction of a second whenever Happeo refreshes the access token (a limitation from Google, which Happeo has fixed).

Implicit flow is generally not recommended from a security perspective due to the user token being exposed in a browser URL and stored in the browser which may lead to potential vulnerabilities.

To turn on the implicit flow, go to Admin Settings > Security > Google Integration and turn on the toggle for implicit flow. 

Why?

We value our users' privacy and have built our Google integrations with this in mind. The application makes API calls to Google directly from the user's browser and the information is combined on the browser and presented to the user looking like it is a part of the Happeo application.

We provide the option for Admins to choose between the implicit or the authorization code flow based on their security requirements. Whenever the tokens are stored on Happeo’s backend, our employees cannot at any point have access to the tokens, and access to our production databases is strictly controlled.

What scopes are asked?

Gmail

• https://www.googleapis.com/auth/gmail.settings.basic - Manage your basic mail settings
• https://www.googleapis.com/auth/gmail.readonly - View your email messages and settings

Drive

• https://www.googleapis.com/auth/drive - See, edit, create, and delete all of your Google Drive files
• https://www.googleapis.com/auth/drive.metadata.readonly - See information about your Google Drive files
• https://www.googleapis.com/auth/drive.readonly - See and download all your Google Drive files

Calendar

• https://www.googleapis.com/auth/calendar - See, edit, share, and permanently delete all the calendars you can access using Google Calendar
• https://www.googleapis.com/auth/calendar.readonly - See and download any calendar that you can access using your Google Calendar
• https://www.googleapis.com/auth/calendar.events.readonly - View events on all of your calendars
• https://www.googleapis.com/auth/calendar.events - View and edit events on all of your calendars

Why do we have so many scopes? Can only some of them be accepted?

Each integration can be enabled separately, therefore if you do not need one of the integrations, you will not need to accept its scopes either. 

Additionally, the scopes listed above are the maximum scopes asked by the application. We aim to ask scopes incrementally, that is, if you only need read access to drive folders, then we will only ask and you will only need to accept the smaller readonly scope for Drive files.

As to why those are the maximal scopes, sharing a drive folder is only available with the largest scope, see:

• Drive API, v3
• Share files, folders & drives
• Permissions: Create

It is the same for sharing a calendar, see:

• Calendar API, v3

• Sharing & attendees

• Acl: Insert

What libraries do we use?

We use Google’s libraries for the OAuth 2.0 flow and to connect to the Google APIs.

Happeo mobile app

The Happeo Mobile app uses the authorization code flow to integrate with Google services, similar to the web app. However, the refresh tokens are not stored on Happeo’s server but instead are stored in the mobile app storage itself.

User Login (Single Sign-on with Google)

The user login functionality uses the OAuth 2.0 authorization code flow as follows:

1. Happeo servers initiate the flow and the user is redirected to Google
2. The user signs in to Google and authorizes Happeo
3. Google redirects the user to Happeo with an authorization code
4. The Happeo server exchanges the authorization code with the ID token and the access token
5. Happeo identifies the user based on the ID token and creates a session
6. Happeo uses the access token to fetch user information from Google

Why?

We use OpenID Connect to identify users signing in to Happeo with a Google account. 

We follow the documentation provided by Google for the sign-in flow.

At the end of the flow, we are able to securely identify the user, match it to a database record and create a Happeo session for it.

What scopes are asked?

These are the basic OpenID Connect scopes: 

• openid - Authenticate using OpenID Connect
• profile - View your basic profile info
• email - View your email address

Are we using refresh tokens and if so, are they stored securely?

We do not store any tokens for user login. When signing in, the temporary access token is used to fetch the user information from Google.

 

What libraries do we use?

We use Google’s libraries for the OAuth 2.0 flow and to connect to the Google APIs.

User and group sync

The user and group sync functionality uses domain-wide delegation.

This is when an administrator of the company in Google Workspace wants to approve an application for the whole company. For more information please see the documentation provided by Google.

For Happeo, this means that the administrator will go to the Google Workspace marketplace and install the Happeo application there. The application will ask for certain permissions, which the Happeo application can then use to impersonate an administrator when doing background tasks. The application can be later found in the Google Admin Panel.

What features in Happeo are behind this flow?

The Google User & Group synchronization is behind this flow.

Why?

The Happeo Application has posts, comments, pages, etc. that are created by users. The application shows who is the Author of a Post, for example, and this means that user information needs to be stored. The Happeo Application also allows users to search for other users in the same company with different keywords, some of which come from their user profile in Google.

The User & Group information is also used to share Channels & Pages. This means that there needs to be a background process that updates User & Group information in a regular manner.

What scopes are asked?

’userinfo.profile’ and ‘userinfo.email’ are always asked when integrating an app with Google.

The ‘manage sites’ scope is for an older integration with Google sites v1, which has been deprecated by Google in September 2021.

These are two group read-only scopes to read the group information from the APIs. In addition, there is a read-only scope to read the secondary domains used by the company, used in a few places in the app to verify users and try to manage/debug user update errors.

Here are three read-only scopes to read the user information from the APIs. In addition, there’s a read-only scope for the resource calendars API, which Google has included in the Admin SDK API and not the Calendar API.

What libraries do we use?

We use Google’s libraries for the impersonation flow and to connect to the Google APIs.

Q&A

Why are custom fields in my Google profile not showing up in my Happeo User Profile?

Happeo only uses Google Directory accounts as opposed to Google profiles. The Google Directory and Google profile are not linked to each other. 

Happeo does sync with Custom Attributes that are in the Google Directory. These are attributes that only the Google Directory Admins can set - not something regular users can do themselves in their Google profile.