Give a plugin's connector access to your Google account

Let a plugin's connector reach your Google account through a Google Cloud project you own, signing in from a browser while Marfa keeps the token.

A plugin's connector that declares a sign-in, in its plugin format sign_in, reaches your account through an OAuth client of your own: Marfa publishes none. You sign in once in a browser, and Marfa keeps the refresh token as one of the connector's secrets, which the connector reads at each run and refreshes itself. Google is the one provider. Each command needs connectors.manage.

You need a Google Cloud project with the connector's APIs turned on and its sign-in screen published: follow the first three steps of Create a Google Cloud project.

Create a web client

In the Google Cloud console, go to Menu > Google Auth platform > Clients, and select Create client. Set Application type to Web application. Under Authorized redirect URIs, add your instance's sign-in address followed by /connect/oauth/callback, such as https://river.marfa.so/connect/oauth/callback, then select Create.

Google shows the whole client secret only now, so copy it with the client ID.

Give the connector the client

marfa plugins settings lists the connector's settings: one holds the client ID, and two secrets hold the client secret and the token. Set the first, then type the secret at the prompt, as Give a connector its settings shows:

marfa plugins settings <name> --set <client-id-setting>=<the client ID>
marfa plugins secret <name> <client-secret-setting>

Sign in

Terminal
marfa plugins sign-in <name> --wait
Open this address in a browser to sign in:
https://accounts.google.com/o/oauth2/v2/auth?client_id=...
signed in <name>

Open the address within ten minutes, choose the account, and leave every permission ticked. Google warns that it hasn't verified the app, because nobody reviewed your project: select Advanced, then the link that ends in (unsafe). The browser can be on any computer.

The token goes to the connector's token secret, and the connector picks it up on its next run. Without --wait, GET /plugins/{name}/connector/sign-in reads how the latest sign-in went.

If it fails

With --wait, a sign-in that fails, expires or is replaced by a later start exits 1 with sign_in_ended. The sign-in's status gives a fixed reason, never Google's own text:

ReasonWhat to do
invalid_clientThe client ID or secret is wrong. Set them again.
access_deniedYou declined in the browser. Sign in again.
timeout, unreachableGoogle didn't answer. Sign in again.
changed_since_startThe client or the plugin changed during the sign-in. Sign in again.

If Google shows its own error page instead of the sign-in, such as redirect_uri_mismatch, the redirect URI doesn't match the sign-in address exactly: fix it in the client, and sign in again. The audit log records each start and outcome as connector.sign_in, connector.signed_in and connector.sign_in_failed.

When access ends

Run marfa plugins sign-in again when the connector can no longer reach Google. A project still in Testing ends every sign-in after seven days, so publish it first. Moving the sign-in address, for example to Marfa Cloud, needs the new address added to the client's redirect URIs before you sign in.

Marfa sends Google one request, for the token, and only to finish a sign-in you started. The rules are in the plugins chapter of the contract, under A connector's sign-in, and the operations are Start a connector's sign-in and Get a connector's sign-in.

On this page