This article explains the different ways Happeo integrates with Google and the use cases for those integrations.
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 APIs.
That link explains how to set up client-side applications, server-side applications, or other scenarios.
In short, application credentials, scopes, and access tokens are needed to be 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 specific 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.
Client-side OAuth
In a client-side application OAuth 2.0 flow, the requests are being made between the web clients (the browser) and Google. There are no requests going through Happeo servers and no tokens are stored on the server side.
This type of application can be used when the user is always present for the actions and the action does not need to be processed on the server side.
For more information, please see this link.
What features in Happeo are behind this flow?
The Gmail, Google Drive, and Google Calendar Integrations are client-side applications.
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 users' browser and the information is combined on the browser and presented to the user as part of the Happeo application.
Happeo does not store tokens nor has the possibility to do so. Therefore, Happeo employees cannot at any point access any mail, files, or calendars belonging to a user.
What scopes are asked?
Gmail
| https://www.googleapis.com/auth/gmail.settings.basic | Manage your basic mail settings |
| https://www.googleapis.com/auth/gmail.metadata | View your email message metadata such as labels and headers, but not the email body |
| 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 |
Calendar
| https://www.googleapis.com/auth/calendar | See, edit, share, and permanently delete all the calendars you can access using Google Calendar |
Why does Happeo 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 for scopes in an incremental way, that is, if you only need read access to Drive folders, then we will only ask for 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:
- https://developers.google.com/identity/protocols/oauth2/scopes#drive
- https://developers.google.com/drive/api/v3/manage-sharing
- https://developers.google.com/drive/api/v3/reference/permissions/create
This is the same for Google Calendars, see:
- https://developers.google.com/identity/protocols/oauth2/scopes#calendar
- https://developers.google.com/calendar/api/concepts/sharing
- https://developers.google.com/calendar/api/v3/reference/acl/insert
What libraries does Happeo use?
Happeo uses Google’s libraries for the OAuth 2.0 flow and to connect to the Google APIs.
Server-side OAuth
In a server-side OAuth 2.0 authorization flow, the Happeo servers initiate the flow.
The “Token response” in the picture below contains both an access token that is valid for a certain amount of time (usually 1 hour) and a refresh token. The refresh token is stored by the application to renew access tokens. This type of application can be used when the user is not present for the actions or the action needs to be processed on the server side.
For more information, please see this link.
What features in Happeo are behind this flow?
The Google SSO (login) is a server-side web application.
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
Is Happeo using refresh tokens and if so, are they stored securely?
Happeo does not store any tokens. When signing in, the temporary access token is used to fetch the user information from Google.
What libraries does Happeo use?
Happeo uses Google’s libraries for the OAuth 2.0 flow and to connect to the Google APIs.
Domain-wide delegation
This is when an administrator of the company in Google Workspace wants to approve an application for the whole company.
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.
For more information, please see this link.
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, for example, who is the author of a post, 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 that 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 was 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.
