Federating Google Cloud Platform with Active Directory: Synchronizing user accounts

This guide is the second part of a multi-part series that discusses how to extend an existing Active Directory–based identity management solution to Google Cloud Platform (GCP). The guide shows you how to set up account synchronization between Active Directory and Cloud Identity by using Google Cloud Directory Sync (GCDS).

The series consists of these parts:

This guide assumes that you have an existing Active Directory forest and that you intend to synchronize all domains in the forest to Cloud Identity.

To follow this guide, you must have access to an Active Directory account that is allowed to manage users. Also, if you don't yet have a Cloud Identity account, you'll need administrative access to your DNS zone in order to verify domains. If you already have an account, ensure that you have a user account in Cloud Identity that has super admin privileges.

Objectives

  • Install Cloud Directory Sync and connect it to Active Directory and Cloud Identity.
  • Configure Cloud Directory Sync to synchronize user accounts to Cloud Identity.
  • Register a scheduled task for continuously synchronizing to Cloud Identity.

Costs

If you're using the free edition of Cloud Identity, following this guide will not use any billable GCP components.

Before you begin

  • Make sure you understand how Active Directory identity management can be extended to GCP.
  • Decide how you want to map identities, groups, and domains. Specifically, make sure that you've answered the following questions:

    • Which DNS domain do you plan to use as the primary domain for Cloud Identity? Which additional DNS domains do you plan to use as secondary domains in Cloud Identity?
    • Do you need to use domain substitution?
    • Do you plan to use the email address (mail) or User Principal Name (userPrincipalName) as common identifiers for user accounts?
    • Do you plan to synchronize groups, and if so, do you intend to use the common name (cn) or email address (mail) as common identifiers for groups?

    For guidance on making these decisions, refer to the overview document on extending Active Directory identity and access management to GCP.

  • Before connecting your production Active Directory to GCP, consider using an Active Directory test environment for setting up and testing account synchronization.

  • Sign up for Cloud Identity if you don't have an account already, and add additional DNS domains if necessary.

  • If you're using the free edition of Cloud Identity and intend to synchronize more than 50 users, request an increase of the total number of free Cloud Identity users through your support contact.

Planning the Cloud Directory Sync deployment

Deciding where to deploy Cloud Directory Sync

Cloud Directory Sync can synchronize user accounts and groups from an LDAP directory to Cloud Identity. Acting as a go-between for the LDAP server and Cloud Identity, Cloud Directory Sync queries the LDAP directory to retrieve the necessary information from the directory and uses the Directory API to add, modify, or delete accounts in Cloud Identity.

Because Active Directory Domain Services is based on LDAP, Cloud Directory Sync is well suited to implement account synchronization between Active Directory and Cloud Identity.

When connecting an on-premises Active Directory infrastructure to GCP, you can run Cloud Directory Sync either on-premises or on a Compute Engine virtual machine in GCP. In most cases, it's best to run Cloud Directory Sync on-premises:

  • Because the information that Active Directory manages includes personally identifiable information and is usually considered sensitive, you might not want Active Directory to be accessed from outside the local network.
  • By default, Active Directory uses unencrypted LDAP. If you access Active Directory remotely from within GCP, you should use encrypted communication. Although you can encrypt the connection by using LDAP/S or Cloud VPN, doing so increases the complexity of the setup.
  • Communication from Cloud Directory Sync to Cloud Identity is conducted through HTTPS and requires little or no change to your firewall configuration.

You can run Cloud Directory Sync on either Windows or Linux. Although it's possible to deploy Cloud Directory Sync on the domain controller, it's best to run Cloud Directory Sync on a separate machine. This machine must satisfy the system requirements and have LDAP access to Active Directory. Although it's not a prerequisite for the machine to be domain joined or to run Windows, this guide assumes that Cloud Directory Sync runs on a domain-joined Windows machine.

To aid with setting up synchronization, Cloud Directory Sync includes a graphical user interface (GUI) called Configuration Manager. If the server on which you intend to run Cloud Directory Sync has a desktop experience, you can run Configuration Manager on the server itself. Otherwise, you'll need to run Configuration Manager locally and then copy the resulting configuration file to the server, where you can use it to run the synchronization. This guide assumes that you run Configuration Manager on a server with a GUI.

Deciding where to retrieve data

Cloud Directory Sync uses LDAP to interact with Active Directory and to retrieve information about user accounts and groups. To make this interaction possible, Cloud Directory Sync requires you to provide a hostname and port in the configuration. In a small Active Directory environment that runs only a single global catalog server, providing a hostname and port is not a problem because you can point Cloud Directory Sync directly to the global catalog server.

In a more complex environment that runs redundant global catalog servers, pointing Cloud Directory Sync to a single server does not make use of the redundancy and is therefore not ideal. Although it's possible to set up a load balancer that distributes LDAP queries across multiple global catalog servers and keeps track of servers that might be temporarily unavailable, it's preferable to use the DC Locator mechanism to locate servers dynamically.

Cloud Directory Sync itself currently does not support using the DC Locator mechanism. In this guide, you complement Cloud Directory Sync with a small PowerShell script that engages the DC Locator mechanism so that you don't have to statically configure endpoints of global catalog servers.

Configuring Cloud Identity

Creating a Cloud Identity user account for synchronization

