signplume
Start free

Handbook › Connect your directory

Connect Google Workspace

Connecting Google Workspace lets signplume read your directory, so joiners, title changes and leavers reach everyone's signature without anyone uploading a CSV. It takes about five minutes in Google Cloud and the Google Admin console. You need to be a super administrator of your Google Workspace for the delegation step.

signplume reads the names, job titles, departments, phone numbers and profile photos of the people in your directory and, if you allow it, your groups. It writes nothing to your directory. It writes each person's Gmail signature only if you also turn on Gmail push.

The job title and department come from each person's Employee information in the Admin console: open the person in the directory there, and the fields are under Employee information. Organisational units are read too, with no extra scope: each unit appears as a target next to your groups on Rules and Campaigns, and a unit includes the units below it. A unit is never printed in a signature and doesn't fill the department, so someone in a "Sales" unit whose Department field is empty still has no department. Units are matched by their path, so renaming a unit in Google makes it a new target, and a design pointed at the old name has to be set again.

The scopes signplume asks for

You grant these on the domain-wide delegation in step 2. signplume asks for nothing else.

  • https://www.googleapis.com/auth/admin.directory.user.readonly (admin.directory.user.readonly), required: reads the people in your directory. It is read-only on purpose.
  • https://www.googleapis.com/auth/admin.directory.group.readonly (admin.directory.group.readonly), optional: reads your groups and who is in them, for group templates on Rules and group audiences on Campaigns. Without it, groups are skipped.
  • https://www.googleapis.com/auth/gmail.settings.basic (gmail.settings.basic), optional: writes each person's Gmail signature, for Gmail push only.

1. Create the service account

  1. Open the Google Cloud console and pick or create a project for signplume.
  2. Under APIs & Services → Library, enable the Admin SDK API. If you will use Gmail push, enable the Gmail API as well.
  3. Under IAM & Admin → Service accounts, choose Create service account and give it a name such as signplume-sync. It needs no roles in the project.
  4. Open the new service account, go to Keys → Add key → Create new key, choose JSON and download the file. Keep it safe: it works like a password.
  5. From the file, note client_email (the service account's address, ending in .iam.gserviceaccount.com) and client_id (a long number; the console shows the same number as the service account's Unique ID).

2. Grant domain-wide delegation

  1. In the Google Admin console, open Security → Access and data control → API controls, choose Manage domain-wide delegation, then Add new. If Access and data control isn't listed under Security, choose Show more. The direct link is admin.google.com/ac/owl/domainwidedelegation.
  2. Paste the service account's client ID.
  3. Under OAuth scopes, paste https://www.googleapis.com/auth/admin.directory.user.readonly. To sync groups or use Gmail push, add those scopes on the same line, separated by commas.
  4. Choose Authorize.

With all three scopes, the line reads:

https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.group.readonly,https://www.googleapis.com/auth/gmail.settings.basic

Google says a new delegation usually works within minutes, and can take up to 24 hours.

3. Paste the key on Directory sync

Open Directory sync in signplume (/admin/directory-sync) and fill in:

  • Service account email: client_email from the JSON file.
  • Workspace admin to act as: the address of an administrator in your Google Workspace who can see every person in the directory; a super administrator is simplest. Domain-wide delegation always acts as a real admin, because the service account belongs to no domain and can list no directory on its own.
  • Customer ID (optional): leave it blank to use my_customer, which means the Google Workspace of the admin above.
  • Private key (PEM): private_key from the same file, from -----BEGIN PRIVATE KEY----- to -----END PRIVATE KEY-----, both lines included.

Press Connect Google Workspace. signplume checks that the key parses before storing it, stores it encrypted, and never shows it again. Press Sync now for the first run; after that the sync runs on its own about every six hours.

If the sync fails

Directory sync shows the last error in Google's own words. The usual causes:

  • unauthorized_client: the client ID or the scopes on the delegation do not match exactly, or the delegation has not taken effect yet.
  • A message that the Admin SDK API has not been used in the project, or is disabled: enable it in the service account's project (step 1).
  • Not Authorized to access this resource/api: the admin you act as cannot read the directory. Use a super administrator.

Replacing the key

Open Replace credentials on Directory sync. Saving always replaces the stored key; there is no way to change the other fields and keep it. To stop syncing without removing anything, press Pause syncing instead.