Federating Google Cloud with Active Directory: Provisioning user accounts

This article shows you how to set up user and group provisioning between Active Directory and your Cloud Identity or G Suite account by using Google Cloud Directory Sync (GCDS).

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

Objectives

  • Install Cloud Directory Sync and connect it to Active Directory and Cloud Identity or G Suite.
  • Configure Cloud Directory Sync to provision users and, optionally, groups to Google Cloud.
  • Register a scheduled task for continuous provisioning.

Costs

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

Before you begin

  • Make sure you understand how Active Directory identity management can be extended to Google Cloud.
  • 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 or G Suite? Which additional DNS domains do you plan to use as secondary domains?
    • 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 users?
    • Do you plan to provision 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 Google Cloud.

  • Before connecting your production Active Directory to Google Cloud, consider using an Active Directory test environment for setting up and testing user provisioning.

  • 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 provision more than 50 users, request an increase of the total number of free Cloud Identity users through your support contact.

  • If you suspect that any of the domains you plan to use for Cloud Identity could have been used by employees to register consumer accounts, consider migrating these user accounts first. For more details, see Assessing existing user accounts.

Planning the Cloud Directory Sync deployment

Deciding where to deploy Cloud Directory Sync

Cloud Directory Sync can provision users and groups from an LDAP directory to Cloud Identity or G Suite. Acting as a go-between for the LDAP server and Cloud Identity or G Suite, 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 users in your Cloud Identity or G Suite account.

Because Active Directory Domain Services is based on LDAP, Cloud Directory Sync is well suited to implement user provisioning between Active Directory and Cloud Identity or G Suite.

When connecting an on-premises Active Directory infrastructure to Google Cloud, you can run Cloud Directory Sync either on-premises or on a Compute Engine virtual machine in Google Cloud. 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 Google Cloud, 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 or G Suite 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 provisioning, 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 Cloud Directory Sync. 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 users 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.

Preparing your Cloud Identity or G Suite account

Creating a user for Cloud Directory Sync

To enable Cloud Directory Sync to interact with the API of Cloud Identity and G Suite, the application needs a user account that has administrative privileges.

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

  1. Open the Admin console and sign in by using the super-admin user that you created when signing up for Cloud Identity or G Suite.
  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: Google Cloud
    2. Last Name: Directory Sync
    3. Primary email: cloud-directory-sync

    Retain the primary domain in the email address, even if the domain does not correspond to the forest that you're provisioning 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 user needs additional privileges. Additionally, it's a good idea to exempt the user 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 user 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.

Configuring user provisioning

Creating an Active Directory user for Cloud Directory Sync

To enable Cloud Directory Sync to retrieve information about users and groups from Active Directory, Cloud Directory Sync also requires a domain user with sufficient access. Rather than reusing an existing Windows user for this purpose, create a dedicated user 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, LocalService:

  1. On the machine where you installed Cloud Directory Sync, sign in using either a domain or local admin user.
  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 or G Suite account. When you're provisioning from multiple different forests to a single Cloud Identity or G Suite 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 cloud-directory-sync Google user and the password that you specified for this user.

    If you've already configured your Cloud Identity or G Suite 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 cloud-directory-sync user. 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 user 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 cloud-directory-sync user to access and modify data in your Cloud Identity or G Suite account. Click Allow to confirm.

    Authorizing cloud-directory-sync to data in your Cloud Identity or G Suite 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 provision users 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 provision

Now that you've successfully connected Cloud Directory Sync, you can decide which items to provision:

  1. In Configuration Manager, click General Settings.
  2. Ensure that User Accounts is selected.
  3. If you intend to provision 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.

Provisioning users

Configuring user mappings

The next step is to configure how to map users between Active Directory and Cloud Identity or G Suite:

  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 users in Cloud Identity or G Suite, 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 Google Cloud.

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 users 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 user that Cloud Directory Sync uses to read from Active Directory is not provisioned to Cloud Identity or G Suite, 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 users 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 user that Cloud Directory Sync uses to read from Active Directory is not provisioned to Cloud Identity or G Suite, 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 or G Suite 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 users 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 users 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 users in Cloud Identity or G Suite. However, it's also important that users that are disabled or deleted in Active Directory be suspended or deleted in Cloud Identity or G Suite.

As part of the provisioning process, Cloud Directory Sync generates a list of users in Cloud Identity or G Suite 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 users that have been disabled or deleted in Active Directory since the last provisioning was performed will be included in this list. The default behavior of Cloud Directory Sync is to delete these users in Cloud Identity or G Suite, 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 user that you used to configure your Cloud Identity or G Suite account.
  3. Optionally, change the deletion policy for non-admin users.
  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 provision different domains or forests to a single Cloud Identity or G Suite account, make sure that the different Cloud Directory Sync instances don't interfere with one another. By default, users in Cloud Identity or G Suite that have been provisioned 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 users that are beyond the scope of the domain or forest that you're provisioning 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.

Provisioning groups

The next step is to configure how to map groups between Active Directory and Cloud Identity or G Suite. 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 provision, 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 users in Cloud Identity or G Suite.

UPN

  1. In Configuration Manager, click Groups > Search Rules.
  2. Click Add Search Rule to add a rule that captures users 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 or G Suite 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 or G Suite 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 users.

Configuring group mappings by email address

First, you need to identify the types of security groups that you intend to provision, 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 users in Cloud Identity or G Suite.

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 users.

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 provision different domains or forests to a single Cloud Identity or G Suite account, make sure that the different Cloud Directory Sync instances don't interfere with one another.

By default, user inCloud Identity or G Suite that have been provisioned 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 users that are beyond the scope of the domain or forest that you're provisioning 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 users 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 user provisioning

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

  1. In Configuration Manager, click Sync.
  2. At the bottom of the screen, select Clear cache, and then click Simulate sync.
  3. After the process 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.

Initial user provisioning

You can now trigger the initial user provisioning:

Warnings

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

Trigger a provision run 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 status.

  3. After the process 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.

If you chose to provision 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 provisioning run 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()
    
    # Start provisioning.
    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"
    $gcdsDir = "$Env:ProgramData\gcds"
    
    $action = New-ScheduledTaskAction -Execute 'PowerShell.exe' `
      -Argument "-ExecutionPolicy Bypass -NoProfile $gcdsDir\sync.ps1 -config $gcdsDir\config.xml -gcdsInstallationDir '$Env:Programfiles\Google Cloud Directory Sync'" `
      -WorkingDirectory $gcdsDir
    $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 user provisioning

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

To trigger a provisioning run 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 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