In order to synchronize accounts, Cloud Directory Sync must interact with Cloud Identity. Creating, listing, and deleting users (and potentially groups and organizational units) are Cloud Identity operations that require administrative privileges.

When signing up for Cloud Identity, you already created one super admin account. Although you could use this account for Cloud Directory Sync, it's preferable to create a separate account that is exclusively used by Cloud Directory Sync:

  1. Open the Admin console and sign in by using the super admin account that you created when signing up for Cloud Identity.
  2. In the menu, click Directory > Users, and then click Add new user to create a user.
  3. Provide an appropriate name and email address, such as:

    1. First Name: Active Directory
    2. Last Name: Synchronizer
    3. Primary email: ad-synchronizer

    Retain the primary domain in the email address, even if the domain does not correspond to the forest that you're synchronizing from.

  4. Ensure that Automatically generate a new password is set to Disabled, and enter a password.

  5. Ensure that Ask for a password change at the next sign-in is set to Disabled.

  6. Click Add New User.

  7. Click Done.

To enable Cloud Directory Sync to create, list, and delete user accounts and groups, the account needs additional privileges. Additionally, it's a good idea to exempt the account from single sign-on—otherwise, you might not be able to re-authorize Cloud Directory Sync when experiencing single sign-on problems. Both can be accomplished by making the account a super admin:

  1. Locate the newly created user in the list and open it.
  2. Under Admin roles and privileges, click Assign Roles.
  3. Enable the Super Admin role.
  4. Click Save.

Enabling API access

Cloud Directory Sync uses the Cloud Identity API to synchronize accounts. You must enable this API first:

  1. In the Admin Console menu, select Security > Settings.
  2. Click API reference to view API-related settings.
  3. Make sure the Enable API access box is selected.
  4. At the bottom, click Save. If you already enabled API access, you can skip this step.

Configuring Active Directory synchronization

Creating an Active Directory user account for synchronization

To enable Cloud Directory Sync to retrieve information about users and groups from Active Directory, Cloud Directory Sync requires a domain account with sufficient access. Rather than reusing an existing Windows account for this purpose, create a dedicated account for Cloud Directory Sync:

  1. Open the Active Directory Users and Computers snap-in.
  2. Navigate to the domain and organizational unit where you want to create the user. If there are multiple domains in your forest, create the user in the same domain as the Cloud Directory Sync machine.
  3. Right-click on the right window pane and choose New > User.
  4. Provide an appropriate name and email address, such as:
    1. First Name: Google Cloud
    2. Last Name: Directory Sync
    3. User logon name: gcds
    4. User logon name (pre-Windows 2000): gcds
  5. Click Next.
  6. Provide a password that satisfies your password policy.
  7. Clear User must change password at next logon.
  8. Select Password never expires.
  9. Click Next, and then click Finish.

You now have the prerequisites in place for installing Cloud Directory Sync.

Installing Cloud Directory Sync

On the machine on which you will run Cloud Directory Sync, download and run the Cloud Directory Sync installer. Rather than using a browser to perform the download, you can use the following PowerShell command to download the installer:

(New-Object net.webclient).DownloadFile("https://dl.google.com/dirsync/dirsync-win64.exe", "$(pwd)\dirsync-win64.exe")

After the download has completed, you can launch the installation wizard by running the following command:

.\dirsync-win64.exe

Creating a folder for the Cloud Directory Sync configuration

Cloud Directory Sync stores its configuration in an XML file. Because this configuration includes an OAuth refresh token that Cloud Directory Sync uses to authenticate with Google, make sure that you properly secure the folder used for configuration.

In addition, because Cloud Directory Sync does not require access to local resources other than this folder, you must configure Cloud Directory Sync to run as a limited user account, LocalService:

  1. On the machine where you installed Cloud Directory Sync, sign in using either a domain or local admin account.
  2. Open a PowerShell console that has administrative privileges.
  3. Run the following commands to create a folder that is named $Env:ProgramData\gcds to store the configuration, and to apply an access control list (ACL) so that only Cloud Directory Sync and admins have access:

    $gcdsDataFolder = "$Env:ProgramData\gcds"
    New-Item -ItemType directory -Path  $gcdsDataFolder
    &icacls "$gcdsDataFolder" /inheritance:r
    &icacls "$gcdsDataFolder" /grant:r "CREATOR OWNER:(OI)(CI)F" /T
    &icacls "$gcdsDataFolder" /grant   "BUILTIN\Administrators:(OI)(CI)F" /T
    &icacls "$gcdsDataFolder" /grant   "Domain Admins:(OI)(CI)F" /T
    &icacls "$gcdsDataFolder" /grant   "LOCAL SERVICE:(OI)(CI)F" /T
    
  4. To determine the location of the ProgramData folder, run the command Write-Host $Env:ProgramData. On English versions of Windows, this path will usually be c:\ProgramData. You will need this path later.

Connecting to Google

You will now use Configuration Manager to prepare the Cloud Directory Sync configuration. These steps assume that you run Configuration Manager on the same server where you plan to run Cloud Directory Sync.

