Skip to content
Event Route Optimiser Docs

CIAM Google + Microsoft Sign-In Runbook (Synkronyx)

CIAM Google + Microsoft Sign-In Runbook (Synkronyx)

1. Objective

Enable and validate customer sign-in for ERO using:

  • Google federation through Microsoft Entra External ID.
  • Microsoft-path sign-in strategy that covers both organizational accounts and consumer Microsoft email use cases.

This runbook is for Inner Loop (local), Test, and Support/Production readiness.

Companion onboarding document for customer intake and one-time setup governance:

  • docs/43-customer-google-signin-onboarding-and-marketplace-intake.md
  • docs/44-customer-google-signin-marketplace-questionnaire.md
  • docs/45-customer-google-signin-post-onboarding-automation-runbook.md
  • docs/46-customer-google-signin-marketplace-portal-copy.md

2. Ownership Decision: Is pedroneil acceptable?

Short answer:

  • Local PoC only: yes, acceptable.
  • Shared Dev/Test/Support/Prod: no, move to Synkronyx-owned identity assets.
StageGoogle Cloud ownershipAcceptable ownerRationale
Local developer PoCPersonal project[email protected]Fast bootstrap and experimentation
Shared dev/testOrganization projectSynkronyx admin/service accountTeam continuity and auditability
ProductionOrganization projectSynkronyx-controlled onlySecurity, legal, and recoverability

Recommended baseline from day one:

  • Create a Synkronyx-owned Google Cloud project and OAuth consent/app branding.
  • Add at least two Synkronyx admins to prevent lockout.

3. Microsoft Sign-In Strategy (Important)

Microsoft account (live.com) customer sign-in is supported in External ID by configuring Microsoft account as an OpenID Connect identity provider, then attaching it to a user flow.

Use these patterns intentionally:

  1. MSA customer sign-in (recommended for live.com): Configure Microsoft account (live.com) OIDC and expose it in the user flow.
  2. Work/school federated sign-in: Add a Microsoft Entra ID tenant as a separate custom OIDC provider.
  3. Fallback path: Keep local account methods (Email + Password or Email OTP) enabled for operational resilience.

4. Prerequisites

  • Synkronyx Entra External ID tenant(s):
    • sknxerodev for non-production
    • sknxeroprod for support/production
  • ERO app registrations aligned with existing taxonomy:
    • ero-dev, ero-test, ero-supp, ero-prod
  • Access roles:
    • External Identity Provider Administrator (or equivalent)
    • Application Administrator
  • Local tooling:
    • Azure CLI (az)
    • Node.js/NPM
    • Optional: Google Cloud SDK (gcloud) for scripted bootstrap

5. Bootstrap Azure + Entra Context

From repository root:

Terminal window
./join-project.ps1 -Environment dev
./scripts/first-run-azure.ps1 -Environment dev

Then verify your active tenant/subscription context:

Terminal window
az account show --output table

6. Bootstrap Google Cloud Project (Synkronyx-first)

Cloud foundation order for Synkronyx:

  1. Create Google Cloud Identity or Google Workspace for synkronyx.com.
  2. Verify synkronyx.com ownership in Google Admin.
  3. Create at least two Synkronyx-managed admin accounts.
  4. Use Synkronyx-managed identities for ownership of projects and OAuth assets.

Minimal manual signup path:

  1. Open https://cloud.google.com/identity and choose Cloud Identity.
  2. Select business onboarding with your existing domain.
  3. Enter synkronyx.com and complete domain verification with DNS TXT record.
  4. Create primary admin account under synkronyx.com.
  5. Sign in to Google Admin and confirm domain verification state is active.

If using CLI:

Terminal window
gcloud auth login
gcloud projects create sknx-ero-auth-dev --name="SKNX ERO Auth Dev"
gcloud config set project sknx-ero-auth-dev

Use the project script to standardize environment loading, Google project setup, redirect URI generation, and optional secret handling.

From repository root:

Terminal window
./scripts/deploy/bootstrap-google-oauth.ps1 -Environment dev -EnsureGoogleApiKey

What this script does:

  1. Loads settings/.env.local, optional settings/.env.nonprod.local, and settings/.env.<env>.local.
  2. Resolves tenant values from PUBLIC_SKNX_ERO_TENANT_ID and PUBLIC_SKNX_ERO_TENANT_DOMAIN (or explicit parameters).
  3. Creates/selects Google project (sknx-ero-auth-<env> by default) and sets active gcloud project.
  4. Enables required Google APIs for bootstrap automation.
  5. Generates a first-class Google API key when -EnsureGoogleApiKey is passed.
  6. Generates the Entra-compatible redirect URI manifest file: settings/google-redirect-uris-<env>.txt.
  7. Writes baseline metadata keys (SKNX_ERO_GOOGLE_PROJECT_ID, SKNX_ERO_GOOGLE_API_KEY_SECRET_NAME, SKNX_ERO_GOOGLE_OAUTH_REDIRECT_URI_FILE) into settings/.env.<env>.local.
  8. Stages secret values in settings/.env.<env>.local immediately before Key Vault synchronization.
  9. Stores secret values in Azure Key Vault first by default, then clears local secret values in non-offline mode.

