Customer Google Sign-In Onboarding

1. Purpose

Define the end-to-end onboarding lifecycle for customers who require Google sign-in for ERO through Microsoft Entra External ID.

This document is the single source for the intake field catalogue, the customer-facing questionnaire, the marketplace portal copy, the one-time manual setup walkthrough, and the post-onboarding automation runbook.

2. Scope

This document applies to:

Customer Google Workspace or Cloud Identity tenants.
ERO identity integration through Microsoft Entra External ID.
Initial onboarding for one pilot user and controlled rollout.
Automated group lifecycle after pilot acceptance.

This document does not replace the technical implementation detail in:

ERO Operations

3. Key Principle: Why one Google API key is not enough

Google API keys are not sufficient for identity administration tasks required for enterprise SSO.

Google sign-in federation and group administration require authenticated admin authority, usually through OAuth credentials and delegated privileges, not a generic project API key.

For Google sign-in onboarding, the minimum identity credential pair is:

Google OAuth Client ID
Google OAuth Client Secret

For automated group synchronization after onboarding, the customer may also provide a delegated admin automation credential set. See section 10.

4. Delivery model

The delivery model has two phases:

One-time manual setup for trust establishment and first validation.
Post-validation automation for repeatable operations such as group sync, membership updates, and compliance checks.

5. Intake field catalogue

This catalogue is authoritative. The questionnaire in section 6 and the portal form in section 7 both draw their fields from this table. The customer must submit all required fields before deployment scheduling.

5.1 Organization profile

Field label	Required	Help text	Validation	Example
Legal organization name	Yes	Enter the full registered legal name of your organization.	2 to 120 characters.	Contoso Manufacturing Ltd
Primary business domain	Yes	Enter the domain used by your workforce identities.	Valid domain format.	contoso.com
Primary deployment region	Yes	Enter the preferred primary hosting region for your deployment.	Free text or controlled list.	UK South
Technical owner name and email	Yes	Enter the person who will support configuration and validation tasks.	Valid email format.	-
Security owner name and email	Yes	Enter the approver responsible for identity and access decisions.	Valid email format.	-

5.2 Google identity profile

Field label	Required	Help text	Validation	Example
Google tenant type	Yes	Select your tenant type.	Must be one of Cloud Identity Premium or Google Workspace.	Cloud Identity Premium
Verified Google domain	Yes	Enter the verified domain used in Google Admin.	Valid domain format.	contoso.com
Google super admin email	Yes	Enter the account used for Google identity configuration sessions.	Valid email format.	google-admin at contoso dot com
Google break-glass admin email	Yes	Enter the emergency admin account that remains available if SSO is disabled.	Valid email format.	google-breakglass at contoso dot com
Break-glass test confirmation	Yes	Confirm that local sign-in for the break-glass account is tested and working.	Boolean checkbox.	true

5.3 Google federation credentials

A Google API key is not sufficient for Google sign-in federation. See section 3.

Field label	Required	Help text	Validation	Example
Google OAuth project ID	Yes	Enter the Google Cloud project ID that contains the OAuth client used for Entra federation.	6 to 63 characters, lowercase letters, numbers, and hyphens.	contoso-identity-prod
Google OAuth Client ID	Yes	Enter the OAuth Client ID for the web application used with Entra.	Non-empty string.	-
Google OAuth Client Secret reference	Yes	Provide a secure reference to the secret location. Do not paste a raw secret value in this form.	Non-empty string.	keyvault://kv-customer-identity/secrets/google-oauth-client-secret
OAuth consent support email	Yes	Enter the support email configured on the Google OAuth consent screen.	Valid email format.	id-admin at contoso dot com

5.4 Entra context

Field label	Required	Help text	Validation	Example
Entra tenant ID	Yes	Enter the tenant ID where ERO External ID configuration will be applied.	GUID format.	11111111-2222-3333-4444-555555555555
Entra tenant domain	Yes	Enter the primary Entra tenant domain.	Domain format.	contosoexternal.onmicrosoft.com
Target user flow name	Yes	Enter the user flow that will be used for Google pilot sign-in.	Non-empty string.	B2C_1_SUSI_ERO_DEV
Approve Google provider in user flow	Yes	Confirm approval to enable the Google identity provider for the specified user flow.	Boolean checkbox.	true

5.5 Pilot scope