If you use a different machine to run Configuration Manager, make sure to copy the configuration file to the Cloud Directory Sync server afterward. Also, be aware that testing the configuration on a different machine might not be possible.

  1. Launch Configuration Manager. You can find Configuration Manager in the Windows Start menu under Google Cloud Directory Sync > Configuration Manager.
  2. Click Google Domain Configuration > Connection Settings.

    Google Domain Configuration > Connection Settings

  3. For Primary Domain Name, enter the primary domain of your Cloud Identity account. When you're synchronizing from multiple different forests to a single Cloud Identity account, the primary domain name might correspond to a different forest than the one you're setting up.

  4. Click Authorize Now.

  5. In the dialog, click Sign-in, which opens a browser window that prompts you to sign in. If you use the default, secure configuration of Internet Explorer, you might see multiple warning messages. If so, you can copy the URL to your local computer and open the URL there.

    Authorizing GCDS

  6. When the Google sign-in page appears, sign in by using the newly created ad-synchronizer Google account and the password that you specified for this account.

    If you've already configured the Cloud Identity account to use single sign-on (SSO), you might be automatically redirected to the Active Directory Federation Services (AD FS) sign-in page, which does not allow you to sign in by using the ad-synchronizer account. In this case, click Sign-in again, and then press Escape to stop the page from loading. In the browser address bar, remove the &hd=[PRIMARY_DOMAIN-name] parameter from the URL, and then press Enter. This step forces the Google sign-in page to appear.

  7. Because this is the first time you've used the account, you are prompted to accept the Cloud Identity Agreement. If you accept the terms, click Accept.

  8. The following screen asks you to authorize the ad-synchronizer account to access and modify data in your Cloud Identity account. Click Allow to confirm.

    Authorizing ad-synchronizer to data in your Cloud Identity account

  9. Close the browser window once you see the message Received verification code.

  10. In the menu, click File > Save as.

  11. In the file dialog, enter [PROGRAM_DATA]\gcds\config.xml as the filename. Replace [PROGRAM_DATA] with the path to the ProgramData folder that the PowerShell command returned when you ran it earlier.

  12. Click Save, and then click OK.

Connecting to Active Directory

The next step is to configure Cloud Directory Sync to connect to Active Directory:

  1. In Configuration Manager, click LDAP Configuration > Connection Settings.
  2. Configure the following settings:
    1. Server Type: Select MS Active Directory.
    2. Connection Type: Select Standard LDAP.
    3. Host Name: Enter the name of a global catalog server. This setting is used only for testing. Later, you will automate the discovery of the global catalog server.
    4. Port: 3268. Using a global catalog server instead of a domain controller helps ensure that you can synchronize accounts from all domains of your Active Directory forest.
    5. Authentication Type: Simple
    6. Authorized User: Enter the User Principal Name (UPN) of the domain user that you created earlier: gcds@[UPN_SUFFIX_DOMAIN]. Replace [UPN_SUFFIX_DOMAIN] with the appropriate UPN suffix domain for the user. Alternatively, you can also specify the user by using the [NETBIOS-DOMAIN-NAME]\gcds syntax.
    7. Base DN: Leave this field empty to ensure that searches are performed across all domains in the forest.
  3. To verify the settings, click Test connection. If the connection fails, double-check that you've specified the host name of a global catalog server and that the username and password are correct. Disregard that the error message might ask you to specify a Base DN.
  4. Click Close.
  5. Click File > Save to commit the configuration changes to disk, and then click OK.

Deciding what to synchronize

Now that you've successfully connected to both Cloud Identity and Active Directory, you can decide which items to synchronize:

  1. In Configuration Manager, click General Settings.
  2. Ensure that User Accounts is selected.
  3. If you intend to synchronize groups, ensure that Groups is selected; otherwise, clear the checkbox.
  4. Synchronizing organizational units is beyond the scope of this guide, so leave Organizational Units unselected.
  5. Leave User Profiles and Custom Schemas unselected.
  6. Click File > Save to commit the configuration changes to disk, and then click OK.

Synchronizing user accounts

Configuring account mappings

The next step is to configure how to map user accounts between Active Directory and Cloud Identity:

  1. In Configuration Manager, click User Accounts > Additional User Attributes.
  2. Click Use defaults to automatically populate the attributes for Given Name and Family Name with givenName and sn, respectively.

The remaining settings depend on whether you intend to use the UPN or email address to map Active Directory to Cloud Identity user accounts, and whether you need to apply domain name substitutions. If you're unsure which option is best for you, see the article on how Active Directory identity management can be extended to GCP.

UPN

  1. In Configuration Manager, click User Accounts > User Attributes.
  2. Configure the following settings:
    1. Email Address Attribute: userPrincipalName
    2. User Identifier Attribute: objectGUID
  3. Click the Search Rules tab, and then click Add Search Rule.
  4. Enter the following settings:

    1. Scope: Sub-tree
    2. Rule:

      (&(objectCategory=person)(objectClass=user)(!(userAccountControl:1.2.840.113556.1.4.803:=2)))

      This rule matches all non-disabled user accounts but ignores computer and managed service accounts.

    3. Base DN: Leave blank to search all domains in the forest.

  5. Click OK to create the rule.

  6. Click the Exclusion Rules tab, and then click Add Exclusion Rule. To make sure the account that Cloud Directory Sync uses to read from Active Directory is not synchronized to Cloud Identity, enter the following settings:

    1. Exclude Type: User Email Address
    2. Match Type: Exact Match
    3. Exclusion Rule: gcds@[UPN_SUFFIX_DOMAIN]. Replace [UPN_SUFFIX_DOMAIN] with the UPN suffix domain used in Active Directory.
  7. Click OK.

  8. Click File > Save to commit the configuration changes to disk, and then click OK.

