Create a Google Cloud project for Google connectors
Create a Google Cloud project of your own, publish it, and sign in once so every Google connector can read your account.
A Google connector, such as Google Calendar, signs in through a Google Cloud project that you own, not one that Marfa publishes. You make the project once and sign in once, and every Google connector you run shares that one sign-in. Nothing depends on a project someone else looks after, and Google never has to review it.
You need the Google account whose data you want to read, and a connector built as Bring in records from another service shows, with its key and settings. An instance works with one Google account: each Google connector keeps the account it first ran with and refuses another. For a second account, use a second instance.
Create the project
Sign in to the Google Cloud console with that Google account. Go to Menu > IAM & Admin > Create a Project, enter a Project Name, and select Create. Nothing in Marfa uses the project's name or ID.
Turn on the APIs your connectors use
A project can only call the APIs you turn on in it. Each connector's Catalog page names the APIs it calls and the permissions it asks for. Google calls a permission a scope and writes it as an address.
Go to Menu > APIs & Services > Library, open each API, and select Enable. For Google Calendar, that's the Google Calendar API.
Set up the sign-in screen and publish it
The sign-in screen is what you see when you give a connector access. Go to Menu > Google Auth platform, and select Get Started if it isn't set up yet.
- Under App Information, enter an App name and a User support email, then select Next. Don't choose a name that could be mistaken for a Google product.
- Under Audience, choose External, then select Next.
- Under Contact Information, enter an email address, then select Next.
- Under Finish, agree to the Google API Services User Data Policy, then select Continue and Create.
- Go to Audience and select Publish app, then confirm. The status changes from Testing to In production.
Don't skip publishing. While a project is in Testing, Google ends every sign-in after seven days, so a connector would stop each week. Once published, a sign-in lasts until you remove it or it goes unused for six months. You don't need to add yourself as a test user.
Create a desktop client
Go to Menu > Google Auth platform > Clients, and select Create client. Set Application type to Desktop app, enter any Name, and select Create.
Copy the client ID and the client secret into your password manager. Google shows the whole secret only now: if you lose it, open the client and select Add Secret. Give both to every Google connector:
export GOOGLE_CLIENT_ID=<the client ID>
export GOOGLE_CLIENT_SECRET=<the client secret>Sign in once
Run the connector's setup by hand, with its usual settings and the two Google settings in place. Setup writes the sign-in to a file that must not exist yet, outside any Git checkout:
node connectors/google-calendar/dist/main.js --setup ~/google-setup.jsonSetup prints an address on your computer. Open it in a browser and follow the link to Google.
- Choose the Google account.
- Google says Google hasn't verified this app, because nobody reviewed your project. That's expected for a project only you use. Select Advanced, then the link that ends in (unsafe).
- Leave every permission ticked. A connector can't do what a cleared permission covers.
The file then holds one value, GOOGLE_REFRESH_TOKEN. Put it in your password manager and in the settings of every Google connector, then delete the file.
If your browser is on another computer, open the Google address that setup prints beside the instruction to paste, and sign in there. The last page shows an error, because it can't reach the computer that runs setup, but its address bar holds the address Google sent. Paste that whole address into the terminal where setup waits, and press Enter. If your terminal cuts the line short, finish in a browser on the computer that runs setup.
Add another Google connector
All Google connectors share one sign-in, so a second one adds its permissions to it:
- Turn on the new connector's API in the same project.
- Run the new connector's setup with the
GOOGLE_REFRESH_TOKENyou have in its settings. Setup asks Google again for every permission that token holds, beside the new connector's own. - Sign in with the same account, and leave every permission ticked.
- Put the new
GOOGLE_REFRESH_TOKENin the settings of every Google connector, the first included, and restart them.
Until you update the first connector, it keeps running on the old token, which holds only what it held before, and nothing warns you.
Sign in again
When Google no longer lets a connector in, the connector stops calling Google and reports the problem google:reconnect, which marfa connectors get <connector-id> shows. Google ends a sign-in when:
- You remove the project's access at
myaccount.google.com/connections. - The sign-in goes unused for six months.
- The project is still in Testing, and seven days have passed.
- You chose access for a limited time, and it ran out.
To sign in again, publish the project first if it's in Testing. Then run the connector's setup and sign in with the same account, put the new GOOGLE_REFRESH_TOKEN in every Google connector's settings, and restart them.
A sign-in that Google ended holds no permissions to carry over, so setup asks only for that connector's own. With several Google connectors, run each one's setup in turn, each with the token the last one wrote, so the final token holds every connector's permissions. A connector still missing one reports a problem that starts with google:scope:.
Google connectors lists every problem setup and Google can report, with its fix.