Field label	Required	Help text	Validation	Example
Pilot user email	Yes	Enter the first pilot account for sign-in validation.	Valid email format.	pilot-user at contoso dot com
Pilot group name	Yes	Enter the group name used to constrain pilot access.	Non-empty string.	grp-contoso-google-sso-pilot-users
Pilot start window UTC	Yes	Enter the planned start date and time in UTC.	ISO 8601 datetime.	2026-08-10T09:00:00Z
Pilot end window UTC	Yes	Enter the planned end date and time in UTC.	ISO 8601 datetime.	2026-08-10T11:00:00Z
Local fallback enabled during pilot	Yes	Confirm local fallback sign-in remains enabled during pilot execution.	Boolean checkbox.	true

5.6 Governance approvals

Field label	Required	Help text	Validation	Example
Identity change approver	Yes	Enter the name and email of the approver for identity changes.	Non-empty string.	Sarah Patel, sarah-patel at contoso dot com
Rollback approver	Yes	Enter the name and email of the approver who can authorize rollback.	Non-empty string.	David Lee, david-lee at contoso dot com
Approved change window UTC	Yes	Enter the approved implementation window in UTC.	Time range format or two datetime fields.	2026-08-10T09:00:00Z to 2026-08-10T11:00:00Z

5.7 Optional automation onboarding

Complete this section only when the customer wants automated group lifecycle from day one.