UPN: domain substitution

  1. In Configuration Manager, click the User Accounts > User Attributes tab.
  2. Configure the following settings:
    1. Email Address Attribute: userPrincipalName
    2. User identifier Attribute: objectGUID
  3. Click OK to create the rule.
  4. Click the Search Rules tab, and then click Add Search Rule.
  5. Enter the following settings:

    1. Scope: Sub-tree
    2. Rule:

      (&(objectCategory=person)(objectClass=user)(!(userAccountControl:1.2.840.113556.1.4.803:=2)))

      This rule matches all non-disabled user accounts but ignores computer and managed service accounts.

    3. Base DN: Leave blank to search all domains within the forest.

  6. Click OK to create the rule.

  7. Click the Exclusion Rules tab, and then click Add Exclusion Rule. To make sure the account that Cloud Directory Sync uses to read from Active Directory is not synchronized to Cloud Identity, enter the following settings:

    1. Exclude Type: User Email Address
    2. Match Type: Exact Match
    3. Exclusion Rule: gcds@[PRIMARY_DOMAIN]. Replace [PRIMARY_DOMAIN] with the primary domain of your Cloud Identity account.
  8. Click OK.

  9. Click Google Domain Configuration > Connection Settings, and choose Replace domain names in LDAP email addresses with this domain name.

  10. Click File > Save to commit the configuration changes to disk, and then click OK.

Email

  1. In Configuration Manager, click User Accounts > User Attributes.
  2. Configure the following settings:
    1. Email Address Attribute: mail
    2. User identifier Attribute: objectGUID
  3. Click the Search Rules tab, and then click Add Search Rule.
  4. Enter the following settings:

    1. Scope: Sub-tree
    2. Rule:

      (&(objectCategory=person)(objectClass=user)(mail=*)(!(userAccountControl:1.2.840.113556.1.4.803:=2)))

      This rule matches all non-disabled user accounts with a non-empty email address but ignores computer and managed service accounts.

    3. Base DN: Leave blank to search all domains in the forest.

  5. Click OK to create the rule.

  6. Click File > Save to commit the configuration changes to disk, then click OK.

Email: domain substitution

  1. In Configuration Manager, click User Accounts > User Attributes.
  2. Configure the following settings:
    1. Email Address Attribute: mail
    2. User identifier Attribute: objectGUID
  3. Click the Search Rules tab, and then click Add Search Rule.
  4. Enter the following settings:

    1. Scope: Sub-tree
    2. Rule:

      (&(objectCategory=person)(objectClass=user)(mail=*)(!(userAccountControl:1.2.840.113556.1.4.803:=2)))

      This rule matches all non-disabled user accounts with a non-empty email address but ignores computer and managed service accounts.

    3. Base DN: Leave blank to search all domains in the forest.

  5. Click OK to create the rule.

  6. Click Google Domain Configuration > Connection Settings, and choose Replace domain names in LDAP email addresses with this domain name.

  7. Click File > Save to commit the configuration changes to disk, and then click OK.

Deletion policy

So far, the configuration has focused on adding and updating user accounts in Cloud Identity. However, it's also important that user accounts that are disabled or deleted in Active Directory be suspended or deleted in Cloud Identity.

As part of the synchronization process, Cloud Directory Sync generates a list of user accounts in Cloud Identity that don't have corresponding matches in the Active Directory LDAP query results. Because the LDAP query incorporates the clause (!(userAccountControl:1.2.840.113556.1.4.803:=2), any accounts that have been disabled or deleted in Active Directory since the last synchronization was performed will be included in this list. The default behavior of Cloud Directory Sync is to delete these users in Cloud Identity, but you can customize this behavior:

  1. In Configuration Manager, click User Accounts > User Attributes.
  2. Under Google Domain Users Deletion/Suspension Policy, ensure that Don't suspend or delete Google domain admins not found in LDAP is checked. This setting ensures that Cloud Directory Sync will not suspend or delete the super admin account that you used to configure Cloud Identity.
  3. Optionally, change the deletion policy for non-admin accounts.
  4. Click File > Save to commit the configuration changes to disk, then click OK.

If you use multiple separate instances of Cloud Directory Sync to synchronize different domains or forests to a single Cloud Identity account, make sure that the different Cloud Directory Sync instances don't interfere with one another. By default, user accounts in Cloud Identity that have been synchronized from a different source will wrongly be identified in Active Directory as having been deleted. To avoid this situation, configure Cloud Directory Sync to ignore all Cloud Identity user accounts that are beyond the scope of the domain or forest that you're synchronizing from.

UPN

  1. In Configuration Manager, click Google Domain Configuration > Exclusion Rules.
  2. Click Add Exclusion Rule.
  3. Configure the following settings:

    1. Type: User Email Address
    2. Match Type: Regular Expression
    3. Exclusion Rule: If you use a single UPN suffix domain, enter the following regular expression:

      .*@((?![UPN_SUFFIX_DOMAIN]).*)$

      Replace [UPN_SUFFIX_DOMAIN] with your UPN suffix domain, as in this example:

      .*@((?!corp.example.com).*)$

      If you use more than one UPN suffix domain, extend the expression as shown:

      .*@((?!corp.example.com|branch.example.com).*)$
  4. Click OK to create the rule.

