Google Workspace
Hearth can use a Google Workspace domain for sign-in and for five connectors: calendar, contacts, mail, files, and chat notifications into Google Chat. All of them read and write, except chat notifications, which only post. It is meant for a self-hosted Hearth.
Every connector is off until an administrator turns it on. Every connection is one person's own: Hearth works in a person's mailbox, calendar, address book, and drive as that person, and never uses a service account that reaches the whole domain.
What each connector does is on Connectors. This page is the setup.
Create the OAuth client
In the Google Cloud console, in a project for Hearth:
- Enable these APIs: Google Calendar API, People API, Gmail API, and Google Drive API.
- Under Google Auth Platform, set the audience to Internal, so only your Workspace domain can use the app.
- Add the scopes below to the data access list, only the ones for the connectors you will turn on.
- Under Clients, make an OAuth client of type Web application with both redirect URIs, exactly, with no trailing slash:
https://hearth.example.com/auth/callbackfor sign-inhttps://hearth.example.com/integrations/google/callbackfor the connectors
| Connector | Scope |
|---|---|
| Sign-in | openid, email, profile |
| Calendar | https://www.googleapis.com/auth/calendar |
| Contacts | https://www.googleapis.com/auth/contacts |
https://mail.google.com/ | |
| Files | https://www.googleapis.com/auth/drive |
| Chat notifications | none |
mail.google.com and drive are restricted scopes. An app whose audience is Internal may use them for your own domain without Google's verification.
Install
oidc:
enabled: true
provider: google
googleHostedDomain: example.com
clientId: <client ID>
google:
enabled: true
encryption:
enabled: true
The client secret goes in your existing Hearth secret under OIDC_CLIENT_SECRET and GOOGLE_CLIENT_SECRET, and the client ID under GOOGLE_CLIENT_ID. Encryption has to be on, because a refresh token has to be stored and Hearth will not store one in the clear. With Google on and encryption off, Hearth says so at start and leaves the connection off.
Sign-in
With oidc.provider: google, Hearth requires the signed token's hd claim to equal your domain, and the address to be verified. Google sets hd only for a Workspace account, so a personal Gmail account has none and is refused. The hd parameter that narrows Google's account chooser is only a hint to the person. The claim is what is checked.
Google's sign-in token carries no groups, so there is no group-to-role mapping for Google sign-in. People get capabilities from an owner or a super admin in Hearth, and the allowed-domain list and the hosted domain decide who may sign in at all. For teams that follow Google groups, see Google Workspace groups.
Turn the connectors on
- Sign in as the owner or a super admin and open Settings, then Connectors.
- Under Google Workspace, enter the primary domain and choose Connect. A person's Google account has to belong to that domain to connect.
- Turn on the connectors you want.
- Each person opens the same page, chooses Connect my Google Workspace account, and ticks what they want.
The connectors pull from Google every ten minutes. Set connectors.interval in the chart to change it, down to one minute.
Check it on your own domain
- Sign in with a Workspace account. Expect to be signed in. Try a personal Gmail address and expect it to be refused.
- Connect from Settings, then Connectors with the calendar ticked. Expect Google's consent screen listing the calendar.
- Make an event in Google Calendar and choose Sync now. Expect it on the Hearth calendar.
- Make an event in Hearth and sync. Expect it in Google Calendar, with a Meet link if you turned on links.
- Share a calendar with a second person, sync it into a department on the Connectors page, and expect the people in that department to see its events in Hearth.
- Open Mailbox. Expect your inbox, open a message with its whole body, reply, and expect the reply in Gmail's Sent.
- Make a contact in the CRM and sync. Expect it in Google Contacts, and the reverse.
- Open Cloud files, upload a file, rename it, move it, and delete it, and expect each in Drive.
- Disconnect, and expect the page to show you as not connected.