How Happeo Integrates with Google

This article explains how Happeo integrates with Google Workspace—covering authentication, user and group synchronization, and web and mobile app connections.

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.

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

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.

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.

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.

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.

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.

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.

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.

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.