UPN: domain substitution

  1. In Configuration Manager, click Google Domain Configuration > Exclusion Rules.
  2. Click Add Exclusion Rule.
  3. Configure the following settings:

    1. Type: User Email Address
    2. Match Type: Regular Expression
    3. Exclusion Rule: If you use a single UPN suffix domain, enter the following regular expression:

      .*@((?![SUBSTITUTION_DOMAIN]).*)$

      Replace [SUBSTITUTION_DOMAIN] with the domain that you use to replace the UPN suffix domain, as in this example:

      .*@((?!corp.example.com).*)$
  4. Click OK to create the rule.

Email

  1. In Configuration Manager, click Google Domain Configuration > Exclusion Rules.
  2. Click Add Exclusion Rule.
  3. Configure the following settings:

    1. Type: User Email Address
    2. Match Type: Regular Expression
    3. Exclusion Rule: If you use a single UPN suffix domain, enter the following regular expression:

      .*@((?![MX_DOMAIN]).*)$

      Replace [MX_DOMAIN] with the domain name that you use in email addresses, as in this example:

      .*@((?!corp.example.com).*)$

      If you use more than one UPN suffix domain, extend the expression as shown:

      .*@((?!corp.example.com|branch.example.com).*)$
  4. Click OK to create the rule.

Email: domain substitution

  1. In Configuration Manager, click Google Domain Configuration > Exclusion Rules.
  2. Click Add Exclusion Rule.
  3. Configure the following settings:

    1. Type: User Email Address
    2. Match Type: Regular Expression
    3. Exclusion Rule: If you use a single UPN suffix domain, enter the following regular expression:

      .*@((?![SUBSTITUTION_DOMAIN]).*)$

      Replace [SUBSTITUTION_DOMAIN] with the domain that you use to replace the email domain, as in this example:

      .*@((?!corp.example.com).*)$
  4. Click OK to create the rule.

Synchronizing groups

The next step is to configure how to map groups between Active Directory and Cloud Identity. This process differs based on whether you plan to map groups by common name or by email address.

Configuring group mappings by common name

First, you need to identify the types of security groups that you intend to synchronize, and then formulate an appropriate LDAP query. The following table contains common queries that you can use.

Type LDAP query
Domain local groups (&(objectCategory=group)(groupType:1.2.840.113556.1.4.803:=2147483652))
Global groups (&(objectCategory=group)(groupType:1.2.840.113556.1.4.803:=2147483650))
Universal groups (&(objectCategory=group)(groupType:1.2.840.113556.1.4.803:=2147483656))
Global and universal groups (&(objectCategory=group)(|(groupType:1.2.840.113556.1.4.803:=2147483650)(groupType:1.2.840.113556.1.4.803:=2147483656)))

The query for global groups also covers Active Directory–defined groups such as domain controllers. You can filter these groups by restricting the search by organizational unit (ou).

The remaining settings depend on whether you intend to use UPN or email address to map Active Directory to Cloud Identity user accounts.

UPN

  1. In Configuration Manager, click Groups > Search Rules.
  2. Click Add Search Rule to add a rule that captures user accounts and group memberships.
  3. Configure the following settings:
    1. Scope: Sub-tree
    2. Rule: Enter the LDAP query.
    3. Base DN: Leave empty to query groups across all domains in the forest.
  4. In the Groups box, enter the following settings:
    1. Group Email Address Attribute: cn
    2. Group Display Name Attribute: name
    3. Group Description Attribute: description
    4. User Email Name Attribute: userPrincipalName
  5. In the Members box, enter the following settings:
    1. Member Reference Attribute: member
    2. Leave the remaining fields blank.
  6. In the Owners box, enter the following settings:
    1. Owner Reference Attribute: managedBy
    2. Leave the remaining fields blank.
  7. Click the Prefix-Suffix tab.
  8. In the Group Email Address box, enter the following settings:
    1. Suffix: @[PRIMARY_DOMAIN], where you need to replace [PRIMARY_DOMAIN] with the primary domain of your Cloud Identity account. Although the setting seems redundant because Cloud Directory Sync will append the domain automatically, you must specify the setting explicitly to prevent multiple Cloud Directory Sync instances from erasing group members that they had not added. Example: @example.com.
    2. Click OK.
  9. Click Add Search Rule to add another rule that captures nested group memberships.
  10. Configure the following settings:
    1. Scope: Sub-tree
    2. Rule: Enter same the LDAP query.
    3. Base DN: Leave empty to query groups across all domains in the forest.
  11. In the Groups box, enter the following settings:
    1. Group Email Address Attribute: cn
    2. Group Display Name Attribute: name
    3. Group Description Attribute: description
    4. User Email Name Attribute: cn
  12. In the Members box, enter the following settings:
    1. Member Reference Attribute: member
    2. Leave the remaining fields blank.
  13. In the Owners box, enter the following settings:
    1. Owner Reference Attribute: managedBy
    2. Leave the remaining fields blank.
  14. Click the Prefix-Suffix tab.
  15. In the Group Email Address box, enter the following settings:
    • Suffix: @[PRIMARY_DOMAIN] where you must replace [PRIMARY_DOMAIN] with the primary domain of your Cloud Identity account.
  16. Click OK.
  17. Click File > Save to commit the configuration changes to disk, then click OK.