Field label	Required	Help text	Validation	Example
Automation requested	No	Select true to request automated Entra-to-Google group synchronization after pilot acceptance.	Boolean checkbox.	false
Delegated admin email for automation	No	Enter the delegated admin account used by automation for Google Admin SDK operations.	Valid email format.	automation-admin at contoso dot com
Service account identifier	No	Enter the service account identifier used for Google automation.	Non-empty when Automation requested is true.	service-account-id-placeholder
Approved Admin SDK scopes	No	Enter the approved scopes used by automation.	Array of scope strings.	[“https://www.googleapis.com/auth/admin.directory.group”]
Automation secret reference	No	Provide the secure location reference for automation credentials.	Non-empty when Automation requested is true.	keyvault://kv-customer-identity/secrets/google-adminsdk-credential

5.8 Secret handling rule

Secrets must never be entered as plain text into email or ticket comments.
Secrets must be exchanged through an approved secret handoff channel.
Forms must capture a secret reference, never a raw secret value.

6. Customer-facing questionnaire

Use the field catalogue in section 5 as the question set. This section defines the rules and attestations that wrap it.

6.1 Submission rules

Customer must submit all required fields in the catalogue.
Customer must not send secrets in plain text email.
Customer must provide secret values through an approved secret handoff channel.
Customer must provide at least one named technical owner and one named security approver.
Customer must confirm that both Google admin accounts can sign in locally to Google Admin.

6.2 Customer attestation

Customer must confirm the statements below:

We confirm domain ownership and identity admin authority.
We confirm Google OAuth values are correct for the target tenant.
We confirm the break-glass account is tested and operational.
We confirm local fallback is approved for pilot safety.
We confirm listed approvers are authorized for change and rollback decisions.

Signature name and signature date in UTC must both be captured.

6.3 Internal Synkronyx intake check

The Synkronyx delivery owner must verify:

Required sections are complete.
Secret references are reachable.
Pilot scope is constrained.
Rollback path is approved.
Customer attestation is signed.

7. Marketplace portal copy

7.1 Form introduction text

Use this as the form header description:

Provide the details below so Synkronyx can onboard Google sign-in safely and complete pilot validation before deployment. All required fields must be completed before scheduling.

Field labels, help text, validation rules, and examples are defined in the catalogue in section 5 and must be used verbatim in the portal form builder.

7.2 Portal validation rules

If Automation requested is true, all optional automation fields become required.
If Google tenant type is missing, block submission.
If the OAuth secret field appears to contain a raw secret value, block submission and instruct the customer to provide a secret reference.
If pilot dates are invalid, or the end is earlier than the start, block submission.

7.3 Customer confirmation text

Use this confirmation checkbox label:

I confirm that the information provided is accurate and that listed approvers are authorized to approve identity changes and rollback actions.

7.4 Internal handoff note

After submission, route the record to:

Synkronyx delivery lead for technical completeness review.
Synkronyx security reviewer for approval-gate validation.
Implementation scheduling queue when both reviews are complete.

8. One-time manual setup walkthrough

8.1 Customer-side manual steps

Customer identity administrators must complete:

Verify domain ownership in Google Admin console.
Confirm two local Google admin accounts exist: one platform admin account and one break-glass account.
Create the OAuth web application client in Google Cloud Console following the playbook in section 8.4.
Provide the OAuth Client ID and Client Secret through an approved secret channel.
Confirm the pilot user account and test window.

8.2 Synkronyx-side manual steps

The Synkronyx implementation team must complete:

Configure the Google identity provider in Entra External ID following section 8.5.
Bind the Google provider to the target ERO user flow following section 8.6.
Configure application redirect URIs and environment secret settings.
Confirm sign-in for one pilot user.
Confirm the local fallback path remains available.

8.3 Playbook: Google Cloud Console OAuth web client creation

When creating the OAuth client for Entra External ID federation in Google Cloud Console:

Open Google Cloud Console and select the target auth project, for example sknx-ero-auth-nonproduction.
Navigate to APIs and Services > Credentials.
Select Create Credentials and choose OAuth client ID.
Set Application type to Web application.
Set Name to a descriptive label, for example ERO Nonproduction Google Sign-In.
Under Authorized JavaScript origins, select Add URI and enter the active Entra auth origin.

Branded origin, after the custom auth domain is attached:
- https://login.synkronyx.com
Temporary bootstrap origin, before the custom auth domain is attached:
- https://sknxerononproduction.ciamlogin.com
Under Authorized redirect URIs, select Add URI and add the exact callback endpoints matching the active auth origin, tenant ID, and tenant domain.

Branded callbacks, after the custom auth domain is attached:
- https://login.synkronyx.com/78ddb811-8ab7-4d7b-bfb8-c3d96e04d00d/federation/oauth2
- https://login.synkronyx.com/sknxerononproduction.onmicrosoft.com/federation/oauth2
Temporary bootstrap callbacks, before the custom auth domain is attached:
- https://sknxerononproduction.ciamlogin.com/78ddb811-8ab7-4d7b-bfb8-c3d96e04d00d/federation/oauth2
- https://sknxerononproduction.ciamlogin.com/sknxerononproduction.onmicrosoft.com/federation/oauth2
Select Create and record the generated Client ID and Client Secret.

The ciamlogin.com callback values are temporary bootstrap values only. Do not use them for customer-facing sign-up after login.synkronyx.com is attached to the CIAM tenant.

8.4 Playbook: Entra External ID provider configuration

To attach the Google identity provider to the external tenant:

Open Microsoft Entra admin center for the target CIAM tenant.
Navigate to External Identities > All identity providers.
Select Google from the list of social identity providers.
Enter the Client ID and Client Secret generated in Google Cloud Console.
Select Save.

8.5 Playbook: Linking Google provider to user flow

To enable Google sign-in on the sign-up and sign-in flow:

Navigate to External Identities > User flows.
Select the target user flow, for example ero-sign-up-sign-in-nonproduction or B2C_1_SUSI_SKNXR_NONPROD.
Select Identity providers from the left menu.
Check Google in the provider list and select Save.

Run the tenant readiness verification script to confirm flow binding:

./platform/automation/powershell/test-ciam-tenant-readiness.ps1 -Tier nonproduction

8.6 Group design baseline

For each onboarding, create the following logical groups:

Entra pilot users group.
Entra SSO operators group.
Google pilot users group.
Google local admin group.
Google break-glass admin group.

Source-of-truth rule:

Entra groups must be source of truth for workforce identity lifecycle.
Google groups must exist for Google-side authorization and service entitlements.

9. Validation, rollback, and evidence

9.1 Validation and sign-off checklist

All checks must pass before customer go-live:

Pilot user can sign in through the Google path and complete ERO sign-up or sign-in.
Local fallback identity path is functional.
Break-glass account sign-in is verified.
User flow shows only approved identity providers.
Customer security owner confirms evidence.

9.2 Rollback criteria

Rollback must be executed if any of the following occur:

Pilot user cannot complete the authentication round trip.
Admin access path is degraded.
Unexpected user population is exposed to the new SSO path.

Rollback action baseline:

Remove or disable the Google provider binding from the affected user flow.
Revert pilot assignments.
Re-run validation on local fallback and break-glass paths.

9.3 Evidence pack required at completion

Store these artifacts in the deployment record:

Completed intake form.
Redacted sign-in validation screenshots.
User flow configuration export or screenshots.
Go-live approval message from the customer security approver.
Rollback plan confirmation.

9.4 Intake form payload template

Use this template as the canonical intake form payload.

customerOrganization: ""
primaryDomain: ""
deploymentRegion: ""

technicalOwnerEmail: ""
securityOwnerEmail: ""

googleTenantType: "Cloud Identity Premium|Google Workspace"
googleVerifiedDomain: ""
googleSuperAdminEmail: ""
googleBreakGlassEmail: ""
googleOAuthProjectId: ""
googleOAuthClientId: ""
googleOAuthClientSecretReference: ""

entraTenantId: ""
entraTenantDomain: ""

pilotUserEmail: ""
pilotScopeConfirmed: true
localFallbackConfirmed: true

changeWindowUtc: ""
identityChangeApprover: ""
rollbackApprover: ""

automationRequested: false
googleAutomationDelegatedAdminEmail: ""
googleAutomationServiceAccountId: ""
googleAutomationScopes: []
googleAutomationSecretReference: ""

10. Post-onboarding automation runbook

10.1 Entry criteria

Automation can start only when all criteria are true:

Manual onboarding checklist is complete.
Pilot user sign-in test passed.
Break-glass account sign-in test passed.
Local fallback sign-in test passed.
Customer change approval is recorded.

10.2 Control model

Entra groups are the source of truth for workforce lifecycle.
Google groups are target objects for Google-side authorization.
Synchronization is one-way from Entra to Google unless explicitly approved otherwise.

10.3 Required automation credentials

Customer must provide:

Google service account identifier used for Admin SDK operations.
Domain-wide delegation approval for required scopes.
Delegated admin user email for automation.
Secret reference for service account credential material.

Synkronyx must provide:

Entra app registration for Graph automation.
Tenant-scoped credential with least privilege.
Secret or certificate reference in an approved secret store.

10.4 Minimum permission set

Google side:

Group create and update.
Group membership create and update.
Read access for user and group lookup.

Entra side:

Read group definitions.
Read group memberships.
Read user identity attributes required for group sync.

10.5 Group mapping contract

Use a deterministic mapping file with explicit source and target group names.

Minimum schema:

groupMappings:
  - sourceEntraGroup: ""
    targetGoogleGroup: ""
    mode: "mirror"

Rules:

Every mapping entry must be unique.
Every target Google group must be pre-approved by the customer security owner.
Deletion behavior must be explicit and disabled by default.

10.6 Execution phases

Phase A, preflight:

Validate credentials can authenticate to Entra and Google.
Validate target tenant and domain values.
Validate mapping file structure.
Generate a preflight report.

Phase B, dry run:

Compute group creation actions.
Compute membership additions.
Compute membership removals.
Export planned actions without writing changes.

Phase C, apply:

Create missing Google groups.
Add missing Google group memberships.
Remove out-of-policy memberships only when the customer approved removal mode.
Write an audit log with correlation ID.

Phase D, validate:

Re-read Google groups.
Compare observed state to expected state.
Publish a pass or fail summary.

10.7 Automation rollback model

Rollback must support:

Restore memberships from the pre-apply snapshot.
Disable the sync execution schedule.
Revert mapping changes made in the current release.

Rollback trigger conditions:

High-impact mismatch in group membership.
Authentication failure during apply.
Customer request to halt deployment.

10.8 Logging and evidence

Every run must produce:

Preflight report.
Dry-run action report.
Apply action log with correlation ID.
Validation report.
Final status summary.

Evidence must be stored in the deployment record.

10.9 Operational cadence

Recommended cadence:

Hourly sync during pilot.
Every 15 minutes after production stabilization.

Cadence must be approved by the customer security and operations owners.

10.10 Security guardrails

Secrets must be read from an approved secret store only.
Credentials must not be printed in logs.
Automation identity must use least privilege.
Emergency stop must be available through a configuration flag.

10.11 Handoff checklist

Synkronyx can mark automation handoff complete only when:

Mapping file is approved by the customer.
Dry run is accepted by the customer.
Apply run passed validation.
Rollback drill is completed once.
Customer operations owner signed off.