How Happeo Integrates with Google

Where Google meets Happeo

Happeo’s integration with Google ensures that your intranet becomes an extension of the tools your organization already uses every day. From authentication to collaboration, Happeo’s Google integrations are designed to provide secure, efficient, and user-friendly experiences.

• For employees, this means a single place to access files, events, and emails without switching between apps.
• For IT teams, it means centralized control over permissions and security policies, reducing risk while simplifying administration.
• And for leadership, it means confidence that the intranet remains a consistent and trusted hub, rather than another fragmented tool.

By embedding Google Workspace directly into Happeo, organizations can minimize context-switching, maintain data accuracy, and ensure teams stay aligned around one source of truth.

Overview of Google integrations in Happeo

Happeo integrates with Google across several layers of the platform:

• User Login (Single Sign-On with Google)
• User Provisioning and Group Synchronization
• Happeo Web Application
• Happeo Mobile Application

Each integration has a distinct purpose: from making onboarding frictionless to enabling direct access to files, emails, and calendars within the intranet itself. Together, they ensure employees can focus on work without switching contexts or duplicating efforts.

How integrations appear in Happeo

Google services surface in Happeo through the following:

• Email, Calendar, and File widgets on Pages.
• Drive and Gmail results in Happeo Search.
• File and member authorizations within Channels.

Authentication and single sign-on

Happeo uses the OAuth 2.0 authorization code flow with OpenID Connect to authenticate users signing in with their Google accounts.

How it works:

1. Happeo redirects the user to Google for authentication.
2. The user signs in and authorizes Happeo.
3. Google returns an authorization code to Happeo.
4. Happeo exchanges this code for an ID token and an access token.
5. Using the ID token, Happeo securely identifies the user, matches them to its database, and creates a session.
6. The access token is then used to fetch basic user information from Google.

This process follows Google’s official OpenID Connect documentation and ensures that each user is securely identified before accessing Happeo.

Scopes requested:

• openid: Authenticate using OpenID Connect.
• profile: View basic profile information.
• email: View the user’s email address.

Token handling: Happeo does not store refresh tokens for login. A temporary access token is used only to fetch user information during the sign-in process, which minimizes exposure and strengthens security.

Library usage: Happeo uses Google’s own libraries for OAuth 2.0 and API connectivity. This minimizes risk by aligning with Google’s recommended security practices and keeping the integration up to date with API changes.

User and group synchronization

Happeo uses domain-wide delegation to synchronize users and groups from Google Workspace. This allows an administrator to approve the Happeo application for the entire organization, so that background updates can run without requiring each individual user to authorize access.

How it works:

1. The administrator installs the Happeo application from the Google Workspace Marketplace.
2. During installation, the application requests certain permissions.
3. With these permissions, Happeo can impersonate an administrator when performing background tasks, such as updating user or group information.
4. Once installed, the application is visible in the Google Admin Panel.

Features enabled by this flow:

• Automatic synchronization of users and groups into Happeo.
• Author attribution for posts, comments, and pages.
• Searchable user profiles with user data from Google Workspace.
• Sharing of Channels and Pages.

Scopes requested:

• userinfo.profile and userinfo.email: Always required for app integration with Google.

• Group read-only scopes: To retrieve group information.
• Secondary domain read-only scope: Used in specific cases to verify users and resolve update errors.

• User read-only scopes: To access profile information needed for synchronization.
• Resource calendars read-only scope: Included by Google in the Admin SDK API.

⚠️  Note: The manage sites scope was previously required for an older Google Sites v1 integration, but this API was deprecated in September 2021.

Libraries used: Happeo relies on Google’s official libraries for the impersonation flow and API connectivity, ensuring compatibility and security.

🔎 For more information, see the documentation provided by Google.

OAuth 2.0 and access management

Happeo’s integrations with Google are built on the OAuth 2.0 framework. You can find Google’s general documentation here, which explains how to set up client-side, server-side, and other application scenarios.

OAuth requires three components to work together:

• Application credentials: Identify the application making the request (in this case, Happeo).
• Scopes: Define the level of access being requested (e.g., read-only Drive access vs. full Drive access).
• Access tokens: Represent the user’s permission to access the requested data.

When combined, these elements allow Happeo to request specific types of access on behalf of a user.

Token lifecycle:

• Access tokens generally expire within one hour.
• To keep integrations working without interruption, new tokens must be obtained.
• The method for refreshing tokens depends on the OAuth flow used:
  • Authorization code flow: A refresh token (issued during the initial login) is used to request a new access token without requiring the user to log in again.
  • Implicit flow: The access token expires and must be renewed by re-running the login flow.

These flows are explained in more detail in the following sections.

Authorization Code Flow

1. Happeo redirects the user to the Google OAuth endpoint, requesting the necessary scope.
2. The user logs in to Google (if not already logged in) and authorizes Happeo.
3. Google redirects the user back to Happeo with an authorization code.
4. Happeo exchanges this code for both an access token and a refresh token.
5. The access token is used to call Google APIs, while the refresh token allows Happeo to request new access tokens when the old one expires.

Because of this, Happeo can refresh tokens in the background — without prompting the user to log in again or showing an additional authorization screen, resulting in a smoother, uninterrupted user experience.

🗒️ Note: For most organizations, the authorization code flow remains the recommended, more secure option.

Implicit Flow

1. Happeo redirects the user to the Google OAuth endpoint, requesting the required scope.
2. The user signs in to Google (if not already signed in) and authorizes Happeo.
3. Google redirects the user back to Happeo with an access token.
4. Happeo uses this access token to call Google APIs.
5. When the access token expires, Happeo must repeat the process from step 1 to obtain a new one.