Email

  1. In Configuration Manager, click Groups > Search Rules.
  2. Click Add Search Rule to add a rule that captures both group memberships.
  3. Configure the following settings:
    1. Scope: Sub-tree
    2. Rule: Enter the LDAP query.
    3. Base DN: Leave empty to query groups across all domains in the forest.
  4. In the Groups box, enter the following settings:
    1. Group Email Address Attribute: cn
    2. Group Display Name Attribute: name
    3. Group Description Attribute: description
    4. User Email Name Attribute: mail
  5. In the Members box, enter the following settings:
    1. Member Reference Attribute: member
    2. Leave the remaining fields blank.
  6. In the Owners box, enter the following settings:
    1. Owner Reference Attribute: managedBy
    2. Leave the remaining fields blank.
  7. Click OK.
  8. Click File > Save to commit the configuration changes to disk, and then click OK.

The same settings also apply if you used domain substitution when mapping user accounts.

Configuring group mappings by email address

First, you need to identify the types of security groups that you intend to synchronize, and then formulate an appropriate LDAP query. The following table contains common queries that you can use.

Type LDAP query
Domain local groups with email address (&(objectCategory=group)(groupType:1.2.840.113556.1.4.803:=2147483652)(mail=*))
Global groups with email address (&(objectCategory=group)(groupType:1.2.840.113556.1.4.803:=2147483650)(mail=*))
Universal groups with email address (&(objectCategory=group)(groupType:1.2.840.113556.1.4.803:=2147483656)(mail=*))
Global and universal groups with email address (&(objectCategory=group)(|(groupType:1.2.840.113556.1.4.803:=2147483650)(groupType:1.2.840.113556.1.4.803:=2147483656))(mail=*))

The remaining settings depend on whether you intend to use UPN or email address to map Active Directory to Cloud Identity user accounts.

UPN

  1. In Configuration Manager, click Groups > Search Rules.
  2. Click Add Search Rule to add a rule that captures both group memberships.
  3. Configure the following settings:
    1. Scope: Sub-tree
    2. Rule: Enter the LDAP query.
    3. Base DN: Leave empty to query groups across all domains in the forest.
  4. In the Groups box, enter the following settings:
    1. Group Email Address Attribute: mail
    2. Group Display Name Attribute: name
    3. Group Description Attribute: description
    4. User Email Name Attribute: userPrincipalName
  5. In the Members box, enter the following settings:
    1. Member Reference Attribute: member
    2. Leave the remaining fields blank.
  6. In the Owners box, enter the following settings:
    1. Owner Reference Attribute: managedBy
    2. Leave the remaining fields blank.
  7. Click OK.
  8. Click Add Search Rule to add another rule that captures nested group memberships.
  9. Configure the following settings:
    1. Scope: Sub-tree
    2. Rule: Enter the same LDAP query.
    3. Base DN: Leave empty to query groups across all domains in the forest.
  10. In the Groups box, enter the following settings:
    1. Group Email Address Attribute: mail
    2. Group Display Name Attribute: name
    3. Group Description Attribute: description
    4. User Email Name Attribute: mail
  11. In the Members box, enter the following settings:
    1. Member Reference Attribute: member
    2. Leave the remaining fields blank.
  12. In the Owners box, enter the following settings:
    1. Owner Reference Attribute: managedBy
    2. Leave the remaining fields blank.
  13. Click OK.
  14. Click File > Save to commit the configuration changes to disk, and then click OK.

Email

  1. In Configuration Manager, click Groups > Search Rules.
  2. Click Add Search Rule to add a rule that captures both group memberships.
  3. Configure the following settings:
    1. Scope: Sub-tree
    2. Rule: Enter the LDAP query.
    3. Base DN: Leave empty to query groups across all domains in the forest.
  4. In the Groups box, enter the following settings:
    1. Group Email Address Attribute: mail
    2. Group Display Name Attribute: name
    3. Group Description Attribute: description
    4. User Email Name Attribute: mail
  5. In the Members box, enter the following settings:
    1. Member Reference Attribute: member
    2. Leave the remaining fields blank.
  6. In the Owners box, enter the following settings:
    1. Owner Reference Attribute: managedBy
    2. Leave the remaining fields blank.
  7. Click OK.
  8. Click File > Save to commit the configuration changes to disk, and then click OK.

The same settings also apply if you used domain substitution when mapping user accounts.

Deletion policy

Cloud Directory Sync handles the deletion of groups similarly to the deletion of users. If you use multiple separate instances of Cloud Directory Sync to synchronize different domains or forests to a single Cloud Identity account, make sure that the different Cloud Directory Sync instances don't interfere with one another.

By default, user accounts in Cloud Identity that have been synchronized from a different source will wrongly be identified in Active Directory as having been deleted. To avoid this situation, configure Cloud Directory Sync to ignore all Cloud Identity user accounts that are beyond the scope of the domain or forest that you're synchronizing from.

UPN

  1. Click Google Domain Configuration > Exclusion Rules.
  2. Click Add Exclusion Rule.
  3. Configure the following settings:

    1. Type: Group Member Email Address
    2. Match Type: Regular Expression
    3. Exclusion Rule: If you use a single UPN suffix domain, enter the following regular expression:

      .*@((?![UPN_SUFFIX_DOMAIN]).*)$

      Replace [UPN_SUFFIX_DOMAIN] with your UPN suffix domain, as in this example:

      .*@((?!corp.example.com).*)$

      If you use more than one UPN suffix domain, extend the expression as shown:

      .*@((?!corp.example.com|branch.example.com).*)$
  4. Click OK to create the rule.

