Prepare and test your skills
Prepare and test your skills
Diagnosing synchronization and single sign-on (SSO) integration issues means tracing a failure to its layer — directory read, Google write, or Security Assertion Markup Language (SAML) authentication — and fixing the configuration at that layer. Google Cloud Directory Sync (GCDS) (opens in a new tab) provisions users and groups from Active Directory to Cloud Identity (opens in a new tab) or Google Workspace, while SSO delegates authentication back to an external identity provider (IdP) such as Active Directory Federation Services (AD FS) (opens in a new tab) using SAML 2.0. GCDS does not synchronize passwords, so SSO succeeds only when the user exists in Cloud Identity and has a matching identity in the external IdP.
GCDS sync logging is the primary record for identifying provisioning failures and unwanted changes. GCDS writes activity to a timestamped log file such as PROGRAM_DATA\gcds\gcds_sync.#{timestamp}.log and can send notifications by email through a configured mail server. The log separates proposed actions during testing from completed actions during enforcement, which helps distinguish mapping errors from authorization or connectivity errors.
GCDS supports two execution modes that must be used in order. Simulation reports what GCDS would do without changing Cloud Identity, while a provision run applies changes permanently. Always select Clear cache before either mode so results reflect current Active Directory data rather than cached state.
| Mode | Effect on Cloud Identity | What to review |
|---|---|---|
| Simulate sync | No changes performed | Proposed changes section for unwanted deletes, suspends, or creates |
| Sync and apply changes | Permanent user and group changes | Successful user changes and Failures sections for created objects and errors |
After simulation shows only expected creates and updates, trigger initial provisioning with a small subset of users by narrowing the Lightweight Directory Access Protocol (LDAP) search rule. Avoid repeatedly modifying or deleting large numbers of users during testing, because bulk deletes and suspends can be flagged as abusive behavior.
GCDS provisioning depends on two authenticated connections with different trust boundaries. Traffic from GCDS to Active Directory flows over LDAP to a global catalog server, while traffic from GCDS to Cloud Identity flows over HTTPS to the Directory API and Domain Shared Contacts API. By default Active Directory uses unencrypted LDAP, so remote access from Google Cloud should use encrypted communication with LDAPS (LDAP over SSL) or Cloud VPN, while GCDS-to-Google traffic over HTTPS typically needs little firewall change.
Authentication failures on either side stop synchronization before any mapping logic runs. GCDS authenticates to Google with an OAuth refresh token stored in its XML configuration file, which must be secured in a restricted folder such as $Env:ProgramData\gcds, and authenticates to Active Directory with a dedicated domain user such as gcds. GCDS authenticates to Google as a dedicated Cloud Identity user such as cloud-directory-sync that holds the Super Admin role. Use Test connection in Configuration Manager to validate the LDAP hostname, port, authentication type, and authorized user before investigating mappings.
Most provisioning failures after successful connection are attribute mapping or scope errors:
userPrincipalName in one environment and mail in another, or where domain substitution is enabled without replacing LDAP email domains with the Google domain.givenName and sn, or where alias sync through proxyAddresses is left enabled when aliases should not be provisioned.gcds service account itself.409 Conflict when the IdP sends duplicate values for google.subject or google.group, or non-unique userName or displayName values.A standard LDAP search rule matches only active person users and excludes the sync account, for example (&(objectCategory=person)(objectClass=user)(!(userAccountControl:1.2.840.113556.1.4.803:=2))(!(userPrincipalName=gcds@*))) with scope Sub-tree and an empty Base DN to search all domains in the forest. When only some users fail, compare the failing objects against this filter and against the configured Email Address Attribute to determine whether the failure is exclusion by scope or rejection by duplicate or malformed claim value.
The SAML SSO authentication flow is the ordered message exchange between the browser, Google Sign-In, and the external IdP that makes redirect failures and authentication loops diagnosable. The flow uses SAML 2.0 HTTP POST binding with Google as the SAML service provider and the external IdP as the SAML IdP. Workforce Identity Federation (opens in a new tab) uses a related Service Provider Initiated flow where Google SecOps looks up IdP information in a workforce identity pool before redirecting to the third-party IdP.
The ordered Cloud Identity and Google Workspace flow is:
RelayState and SAMLRequest parameters.google.com, or google.com/a/DOMAIN when domain-specific issuer is used.https://www.google.com/a/example.com/acs, completing sign-in.For AD FS, the same trust is represented on both sides by paired identifiers. The SAML SSO profile in the Admin console holds the IdP entity ID such as https://ADFS/adfs/services/trust, sign-in URL such as https://ADFS/adfs/ls/, sign-out URL, and password-change URL, while the AD FS relying party trust holds the Google Entity ID and ACS URL copied from that profile. The relying party trust must be Claims aware, must enable support for the SAML 2.0 WebSSO protocol with the correct ACS URL, and must list the Google Entity ID as a relying party identifier. For Workforce Identity Federation, the SAML assertion returns to the workforce pool for attribute mapping with Common Expression Language (CEL) into google.subject, google.display_name, and google.groups before access is granted.
Certificate, entity ID, and claim failures are the three common causes of broken SSO trust and rejected assertions. An expired or missing verification certificate breaks signature validation between Google and the IdP, so upload the current IdP signing certificate to the SAML profile and update the AD FS trust before expiration. An incorrect entity ID or ACS URL breaks routing of the assertion, which can appear as a missing login screen during Test SSO setup or as Verification failure: missing session ID in request when ACS and Entity ID base URLs are incorrect. Always test SSO by opening Test SSO setup in a private or incognito window; if no IdP login screen appears, correct the IdP application configuration before saving the new provider.
Claim and authorization failures occur after the assertion reaches Google:
403 when accessing Google SecOps.?aadOptscim062020, or where user and group access fails after silent sync delays.To reduce token size, use Debug IdP Token on the workforce provider details page and filter the groups claim at the provider to send only groups required for Google SecOps, such as by prefix filtering in Microsoft Entra ID. To resolve SCIM token exhaustion, list existing tokens for the workforce pool, provider, and SCIM tenant, delete an unused token, and retry creation. To resolve PATCH failures, append ?aadOptscim062020 to the Tenant URL base URI, test the connection, and save. A critical safeguard is to keep break-glass access outside SSO: super admins can bypass SSO, and the dedicated GCDS service user should be exempted from SSO and protected with 2-step verification so an SSO outage does not block GCDS re-authorization.
Exam tip: Update IDP group mapping to reference groups in the new IdP before changing the SSO provider, because skipping that order causes HTTP 403 even when SAML authentication itself succeeds.
Single sign-on with a third-party identity provider lets workforce users sign in once at their home IdP and then access Google Cloud without a separate Google password. Workforce Identity Federation provides this SSO bridge by establishing trust between an external IdP and Google Cloud. Once that trust is configured, the external identity becomes the authenticated principal for console, command-line, and API access, and Identity and Access Management (IAM) controls what that principal can do.
Workforce Identity Federation is the trust configuration that lets an external IdP authenticate workforce employees, partners, and contractors for Google Cloud services. The administrator configures federation in the Google Cloud project, defines a workforce pool and provider that represents the external IdP, and then represents workforce pool users in IAM policies to grant roles. The authentication flow moves from Google Cloud to the external IdP and back: a user who is not signed in is directed to an authentication portal, specifies the workforce pool provider name, signs in at the external IdP, and is then redirected back to the requested Google Cloud interface. When using an external IdP with the command line, the user must first sign in to the gcloud CLI with a federated identity before running other commands.
Authorizing external identities to Component Gateway interfaces shows how federated SSO is granted for a specific workload interface. Managed Service for Apache Spark, formerly Dataproc on Compute Engine for clusters and Google Cloud Serverless for Apache Spark for serverless, runs component web interfaces on the first master node of a cluster. If Workforce Identity Federation is configured in the project, external identity users can use the Google Cloud console, Google Cloud CLI, and the Managed Service for Apache Spark API for most features.
External identities cannot use the following restricted features:
To allow an external identity to open Managed Service for Apache Spark Component Gateway (opens in a new tab) URLs, complete the federation and authorization dependencies in order:
dataproc.clusters.use role so the IAM policy permits Component Gateway use.Only a principal authenticated with an external identity can open the URL for external identities, which uses the format https://UNIQUE_ID-dot-dataproc.byoid.googleusercontent.com. If that user visits the URL while not signed in, Google Cloud redirects the user first to the authentication portal for the workforce pool provider name, then to the external IdP for sign-in, and then back to the component web interface.
Service account impersonation is the act of an authenticated principal authenticating as a service account to gain that service account's permissions. Impersonation always involves two identities: the authenticated principal who initiates the request and the service account that is impersonated. The principal first obtains a token for the service account and then uses that token to authenticate as the service account, so most audit logs record both the principal identity and the impersonated service account identity.
A principal can obtain the impersonated credential in three ways:
--impersonate-service-account flag or impersonate-service-account property, which makes the CLI create short-lived credentials for the service account and run the command with those credentials.Authentication without impersonation involves only one authenticated identity. A workload that uses an attached service account authenticates directly as that service account, so the attached service account is the workload's only identity. A principal that uses a service account key also authenticates as the service account alone, and keys create added risk because the holder is responsible for protecting the private key and following key-management best practices. For workloads that need a strongly attested identity, Agent Identity (opens in a new tab) provides a cryptographic identity based on the SPIFFE standard that can authenticate to MCP servers, cloud resources, endpoints, and other agents, acting either on its own behalf or on behalf of an end user.
Exam tip: Using a service account key is not impersonation because only the service account identity is involved, while impersonation always involves both the calling principal and the impersonated service account.
Google Cloud Directory Sync (GCDS) (opens in a new tab) is a provisioning bridge that copies identity data from on-premises Active Directory to Cloud Identity (opens in a new tab) or Google Workspace without copying passwords. Data flows from Active Directory to the GCDS host over LDAP, and then from the GCDS host to Google over HTTPS calls to the Directory API and Domain Shared Contacts API. Because the Google APIs are publicly reachable, the GCDS-to-Google path needs little firewall change and does not require hybrid connectivity, while the GCDS-to-Active Directory path must have direct LDAP network access.
GCDS deployment architecture centers on a dedicated sync host that sits between Active Directory and Google. The GCDS host can run on Windows or Linux, but best practice is to run it on a separate machine with LDAP access to Active Directory rather than on a domain controller itself. The guide assumes a domain-joined Windows machine with a desktop experience so Configuration Manager, the graphical interface for GCDS, can run directly on the server and write its XML configuration file locally. If the server has no desktop experience, Configuration Manager must run on an administrator workstation and the resulting configuration file must then be copied to the server.
GCDS stores its configuration in an XML file that contains an OAuth refresh token used to authenticate to Google, so the folder holding that file must be secured against unauthorized access. Communication from GCDS to Cloud Identity or Google Workspace travels over HTTPS, while communication to Active Directory travels over LDAP and should be encrypted with LDAPS or Cloud VPN when GCDS queries Active Directory remotely. By default Active Directory uses unencrypted LDAP, so remote queries from Google Cloud without encryption would expose directory reads on the network.
The LDAP connection defines how GCDS locates and authenticates to Active Directory to retrieve users and groups. GCDS requires an explicitly configured LDAP hostname and port, Authentication Type of Simple, and an Authorized User such as gcds@UPN_SUFFIX_DOMAIN or NETBIOS_DOMAIN_NAME\gcds. The Base DN field should be left empty when the goal is to search all domains in the forest, and the connection can be verified in Configuration Manager with Test connection before any provisioning rules are built.
In a small environment GCDS can point directly at a single global catalog (GC) server, but pointing at one server in a larger environment wastes redundancy and creates a single point of failure. GCDS does not natively support the Active Directory DC Locator mechanism for dynamic server discovery, so large deployments complement it with a PowerShell script that uses DC Locator to find the closest available GC server at sync time. A load balancer across GC servers is possible, but dynamic discovery is preferred because it automatically tracks servers that are temporarily unavailable.
Exam tip: Leave Base DN blank in GCDS to search all domains in the Active Directory forest; entering a DN limits LDAP searches to that subtree only.
The GCDS authorization model depends on two dedicated service identities, one on each side of the sync boundary. On the Active Directory side, GCDS depends on a dedicated domain user such as gcds created with Active Directory Users and Computers or New-ADUser, with User must change password at next logon cleared and Password never expires selected. Creating this user in the same domain as the GCDS machine simplifies authentication, and excluding this account from sync filters later prevents GCDS from trying to provision its own reader account.
On the Google side, GCDS depends on a dedicated Cloud Identity user such as cloud-directory-sync that holds the Super Admin role so it can create, list, and delete users and groups through the Directory API. This automation account should use a manually set password with Ask for a password change at the next sign-in cleared, should be protected with 2-step verification, and should be exempted from single sign-on so administrators can still re-authorize GCDS if federation fails. The Super Admin grant gives full control over Cloud Identity, Google Workspace, and Google Cloud resources, so it must be limited to this purpose-built account.
Attribute mapping controls how an Active Directory object becomes a Google user with a routable email identity. GCDS populates Given Name from the LDAP givenName attribute and Family Name from sn when Use defaults is selected under User Accounts > Additional User Attributes. The critical decision is the Email Address Attribute, which determines which Active Directory value becomes the Google primary email, with proxyAddresses optionally synced to preserve alias addresses.
The three mapping patterns differ only in which source attribute is trusted and whether Google rewrites the domain:
| Mapping pattern | Email Address Attribute | Google domain handling |
|---|---|---|
| UPN mapping | userPrincipalName | Keep Active Directory UPN suffix as Google email domain |
| UPN with domain substitution | userPrincipalName | Enable Replace domain names in LDAP email addresses with this domain name under Google Domain Configuration |
| Email mapping | Default mail attribute | Keep Active Directory mail value as Google email domain |
Choose UPN mapping when User Principal Names already match the verified Google domains, choose domain substitution when internal UPN suffixes do not match the public Google domain, and choose email mapping when the mail attribute is the authoritative identifier. Active Directory and Cloud Identity use different logical structures for domains, identities, and groups, so the mapping choice must be assessed before provisioning and groups should be synchronized alongside users so IAM can grant Google Cloud access by group membership.
Filtering rules control which Active Directory objects GCDS is allowed to provision and where the search applies. Scope is set in General Settings by selecting User Accounts and Groups while leaving Organizational Units, User Profiles, and Custom Schemas unselected when only users and groups are in scope. Each LDAP search rule then sets Scope to Sub-tree and leaves its own Base DN blank to cover the forest, or sets a specific Base DN to limit provisioning to selected domains or organizational units.
The standard user search rule matches all enabled person accounts while excluding disabled users, computer accounts, managed service accounts, and the GCDS reader:
(&(objectCategory=person)(objectClass=user)(!(userAccountControl:1.2.840.113556.1.4.803:=2))(!(userPrincipalName=gcds@*)))
In this filter, the userAccountControl bit-match excludes disabled accounts and the final clause excludes the gcds service account. Restricting provisioning to an assigned subset is also possible by narrowing the LDAP query or Base DN during testing, which prevents mass creates, suspends, or deletes before the mapping has been validated.
The GCDS operational lifecycle moves in order from configuration to simulation to initial provisioning to hourly scheduled sync. First, logging is configured to PROGRAM_DATA\gcds\gcds_sync.#{timestamp}.log and optional email Notifications are pointed at a mail server so failures are visible. Then the configuration is saved and validated without changing Google data:
sync.ps1 script with the configuration path and GCDS installation directory to %ProgramData%\gcds\sync.ps1 and trigger it hourly with a scheduled task so Active Directory changes propagate to Google.GCDS provisions account details and lifecycle state but does not synchronize passwords, so authentication after provisioning must still be delegated back to Active Directory through federation. Repeated bulk modification or deletion during testing can be flagged as abusive behavior, so pilot scoping, simulation review, and hourly incremental syncs keep the Google directory consistent without triggering large destructive changes.
Simulate sync reports what Google Cloud Directory Sync would do without changing Cloud Identity, while Sync and apply changes permanently creates, updates, suspends, or deletes users and groups. Always select Clear cache before either mode so results reflect current Active Directory data, and review Proposed changes during simulation before checking Successful user changes and Failures after enforcement.
Use domain substitution when internal Active Directory User Principal Name suffixes do not match the verified Google domain. In that pattern the Email Address Attribute remains userPrincipalName but Google replaces LDAP email domains with the configured Google domain, whereas standard User Principal Name mapping keeps the Active Directory suffix and email mapping keeps the mail attribute value.
An expired or missing identity provider signing certificate breaks signature validation, while an incorrect entity ID or assertion consumer service URL breaks routing of the assertion to Google. After the assertion reaches Google, mismatched NameID or attribute claims prevent matching to a provisioned Cloud Identity account, and tokens with too many group memberships fail when the authentication JSON Web Token exceeds the 4KB limit.
An organization is designing an automated identity synchronization architecture between their on-premises Active Directory Domain Services (AD DS) forest and Cloud Identity to enable workforce access to Google Cloud resources. The security team establishes the following requirements:
Which architectural and configuration approach should the organization implement?
Configure Google Cloud Directory Sync (GCDS) to authenticate through the root Organization SAML profile, requiring all administrative sessions to validate against on-premises Active Directory.
Deploy Google Cloud Directory Sync (GCDS) on-premises, create a dedicated Cloud Identity administrator account for GCDS that is exempt from SAML Single Sign-On (SSO), and configure SAML 2.0 federation to delegate authentication to Active Directory.
Deploy Managed Service for Microsoft Active Directory in Google Cloud with a bidirectional forest trust, and execute the Active Directory Migration Tool (ADMT) to migrate users and password hashes.
Install Google Cloud Directory Sync (GCDS) alongside G Suite Password Sync (GSPS) on domain controllers, and map the primary domain administrator account to authenticate GCDS via SAML SSO.
Last updated