Because of this, the user must always remain logged in to Google for the integration to continue working. Unlike the Authorization Code Flow, Happeo’s servers cannot refresh tokens in the background — meaning tokens can only be renewed when the user is actively present.

How to enable Implicit Flow

Admins can enable implicit flow in the following way:

1. Click your avatar in the top-right corner of your intranet’s main navigation and go to Admin Settings.
2. Navigate to Advanced Control > OAuth2.
3. Toggle Implicit OAuth2.

Happeo Web application integrations

The Happeo web application integrates directly with Gmail, Drive, and Calendar. API calls to Google services are made client-side — directly between the user’s browser and Google — so Happeo’s servers do not process the retrieved data. However, this process is slightly different if Search AI is enabled. 

🔎 See the section ‘Data flow in Search AI’ below for more information.

To connect Google APIs, the web app requires an access token, which can be obtained through either the Authorization Code Flow or the Implicit Flow. Admins can configure which flow is used, depending on their organization’s security preferences.

Authorization Code Flow for the web application

1. The Happeo app opens a popup directing the user to the Google OAuth endpoint, requesting the required scope.
2. The user signs in to Google (if not already logged in) and authorizes Happeo.
3. Google redirects back to Happeo with an authorization code.
4. Happeo’s backend exchanges the code for an access token and a refresh token.
5. The refresh token is stored securely in Firestore, encrypted with Google’s Key Management Service (KMS).
6. The access token is passed to the browser for immediate use.
7. When the access token expires, the app requests a new one from the backend. The backend uses the refresh token to obtain a new access token, which is then exposed to the app.

Why use authorization code flow?

• This is the default and most secure option.
• The access token is never exposed in the URL.
• Tokens are encrypted with KMS, with keys rotated every 90 days.
• Backend endpoints for token storage and refresh always authenticate the user session, ensuring tokens can only be exchanged or refreshed while the user is logged in.

Implicit Flow for the web application

1. The Happeo app opens a popup directing the user to the Google OAuth endpoint.
2. The user logs in to Google and authorizes Happeo.
3. Google redirects back with an access token (no refresh token).
4. The token is stored in the browser’s session storage.
5. When the token expires, the app must repeat the login flow to obtain a new one.

When to use implicit flow: If you prefer not to store user tokens on Happeo’s backend.

Considerations:

• The user must always remain logged into Google.
• Pop-ups may appear when refreshing tokens, which can disrupt the user experience.
• From a security perspective, implicit flow is less recommended since tokens are exposed in the browser and can be vulnerable to interception.

Why both options exist

We recognize that different organizations have different security requirements. That’s why admins can choose between flows:

• Authorization code flow for stronger security and seamless user experience.
• Implicit flow for scenarios where storing tokens server-side is not desired.

In both cases, Happeo prioritizes privacy. API calls are made directly between the browser and Google, and when tokens are stored server-side, they remain encrypted and inaccessible to Happeo employees.

Happeo Mobile application integrations

The Happeo mobile app also integrates directly with Gmail, Drive, and Calendar. It uses the authorization code flow but stores refresh tokens locally in the app storage instead of Happeo servers.

This approach balances mobility with security, ensuring employees can access Google content on the go without sacrificing data protection.

Data flow in Search AI

When a user performs a search in Happeo:

• The search begins client-side, with requests sent to Happeo’s search and any enabled federated search connectors (e.g. Google Drive).
• At this stage, the data returned by the search connectors remains on the client side.

If Search AI is enabled:

• While API calls to Google services are made client-side, the search query and the results from the enabled integrated sources (e.g. Google Drive) are passed to Happeo’s backend.
• The backend sends this information, along with a prompt, to Gemini (Google’s AI model) to generate the AI answer.
• Happeo does not store the document content returned in these results. Instead, it keeps only document identifiers to support Happeo features (if enabled), such as suggesting documents to link within Happeo.

This ensures AI-powered search remains accurate and helpful without compromising data security.

🔎 Check out our Admin Settings: Search article to learn how to manage which integrated sources are included or excluded from AI generation.

What scopes are requested?

The scopes requested depend on the integrations you enable. For example:

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 are so many scopes requested? Can only some be accepted?

Scopes in Happeo are tied to specific integrations. This means you only need to grant the scopes for the integrations you plan to use — if you don’t enable a particular integration, its scopes won’t be requested.

The list shown represents the maximum possible scopes Happeo may ask for. In practice, Happeo requests scopes incrementally. For example, if you only need read access to Drive folders, you’ll only be prompted to approve the lightweight readonly scope, not full access.

Some features, however, can only function with broader scopes. For instance:

Sharing a Drive folder:

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

Sharing a calendar:

• Calendar API, v3
• Sharing & attendees
• Acl: Insert

This balance ensures admins retain control while still enabling advanced collaboration features when needed.

Security and token management

When tokens are stored, they are always encrypted via Google Cloud’s Key Management Service (KMS). Tokens never provide Happeo employees direct access to user data, and access to production databases is strictly controlled.

Keys used for encryption are rotated every 90 days, reducing long-term exposure risks.

FAQ

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

Happeo pulls information from Google Directory accounts, not from individual Google profiles. The two are separate and not linked.

Happeo does sync with Custom Attributes stored in the Google Directory. These attributes can only be created and managed by Google Directory administrators — regular users cannot add or edit them in their personal Google profiles.