UPN: domain substitution

  1. Click Google Domain Configuration > Exclusion Rules.
  2. Click Add Exclusion Rule.
  3. Configure the following settings:

    1. Type: Group Member Email Address
    2. Match Type: Regular Expression
    3. Exclusion Rule: If you use a single UPN suffix domain, enter the following regular expression:

      .*@((?![SUBSTITUTION_DOMAIN]).*)$

      Replace [SUBSTITUTION_DOMAIN] with the domain that you use to replace the UPN suffix domain, as in this example:

      .*@((?!corp.example.com).*)$
  4. Click OK to create the rule.

Email

  1. Click Google Domain Configuration > Exclusion Rules.
  2. Click Add Exclusion Rule.
  3. Configure the following settings:

    1. Type: Group Member Email Address
    2. Match Type: Regular Expression
    3. Exclusion Rule: If you use a single UPN suffix domain, enter the following regular expression:

      .*@((?![MX_DOMAIN]).*)$

      Replace [MX_DOMAIN] with the domain name that you use in email addresses, as in this example:

      .*@((?!corp.example.com).*)$

      If you use more than one UPN suffix domain, extend the expression as shown:

      .*@((?!corp.example.com|branch.example.com).*)$
  4. Click OK to create the rule.

Email: domain substitution

  1. Click Google Domain Configuration > Exclusion Rules.
  2. Click Add Exclusion Rule.
  3. Configure the following settings:

    1. Type: Group Member Email Address
    2. Match Type: Regular Expression
    3. Exclusion Rule: If you use a single UPN suffix domain, enter the following regular expression:

      .*@((?![SUBSTITUTION_DOMAIN]).*)$

      Replace [SUBSTITUTION_DOMAIN] with the domain that you use to replace the email domain, as in this example:

      .*@((?!corp.example.com).*)$
    4. Click OK to create the rule.

Configure logging and notifications

Keeping Active Directory and Cloud Identity in sync requires that you run Cloud Directory Sync on a scheduled basis. To allow you to keep track of Cloud Directory Sync activity and potential problems, you can configure Cloud Directory Sync to write a log file:

  1. In Configuration Manager, click Logging.
  2. Set File name to [PROGRAM_DATA]\gcds\gcds_sync.log. Replace [PROGRAM_DATA] with the path to the ProgramData folder that the PowerShell command returned when you ran it earlier.
  3. Click File > Save to commit the configuration changes to disk, then click OK.

In addition to logging, Cloud Directory Sync can send notifications by email. To activate this service, click Notifications and provide connection information for your mail server.

Simulating a synchronization

You've completed the Cloud Directory Sync configuration. To verify that the configuration works as intended, you can simulate a synchronization run. During simulation, GCDS won't perform any changes to Cloud Identity, but will instead report which changes it would perform during a regular synchronization run.

  1. In Configuration Manager, click Sync.
  2. At the bottom of the screen, select Clear cache, and then click Simulate sync.
  3. After synchronization completes, review the Proposed changes section of the log that is shown in the lower half of the dialog and verify that at least one user is being proposed to be created or modified.

Performing an initial synchronization

You can now trigger an an initial synchronization:

Warnings

  • Triggering a synchronization will make permanent changes to user accounts and groups in your Cloud Identity account.
  • If you have a large number of user accounts to synchronize, consider temporarily changing the LDAP query to match a subset of these user accounts only. Using this subset of accounts, you can then test synchronization and adjust settings if necessary. After you've successfully validated results, change back the LDAP query and synchronize the remaining accounts.
  • Avoid repeatedly modifying or deleting a large number of user accounts when testing synchronization because such actions might be flagged as abusive behavior.

Trigger a synchronization as follows:

  1. In Configuration Manager, click Sync.
  2. At the bottom of the screen, select Clear cache, and then click Sync & apply changes.

    A dialog appears showing the synchronization status.

  3. After synchronization completes, check the log that is shown in the lower half of the dialog:

    1. Under Successful user changes, verify that at least one user has been created.
    2. Under Failures, verify that no failures occurred during synchronization.

If you chose to synchronize groups, the remainder of the log might contain several warnings, which are usually safe to ignore.

Scheduling

