Google Workspace identity
Members → Workspace identity admits and maintains organization memberships from a verified Google Workspace directory. Google identity and a user-verified WebAuthn passkey are still required for every console session. This integration does not add a password, SAML, recovery-code or passkey-free sign-in path.
Configure the provider
The platform operator must enable the Admin SDK API in the Google Cloud project used by the console's Google OAuth client. Add this exact authorized redirect URI to that web client:
https://YOUR-CONSOLE/integrations/google-workspace/callback
Use the matching loopback HTTP address for local development. The existing server-side SPM_GOOGLE_CLIENT_ID and SPM_GOOGLE_CLIENT_SECRET remain the platform's sign-in configuration. The organization connection stores its offline refresh grant and temporary PKCE verifier in the encrypted vault; neither is returned to the browser.
Configure the Google consent screen for these scopes:
openid
email
https://www.googleapis.com/auth/admin.directory.user.readonly
https://www.googleapis.com/auth/admin.directory.domain.readonly
Google may require OAuth application verification and administrator approval for the requested Directory scopes. Testing-mode grants and revoked consent can expire. A configured, Google-verified OAuth application is an external prerequisite; this repository does not supply one or claim that local fixtures verify a real Workspace deployment.
Connect and review a policy
- Keep a manually managed organization owner with a working Google account and passkey for recovery. Directory management never takes over existing manual memberships or creates platform administrators.
- Open Members → Workspace identity. Managing identity requires
org.settings.write,members.writeandcredentials.write, plus a passkey verified within 10 minutes. - Connect Google Workspace and continue with an active Workspace super administrator. Authorization is bound to the initiating console user, session, organization and configuration revision. It expires after 10 minutes and can be consumed only once. An organization can start 10 authorizations per hour.
- Select exact verified domains and an eligible organization role. The role must be within your own permission grant and cannot administer organization identity, members, approvals or credentials. Custom roles are checked by their actual permission set.
- Preview the complete directory impact. Review the counts and example identities, then apply the immutable preview within 10 minutes. A changed directory, grant, role or policy requires another preview.
Google's verified ID-token sub identifies the account. The signed hd claim, current Directory user ID, primary email, customer ID and verified domain must agree. An email suffix by itself never proves domain ownership. A domain can be claimed by only one organization; moving it requires its current administrator to release it. The Google customer ID stays pinned across disconnection and reconnection.
This increment requires the signed hosted domain to match the Directory primary-email domain exactly. Subdomains and domain aliases are not inferred. A verified Directory identity is initially a pending entitlement; it does not create a global user until Google sign-in succeeds. The verified account then receives the reviewed organization role and completes its mandatory passkey step. Existing manual memberships are preserved.
An existing account with a different non-null Google subject cannot be claimed through a recycled email address. An active legacy account without a Google subject must prove its existing passkey before binding. A non-active legacy account that already has credentials requires administrator recovery; starting Google sign-in cannot reactivate it. A genuinely unused invited account can enroll through a current verified-email invitation; configured unused bootstrap accounts retain their existing explicit bootstrap enrollment. Ambiguous legacy rows require administrator recovery instead of silently replacing identity ownership.
Freshness, pause and recovery
The worker schedules full checks every 3 minutes. A managed membership is usable only while both its Directory evidence and the connection verification are less than 15 minutes old, the vaulted grant is active, the Google identity/domain still matches and its automatically managed role has the reviewed permission set. This is enforced for console organization/application access, organization listings, and personal Management API token origin and target organizations.
An expired or revoked grant requires reconnection and closes managed access immediately when detected. Transient Google failures, including quota responses, never extend the prior freshness window. A delayed or missing worker therefore closes managed access after 15 minutes. Manual recovery memberships remain available through the normal Google-plus-passkey flow. Global sessions keep their existing 8-hour absolute and 30-minute idle limits; removing one managed organization does not log the person out of unrelated organizations.
Pause new admissions to stop new memberships while continuing existing-member verification and deprovisioning. A confirmed suspended, archived, guest, removed or out-of-policy identity loses its managed membership and its personal tokens bound to that organization. A returned employee requires an explicit restore review; sync, Google sign-in and invitation acceptance cannot resurrect a tombstoned managed identity. Restoring a membership does not restore revoked tokens.
Changing a managed member's role requires a fresh passkey and an explanation. A non-administrative manual role stops automatic role replacement while Directory status still controls membership. A separately reviewed protected administrator role becomes a manual recovery membership. Changes to a provisioning role's permissions close automatically managed access until another policy preview approves the new set.
Disconnect requires reviewing the membership and token counts, confirming the organization slug and supplying a reason. It removes managed memberships, revokes their organization-bound personal tokens, destroys locally stored grant/verifier secrets and retains blocked identity tombstones. Manual memberships and unrelated organizations remain available. Reconnection is pinned to the same customer and does not undo tombstones. If Google no longer verifies the previous domains, reconnection clears the active domain selection and pauses admissions; managed access stays closed until a new policy is reviewed. You can also revoke the OAuth application in Google directly. The console makes no Google administration writes or remote token-revocation calls.
Capacity and retained evidence
The installation supports 20 connected directories, each with at most 1,000 Directory users, 20 selected domains and 10,000 lifetime subject records. Complete scans are bounded by page count and response size; an incomplete or oversized scan applies no partial membership changes. The worker uses four provider lanes and fair, leased batches of ten connections. Expired leases and evidence older than 60 seconds cannot be committed as newly verified. Login Directory checks use four lanes with a shared 30-second provider deadline; incomplete checks cannot refresh or grant managed access.
Directory identities are paginated in groups of 200. Names, email addresses and private review reasons require people.pii.read. Policy previews show up to 100 examples with counts across the complete bounded result. The latest 100 history entries are available for up to 90 days. Inactive identity names, emails and private reasons expire after 90 days; minimal subject tombstones remain to prevent automatic re-admission. The append-only audit ledger retains security receipts. Temporary authorizations and previews expire after 10 minutes; obsolete encrypted secrets are destroyed and revoked credential metadata is bounded. No real Google administrator mutation or message is required for local validation.