Google Workspace setup¶

ARIS uses Google for two distinct things:

Operator login — Google OIDC. An OAuth 2.0 web client in a Google Cloud project.
Directory sync — read-only Admin Directory API. A service account with domain-wide delegation.

You do both inside one Google Cloud project tied to your Workspace tenant. Plan on 15–20 minutes.

What ARIS ends up with — read-only, two scopes, nothing else

By the time you finish this page, ARIS will hold credentials with exactly these permissions against your Workspace:

https://www.googleapis.com/auth/admin.directory.user.readonly — list and read user records.
https://www.googleapis.com/auth/admin.directory.group.readonly — list and read group memberships.

Both end in .readonly. There is no path through ARIS that requests, accepts, or uses any other scope. ARIS cannot create, modify, suspend, or delete users, groups, or any other Workspace resource — Google rejects those calls because the credentials don't carry write scopes.

You can audit this at any time in Google Workspace Admin → Security → API controls → Domain Wide Delegation: the row ARIS uses lists exactly these two scopes and nothing else.

Have one Workspace super-admin do this

The service-account DWD step requires a super-admin of the Workspace tenant. The OAuth client step requires owner/editor on the Google Cloud project. The fastest path is one person with both.

1. Create or pick a Google Cloud project¶

Open the Google Cloud Console and either pick an existing project tied to your Workspace tenant or create a new one. Note the project ID.

In APIs & Services → Library, enable:

Admin SDK API (admin.googleapis.com).

That is the only API ARIS calls.

What \"enable Admin SDK API\" actually does

The name is broad — Google's Admin SDK API is the umbrella that covers user, group, org-unit, role, and licence management, including write surface. Enabling it is a project-level toggle that lets the API be called; it does not grant any credential the right to call it, and it does not give ARIS anything by itself.

What ARIS ends up with is gated separately, two steps later, in §4 Authorise domain-wide delegation: exactly the two .readonly scopes shown in the box above. Even though the umbrella API includes write methods, ARIS holds no scope that authorises them — Google rejects any call ARIS could make with a write verb.

Operators sign in to ARIS by clicking Sign in with Google in the web UI. You configure the consent flow and the OAuth client under Google Auth Platform — Google's rebranded home for what used to be split across "APIs & Services → OAuth consent screen" and "APIs & Services → Credentials → OAuth client IDs".

Open the Cloud Console's navigation menu and pick Google Auth Platform. You'll land on an Overview page with a left rail: Branding, Audience, Clients, Data access, Verification centre, Settings. You'll touch four of them, in this order.

If you don't see \"Google Auth Platform\" in the menu

Older projects still use the "APIs & Services → OAuth consent screen" / "APIs & Services → Credentials" split. The same fields exist in both UIs — map the steps below 1:1.

Reusing a project that already hosts another OAuth-using app (e.g. Keycloak)

A single Cloud project hosts one consent screen (shared Branding / Audience / Data access) and many OAuth clients (one per app). If you already configured the consent screen for another app, you can reuse it — skip 2a, 2b, 2c and go straight to 2d (Clients) to create a new client just for ARIS.

Always create a separate OAuth client for ARIS rather than reusing an existing app's. Different redirect URIs are required regardless, and separate clients let you rotate or revoke ARIS credentials without touching the other app.

The same logic applies to §3: create a fresh service account dedicated to ARIS rather than reusing one. Different keys, independent rotation.

In Audience, set User type to Internal. This is the gate that prevents anyone outside your Workspace tenant from completing the Google sign-in flow into ARIS. Save.

If the Internal option is greyed out, the Cloud project isn't tied to a Workspace organisation. Switch to a project owned by your Workspace org before continuing.

2b. Branding — name the app¶

In Branding, fill in:

App name: ARIS (or whatever your operators will recognise on the consent screen).
User support email: a Workspace user; typically the admin running this install.
Developer contact information: the same email is fine.
Authorised domains: add the domain that will host the web UI (e.g. your-domain.com). Skip for a localhost-only evaluation.
Application home page / Privacy policy / Terms of service: optional for an Internal app — leave blank if you don't have them.

Save.

2c. Data access — declare the OIDC scopes¶

In Data access → Add or remove scopes, add:

openid
.../auth/userinfo.email
.../auth/userinfo.profile

Save. ARIS does not request anything else from the OIDC flow. All three are non-sensitive scopes, so the consent screen does not trigger Google's verification flow (Internal-audience apps are exempt regardless).

2d. Clients — create the OAuth client¶

In Clients → Create client:

Application type: Web application.
Name: ARIS Web.
Authorised redirect URIs — add the URL where operators will reach the web UI, with the path /api/auth/callback/google:
- Local install: http://localhost:3001/api/auth/callback/google
- Production: https://aris.your-domain.com/api/auth/callback/google
Create.

Copy the Client ID and Client secret that appear in the dialog. You will paste them into .env as GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET. The secret is shown once — re-open the client later to Add secret if you lose it.

3. Create the service account (directory sync)¶

ARIS reads your Workspace directory once an hour to discover users and resolve who is in which group. It does this with a service account, not with the OAuth client above.