To ensure that changes performed in Active Directory are propagated to Cloud Identity, set up a scheduled task that triggers a synchronization every hour:

  1. Open a PowerShell console as Administrator.
  2. Check if the Active Directory PowerShell module is available on the system:

    import-module ActiveDirectory

    If the command fails, download and install the Remote Server Administration Tools and try again.

  3. In Notepad, create a file, copy the following content into it, and save the file to $Env:ProgramData\gcds\sync.ps1. When you're done, close the file.

    [CmdletBinding()]
    Param(
        [Parameter(Mandatory=$True, Position=1)]
        [string]$config,
    
        [Parameter(Mandatory=$True, Position=1)]
        [string]$gcdsInstallationDir
    )
    
    import-module ActiveDirectory
    
    # Stop on error.
    $ErrorActionPreference ="stop"
    
    # Ensure it's an absolute path.
    $rawConfigPath = [System.IO.Path]::Combine((pwd).Path, $config)
    
    # Discover closest GC in current domain.
    $dc = Get-ADDomainController -discover -Service "GlobalCatalog" -NextClosestSite
    Write-Host ("Using Global Catalog server {0} of domain {1} as LDAP source" -f [string]$dc.HostName, $dc.Domain)
    
    # Load XML and replace the endpoint.
    $dom = [xml](Get-Content $rawConfigPath)
    $ldapConfigNode = $dom.SelectSingleNode("//plugin[@class='com.google.usersyncapp.plugin.ldap.LDAPPlugin']/config")
    
    # Tweak the endpoint.
    $ldapConfigNode.hostname = [string]$dc.HostName
    $ldapConfigNode.ldapCredMachineName = [string]$dc.HostName
    $ldapConfigNode.port = "3268"   # Always use Global Catalog port
    
    # Tweak the tsv files location
    $googleConfigNode = $dom.SelectSingleNode("//plugin[@class='com.google.usersyncapp.plugin.google.GooglePlugin']/config")
    $googleConfigNode.nonAddressPrimaryKeyMapFile = [System.IO.Path]::Combine((pwd).Path, "nonAddressPrimaryKeyFile.tsv")
    $googleConfigNode.passwordTimestampFile = [System.IO.Path]::Combine((pwd).Path, "passwordTimestampCache.tsv")
    
    # Save resulting config.
    $targetConfigPath = $rawConfigPath + ".autodiscover"
    
    $writer = New-Object System.IO.StreamWriter($targetConfigPath, $False, (New-Object System.Text.UTF8Encoding($False)))
    $dom.Save($writer)
    $writer.Close()
    
    # Run synchronization.
    Start-Process -FilePath "$gcdsInstallationDir\sync-cmd" `
        -Wait -ArgumentList "--apply --loglevel INFO --config ""$targetConfigPath"""
    
  4. Configuration Manager created a secret key to encrypt the credentials in the config file. To ensure that Cloud Directory Sync can still read the configuration when it's run as a scheduled task, run the following commands to copy that secret key from your own profile to the profile of NT AUTHORITY\LOCAL SERVICE:

    New-Item -Path Registry::HKEY_USERS\S-1-5-19\SOFTWARE\JavaSoft\Prefs\com\google\usersyncapp -Force
    
    Copy-Item -Path Microsoft.PowerShell.Core\Registry::HKEY_CURRENT_USER\SOFTWARE\JavaSoft\Prefs\com\google\usersyncapp\util `
        -Destination Microsoft.PowerShell.Core\Registry::HKEY_USERS\S-1-5-19\SOFTWARE\JavaSoft\Prefs\com\google\usersyncapp\util
    

    If the commands fail, ensure that you started the PowerShell console as Administrator.

  5. Create a scheduled task by running the following commands. The scheduled task will be triggered every hour and invokes the sync.ps1 script as NT AUTHORITY\LOCAL SERVICE.

    $taskName = "Synchronize to Cloud Identity"
    
    $arguments = [string]::Format('-ExecutionPolicy Bypass -NoProfile {0}\gcds\sync.ps1 -config {0}\gcds\config.xml -gcdsInstallationDir ''{1}\Google Cloud Directory Sync''', $Env:ProgramData, $Env:Programfiles)
    
    $action = New-ScheduledTaskAction -Execute 'PowerShell.exe' `
      -Argument $arguments
    $trigger = New-ScheduledTaskTrigger `
      -Once `
      -At (Get-Date) `
      -RepetitionInterval (New-TimeSpan -Minutes 60) `
      -RepetitionDuration (New-TimeSpan -Days (365 * 20))
    
    $principal = New-ScheduledTaskPrincipal -UserID "NT AUTHORITY\LOCAL SERVICE" -LogonType ServiceAccount
    Register-ScheduledTask -Action $action -Trigger $trigger -Principal $principal -TaskName $taskName
    
    $task = Get-ScheduledTask -TaskName "$taskName"
    $Task.Settings.ExecutionTimeLimit = "PT12H"
    Set-ScheduledTask $task
    

Testing synchronization

You've completed the installation and configuration of Cloud Directory Sync, and the scheduled task will trigger a synchronization every hour.

To trigger a synchronization manually, switch to the PowerShell console and run the following command:

$taskName = "Synchronize to Cloud Identity"
Start-ScheduledTask $taskName

Cleaning up

To remove Cloud Directory Sync, perform the following steps:

  1. Open Windows Control Panel and click Programs > Uninstall a program.
  2. Select Google Cloud Directory Sync, and click Uninstall/Change to launch the uninstall wizard. Then follow the instructions in the wizard.
  3. Open a PowerShell console and run the following command to remove the scheduled synchronization task:

    $taskName = "Synchronize to Cloud Identity"
    Unregister-ScheduledTask -TaskName $taskName -Confirm:$False
    
  4. Run the following command to delete the configuration and log files:

    Remove-Item -Recurse -Force "$Env:ProgramData\gcds"
    Remove-Item -Recurse -Path Registry::HKEY_USERS\S-1-5-19\SOFTWARE\JavaSoft\Prefs\com\google\usersyncapp
    

What's next

Was this page helpful? Let us know how we did:

Send feedback about...