Connectors
Registering your organisation's Google or Microsoft application, so members can connect their own accounts.
Connectors in the console. Register the Google and Microsoft applications your organisation owns. Members then connect their own accounts against them, under Profile then Connections.
The split matters: you register the application, each person grants their own access, and the assistant acts with their permissions. There is no shared mailbox credential.
Setting one up
Step-by-step, including the permissions each service uses and what they are for:
Read this before you register
Four things that are cheaper to know now than to discover later. The console states them beside the fields.
Set your Google consent screen to Internal, or move it to production, before anyone connects. While it is in Testing, Google expires every connection after seven days, however often it is used. Members reconnect weekly, blame the product, and stop using it. This is the most common way a connector rollout dies quietly.
An External consent screen asking for Gmail or full Drive access needs Google verification and a third-party security assessment. Internal avoids both. If your members are all in your own Workspace, Internal is the answer and it is not close.
Request only the scopes you need. Everyone who connects approves exactly what your application asks for, so an over-broad request is permanent.
For Microsoft, register a single-tenant application in your own directory and keep its directory (tenant) ID to hand.
What members get
Once registered, members connect their own account and choose which services to allow: Calendar, Drive, Gmail, Docs, Sheets, Slides, Drive uploads.
Two constraints are Google's rather than ours, and members will ask you about both:
- Docs, Sheets, Slides and Drive uploads share one permission. Enabling any one enables all four.
- Editing a document requires access to Drive files generally, because Google only grants document comments together with full file access.
Members can only change their selection by disconnecting and reconnecting, so the consent screen is worth getting right.
See Connections for what your members see.
What this enables
With a connector registered and a member connected, the assistant can work with that member's mail, calendar and files: reading them, and creating or changing things with confirmation.
It also changes where deliverables go. A collection that mirrors a Drive or SharePoint folder receives files there rather than in Asteria Cloud, which is usually what people want. See Connected folders.
A file created through a member's connected account belongs to that member in Google or Microsoft, not to the organisation. When they leave, it goes with their account unless it sits on a shared drive.
Worth saying out loud to teams before they build a process around it, and worth pointing them at shared drive folders rather than personal ones.
Workflows that trigger on incoming mail
Gmail is the one Google service that does not deliver notifications to an address we choose. It publishes them to a Cloud Pub/Sub topic in your own Google Cloud project, and you point that topic back at us. Four steps, all in the project your OAuth application already lives in: Google will not accept a topic from anywhere else.
1. Create the topic. Enable the Cloud Pub/Sub API and create a topic with any name. Copy its full name, which looks like projects/your-project/topics/asteria-gmail, and paste that into the Gmail Pub/Sub topic field when you register or update your Google application here.
2. Let Gmail publish to it. On the topic, grant gmail-api-push@system.gserviceaccount.com the Pub/Sub Publisher role. That address is Google's own, the same for every customer.
It never appears in the console's principal picker (it lives outside your project), so type it in and ignore the missing suggestion. Skip this step and nothing complains until somebody enables a Gmail trigger, which then fails with a permission error that reads like an OAuth scope problem.
3. If your organisation enforces Domain Restricted Sharing, step 2 is refused outright, with a message about constraints/iam.allowedPolicyMemberDomains. The constraint accepts customer IDs rather than domain names, so there is nothing you can type that names Google's service accounts.
What works: override the policy on the project rather than the organisation, make the grant, then set the project back to inheriting. The constraint is checked when a policy is written and is explicitly not retroactive, so the grant you just made survives you turning the restriction back on.
4. Create a push subscription. Once the topic is saved here, the console shows the Gmail push endpoint for your organisation, with a copy button. Create a push subscription on your topic and paste that address in as the endpoint. It is specific to your organisation and contains a secret, so treat it as you would any webhook URL.
Your workflows will run without step 4. Push is what makes them run the moment mail arrives; without it they fall back to a check every 20 minutes, which is often perfectly fine.
It also tells you where to look when something is wrong. A trigger that fires but always feels late means the subscription is wrong. A trigger that will not enable at all means the publisher grant is missing.
Unattended runs
Workflows run with nobody present and use the connected accounts of whoever set the schedule up. A scheduled step that sends mail sends it as that person.
That is the property to explain when someone asks why a workflow needs their account connected, and the reason to be careful about who is made an editor on a shared workflow.