Heads-up: \"organisation policy blocks service account key creation\"

If your org enforces the GCP constraint iam.disableServiceAccountKeyCreation, the Add key → Create new key button at the end of this section will fail with that message. ARIS today needs a JSON key on disk. See Troubleshooting → Org policy blocks service-account key creation for the unblock path before you start §3.

In IAM & Admin → Service Accounts → Create service account:

Service account details: name it aris-directory-sync. Continue.
Permissions (optional) — leave empty. Click Continue. ARIS does not interact with any Google Cloud resource; this step grants GCP IAM roles (Editor, Storage Admin, etc.) which ARIS has no use for. The service account's only powers come from the Workspace-side scope grant in §4.
Principals with access (optional) — leave empty. Click Done. This step grants other GCP principals the right to impersonate this service account; ARIS uses the JSON key directly, no impersonation chain.

The "Service account created" toast confirms it exists. Open the new service account, go to the Keys tab, Add key → Create new key → JSON, and download the JSON file. Save its absolute path — you will mount it into the core container.

Note the service account's OAuth 2 client ID (long numeric string) — visible on the service-account Details tab as Unique ID. You will need it in the next step.

4. Authorise domain-wide delegation¶

The service account exists, but Workspace will not let it read your directory until you explicitly authorise it.

Switch consoles for this step

Steps §1–§3 have all been in the Google Cloud Console at console.cloud.google.com. Step §4 is the only step that happens in the Google Workspace Admin Console at admin.google.com — a separate UI with separate sign-in. Open it in a new tab; you'll come back to the Cloud Console afterwards. The Workspace admin console requires a Workspace user with Super Admin role.

In the Google Workspace Admin Console (admin.google.com), go to Security → Access and data control → API controls → Manage Domain Wide Delegation:

Add new API client.
Client ID: paste the service account's OAuth 2 client ID from step 3.

OAuth scopes (comma-separated):

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

Authorise.

These are the only two scopes ARIS uses, and both are read-only. Anyone auditing the install can verify this in the Workspace console.

5. Pick a delegate admin email¶

The Admin Directory API requires the service account to impersonate a Workspace admin. ARIS does not store the impersonated user's password — it just uses their identity for the API call.

Pick a Workspace user with Super Admin role (or at minimum a custom role with read access to users and groups). A common pattern is to create a dedicated directory-reader@<your-domain> user with Super Admin role and use it only for this — never as an operator login. You will set its address as ARIS_GOOGLE_DELEGATE_EMAIL.

Don't reuse the aris-admin@ name here

The names aris-admin@<your-domain> and aris-auditor@<your-domain> are reserved by ARIS for the role groups in §6. Using either of those addresses for the delegate user in §5 collides with §6 and makes the install harder to reason about. Pick a distinct name like directory-reader@, aris-sa-delegate@, or any internal naming convention you already use.

6. (Recommended) Create role groups¶

This step controls what someone can do inside ARIS once they've logged in. It is unrelated to §5 (which was about how the backend talks to Google).

How ARIS decides what you can do¶

Every login is given one of three permission levels — ARIS calls them scopes:

Scope	What it means
`read`	View information ARIS has collected. Read-only access to the UI.
`audit`	Everything `read` does, plus audit-trail and compliance views.
`admin`	Everything `audit` does, plus configuration changes and user management.

The default is read. Every operator who logs in gets read automatically — including you, including a Workspace Super Admin. ARIS deliberately does not look at Google's Super Admin role; it only looks at whether the user is a member of two specific groups:

In aris-admin@<your-domain> → upgraded to [read, audit, admin].
In aris-auditor@<your-domain> → upgraded to [read, audit].

§6 just creates those two groups. Without them, nobody can be a member, and everyone stays at read.

Should you do §6?¶

Skip it if you're only doing a "does this thing turn on at all" install — log in, see the home page, confirm the wiring works. Everyone will have read-only access. The install fully works; you just won't be able to use admin- or audit-gated features (today, the MVP doesn't have any, but that changes as features land).

Do it if you (or anyone) need audit or admin capabilities. You'll need to do it before any real production use, so most installs do it now.

How to do it¶

In Google Workspace Admin → Directory → Groups, create:

aris-admin@<your-domain> — add yourself for the first login.
aris-auditor@<your-domain> — leave empty for now if you don't need it.

The two group addresses are literal — ARIS string-matches aris-admin@<ARIS_GOOGLE_DOMAIN> exactly, so the names are not configurable.

You can come back and create these groups (or add yourself to them) at any time. The next directory sync picks up the change automatically; you don't need to restart anything. A 404 on either group at sync time is tolerated — the run proceeds and every user defaults to read.

What you should have at this point¶

Value	Where it goes
OAuth Client ID + Client Secret	`.env` → `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`
Service-account JSON file (absolute host path)	`.env` → `ARIS_GOOGLE_SERVICE_ACCOUNT_KEY_FILE`
Workspace domain (e.g. `acme.com`)	`.env` → `ARIS_GOOGLE_DOMAIN`
Delegate admin email	`.env` → `ARIS_GOOGLE_DELEGATE_EMAIL`

Next: Configure →