Example with explicit values and Key Vault secret publication:

Terminal window
./scripts/deploy/bootstrap-google-oauth.ps1 \
  -Environment dev \
  -GoogleProjectId sknx-ero-auth-dev \
  -GoogleProjectName "SKNX ERO Auth Dev" \
  -EnsureGoogleApiKey \
  -GoogleClientId "<google-client-id>" \
  -GoogleClientSecret "<google-client-secret>" \
  -KeyVaultName "kv-sknx-identity-dev" \
  -PersistClientSecretLocally

Notes:

  • Google OAuth consent-screen lifecycle and first-time app verification can still require Console actions.
  • If you already have a Google project, use -SkipProjectBootstrap and only generate manifest/env updates.
  • Use -OfflineMode only when Key Vault access is unavailable and temporary local secret fallback is required.

6.2 Configure Synkronyx Entra as Google Workforce IdP

Use this when Synkronyx workforce sign-in to Google must use Entra:

  1. In Google Admin Console, open Security > Authentication > SSO with third-party IdP.
  2. In Microsoft Entra, create enterprise application for Google Cloud or custom SAML app.
  3. Configure SAML identifiers and reply URLs from Google SSO setup page.
  4. Download Entra federation metadata or certificate and provide it to Google SSO configuration.
  5. Set sign-in page URL and sign-out URL from Entra SAML endpoints.
  6. Map NameID to Synkronyx primary email format used in Google accounts.
  7. Enable SSO first for a pilot organizational unit.
  8. Validate admin and user sign-in flows before organization-wide rollout.

In Google Cloud Console:

  1. Open APIs & Services > OAuth consent screen.
  2. Set user type to External.
  3. Use Synkronyx branding and Synkronyx support contact email.
  4. Add required authorized domains (for Entra federation this includes ciamlogin.com and microsoftonline.com).

7. Create Google OAuth Client for Entra Federation

In Google Cloud Console:

  1. Credentials > Create credentials > OAuth client ID.
  2. Application type: Web application.
  3. Add redirect URIs using your Entra external tenant details.

Use Microsoft Learn’s current URI set pattern (replace placeholders):

  • https://login.microsoftonline.com
  • https://login.microsoftonline.com/te/<tenant-ID>/oauth2/authresp
  • https://login.microsoftonline.com/te/<tenant-subdomain>.onmicrosoft.com/oauth2/authresp
  • https://<tenant-ID>.ciamlogin.com/<tenant-ID>/federation/oidc/accounts.google.com
  • https://<tenant-ID>.ciamlogin.com/<tenant-subdomain>.onmicrosoft.com/federation/oidc/accounts.google.com
  • https://<tenant-subdomain>.ciamlogin.com/<tenant-ID>/federation/oauth2
  • https://<tenant-subdomain>.ciamlogin.com/<tenant-subdomain>.onmicrosoft.com/federation/oauth2

Capture:

  • Google Client ID
  • Google Client Secret

8. Configure Google IdP in Entra External ID

Preferred automated path:

Terminal window
./scripts/deploy/bootstrap-google-oauth.ps1 -Environment dev -SkipProjectBootstrap -EnsureGoogleApiKey

This updates or creates the tenant-level Google provider in the target CIAM tenant by using Microsoft Graph through Azure CLI authentication. The script intentionally does not modify Microsoft account (MSA) provider configuration.

In Entra admin center (external tenant):

  1. Entra ID > External Identities > All identity providers.
  2. Built-in tab > Google > Configure.
  3. Paste Google Client ID/Secret.
  4. Save.

9. Configure User Flow

Standard naming convention (recommended):

  • Dev: B2C_1_SUSI_ERO_DEV
  • Test: B2C_1_SUSI_ERO_TEST
  • Prod: B2C_1_SUSI_ERO_PROD

Keep the SUSI token consistent (Sign Up and Sign In) across all environments.

Optional automated binding for a specific user flow:

Terminal window
./scripts/deploy/bootstrap-google-oauth.ps1 -Environment dev -SkipProjectBootstrap -UserFlows B2C_1_SUSI_ERO_DEV
./scripts/deploy/bootstrap-google-oauth.ps1 -Environment test -SkipProjectBootstrap -UserFlows B2C_1_SUSI_ERO_TEST
./scripts/deploy/bootstrap-google-oauth.ps1 -Environment prod -SkipProjectBootstrap -UserFlows B2C_1_SUSI_ERO_PROD

To skip flow binding and only configure the tenant-level Google provider:

Terminal window
./scripts/deploy/bootstrap-google-oauth.ps1 -Environment dev -SkipProjectBootstrap -SkipUserFlowBinding
  1. External Identities > User flows > create/select sign-up/sign-in flow.
  2. Identity providers:
    • Enable Google.
    • Enable local account method (Email with password or Email OTP).
    • Add custom OIDC provider only if required for Microsoft organizational federation.
  3. Add required user attributes (minimal by default: display name, email).

9.1 Configure MSA (live.com) OIDC Provider

A. Create Microsoft account application

  1. In an Entra tenant where you can register apps, create a new app registration.
  2. Supported account types: Accounts in any organizational directory and personal Microsoft accounts.
  3. Add the redirect URI required by the External ID OIDC setup flow.
  4. Record the Application (client) ID and Client secret value.

B. Add Microsoft account as OIDC provider in External ID tenant

  1. In the ERO external tenant, open Entra ID > External Identities > All identity providers.
  2. On Custom, choose Add new > OpenID Connect.
  3. Configure with these values: Display name = Microsoft account, Well-known endpoint = https://login.microsoftonline.com/consumers/v2.0/.well-known/openid-configuration, OpenID Issuer URI = https://login.live.com, Client ID = MSA app Application ID, Client Secret = MSA app secret value, Client authentication = client_secret, Scope = openid profile email, Response type = code.
  4. Save provider.

C. Add MSA provider to the user flow

  1. Open External Identities > User flows.
  2. Select the ERO sign-up/sign-in flow.
  3. Open Identity providers.
  4. Under Other identity providers, enable the Microsoft account provider.
  5. Save.

10. Configure ERO App Settings

Set in environment file (settings/.env.dev.local or equivalent):

  • PUBLIC_SKNX_ERO_CLIENT_ID
  • PUBLIC_SKNX_ERO_TENANT_ID
  • PUBLIC_SKNX_ERO_TENANT_DOMAIN
  • PUBLIC_SKNX_ERO_API_SCOPE
  • PUBLIC_SKNX_ERO_AUTH_MOCK

Guidance:

  • Local inner loop with live IdP tests: set PUBLIC_SKNX_ERO_AUTH_MOCK="false".
  • Mock mode should remain for offline-only development, not federation validation.

11. Test Plan

11.1 Local Inner Loop

  1. Start services with ./scripts/bootstrap.ps1 -SkipAzure -SkipTerraform.

  2. Open http://localhost:4321.

  3. Use CIAM panel to sign in.

  4. Validate:

    • Google login roundtrip succeeds.
    • Access token attached to /api/* calls.
    • /api/data hydrate works.

11.2 Microsoft-path Tests

Run both tracks:

  1. MSA upstream OIDC sign-in with a real live.com/outlook.com Microsoft account.
  2. If enabled, separate custom OIDC Entra federation with a work/school account tenant.
  3. Optional local-account sign-in with Microsoft-hosted email address for fallback-path verification.

Track expected behavior explicitly so teams do not confuse local-account email sign-in with true upstream MSA federation.

11.3 Cloud Outer Loop

  1. Deploy to dev cloud endpoint.
  2. Confirm mock token bypass is disabled.
  3. Verify JWT signature validation and scope enforcement at Worker edge.

12. Promotion Gates (Dev -> Test -> Support -> Prod)

  • IdP ownership is Synkronyx-controlled.
  • At least two admins per Google OAuth project.
  • Redirect URIs match target environment exactly.
  • User flow locked and reviewed.
  • App registrations and secrets tracked in governed vault/process.
  • End-to-end sign-in and token validation evidence captured.

13. Troubleshooting Notes

  • If Google sign-in option doesn’t appear: verify Google IdP is enabled in the specific user flow.
  • If redirect mismatch errors occur: re-check every configured redirect URI and tenant placeholders.
  • If email-claim errors occur on external OIDC providers: confirm claim mapping and, if needed, make email optional at user-flow level per current Entra guidance.

14. References

  • Microsoft Entra External ID: Identity providers for external tenants
  • Microsoft Entra External ID: Add MSA for customer sign-in
  • Microsoft Entra External ID: Add Google as identity provider
  • Microsoft Entra External ID: Add custom OIDC provider
  • Microsoft Entra External ID: Create sign-up/sign-in user flow
  • Google OAuth 2.0 documentation