Set up user sync

This page is for Directory Sync. If you’re using Google Cloud Directory Sync (GCDS), go to GCDS. Directory Sync is currently in public beta.

Now you’re ready to set up the users you are going to synchronize. In Directory Sync, you enter group names from your external directory to sync users. The individual users in the group (not the group itself) are synced to your Google cloud directory.

Before you begin

Make sure you add and test your external directory connection to your Google cloud directory. For details, go to Add, edit, or remove an external directory.

Set up the users to synchronize

Expand all  |  Collapse all

Step 1: Select the users
  1. Sign in to your Google Admin console.

    Sign in using your administrator account (does not end in

  2. In the Admin console, go to Menu and then Directoryand thenDirectory sync.
  3. Click the name of your external directory.
  4. Click Set up user sync.
  5. Enter the name of the external directory group and press Enter.

    Directory Sync syncs the group members to your Google cloud directory.

  6. Enter any additional group names.
  7. (Active Directory only) For Base DN, enter the base distinguished name (DN).

    The groups specified in steps 4 and 5 should be directly under the base DN.

    Example: ou=Sales, dc=example, dc=com. In this example, Directory Sync searches for groups under the Sales organizational unit.

  8. Click Verify to check that the groups exist in your external directory.
  9. Click Continue.
  10. If you want to map users to a single organizational unit, select the organizational unitand thenDone.
  11. (Optional) To ensure that the user remains in the organizational unit in your Google cloud directory if they're moved in the external directory, uncheck the Enforce organizational unit mapping box.
  12. Click Continue.
Step 2: Place users in an organizational unit
  1. Choose an option:
    • If you want to place users in a single organizational unit, click Select organizational unit, go to and select the organizational unitand thenclick Done.
    • If you want to place users in an organizational unit that's defined in an attribute in your external directory, for Place users in the OU stored as an attribute, enter the user attribute in your external directory that contains the full path to the organizational unit.

      For the steps to create the path, go to Add an organizational unit as an attribute in your external directory (below on this page).

  2. (Optional) To ensure that the user remains in the organizational unit in your Google cloud directory if they are moved in the external directory, uncheck the Enforce organizational unit mapping box.
  3. Click Continue.

Add an organizational unit as an attribute in your external directory

  1. Set up the organizational unit structure in your Google Admin console. For details, go to Add an organizational unit.
  2. In your external directory, using a standard or custom attribute, define the intended organizational unit path for each user. Use the following format:
    • Don't include the top-level organizational unit.
    • Separate the parent and child organizational units with a forward slash (/).

Example: If you want to add the user to the Sales organizational unit that's under the Finance organizational unit, you would follow these steps:

  1. In the external directory, for, set the Department attribute to Finance/Sales.
  2. When you set up Directory Sync, click Place users in the OU stored as an attribute and add the Department attribute.
Step 3: Map the user attributes

Set up required attributes

Confirm or enter the external directory attributes that map to the following user attributes in your Google cloud directory:

  • First name
  • Last name
  • Primary email address

If you change the attributes, you can click Set defaultand thenProceed to reset them back to their default.

Map any optional attributes

You can map standard and custom user attributes from your external directory to your Google cloud directory. To see frequently used mappings, go to Common user attribute mappings (below on this page).

  1. For Enter an attribute, enter the user attribute from your external directory.

    If the external directory user attribute is nested, separate the attribute and subattribute with a period (for example, employeeOrgData.division).

  2. From the list, select the Google cloud directory user attribute.

    You can map a single external directory attribute to multiple Google cloud directory user attributes. However, you can't map a single Google cloud directory attribute to multiple external directory attributes.

  3. (Optional) To map additional user attributes, repeat the steps.

Common user attribute mappings

Here are some common attribute mappings. You don't have to follow these mappings. You can change the attribute in the external directory and map to another attribute in your Google cloud directory.

External directory attribute in Active Directory (AD) or Azure AD Usually maps to this Google user attribute...
givenName (AD & Azure AD) First name
sn (AD)
surname (Azure AD)
Last name
mail (AD)
userPrincipalName (Azure AD)
Primary email
company (AD)
companyName (Azure AD)
Company name
assistant (AD) Assistant's email
department (AD & Azure AD) Department
physicalDeliveryOfficeName (AD)
officeLocation (Azure AD)
Office location
title (AD)
jobTitle (Azure AD)
Job title
employeeID (AD)
employeeId (Azure AD)
Employee ID
telephoneNumber (AD) Work phone number
homePhone (AD) Home phone number
facsimileTelephoneNumber (AD)
faxNumber (Azure AD)
Fax number
mobile (AD)
mobilePhone (Azure AD)
Mobile phone number
pager (AD) Work mobile phone
telephoneAssistant (AD) Assistant’s number

streetAddress (AD & Azure AD)

Street address
postOfficeBox (AD) P.O. box
l (lowercase L in AD)
city (Azure AD)
st (AD)
state (Azure AD)
postalCode (AD & Azure AD) Zip/Postal code
co (AD)
country (Azure AD)
preferredLanguage (Azure AD) Language
aboutMe (Azure AD) About
employeeOrgData.costCenter (Azure AD) Cost center
uidNumber (AD) POSIX UID

primaryGroupID (AD)


sAMAccountName (AD) POSIX Username
unixHomeDirectory (AD) POSIX home directory

Related topics

Step 4: Choose how users activate their accounts
  1. Choose an option:
    • Send activation email—Users get an email message about activating their new account and setting a password.

      If you select this option, choose whether to send the email to the user's primary or recovery email address. If you select the recovery email address, make sure you added a mapping for the address in Step 3: Map the user attribute (above on this page).

      For more information about what users need to do, go to What happens when a user gets an activation email? (below on this page).

    • Do not send an activation email—Users do not get an email.

      Use this option if you want to communicate directly with your users about new accounts or if you use a third-party identity provider (IdP) for authentication. (If you use an IdP, there’s no need for users to set a Google password.)

  2. Click Continue.

What happens when a user gets an activation email?

After the sync, your users get an email message with details about activating their new managed Google Account. When they're ready to sign in to the new account for the first time, users need to complete the following steps:

  1. In their original email account, open the email message and click Sign inand thenNext.
  2. Click Send to get a verification code.
  3. In their original account, open the verification code message and copy the code.
  4. In their new Google account, enter the verification code and click Next.
  5. Accept the Terms of Service.
  6. Create a strong password and click Change password.
Step 5: Suspend users not found in the external directory (Optional)

If a user is suspended or not found in your external directory (for example, the user's group is deleted in the external directory), you can suspend them in your Google cloud directory. 

To suspend users not found in the external directory:

  1. Check the Suspend user in Google box.

    If you don't want to suspend users, uncheck the box.

  2. Click Continue.

Important: Directory Sync syncs the user's state. If you suspend a user's account but the external directory account is active, the user's account is activated following a sync.

Step 6: Set safeguards

Set the conditions under which a sync is automatically canceled. If the sync exceeds the safeguard limits, the sync is automatically canceled and no users are suspended. No further syncs will run until you manually enable the sync. For more information about safeguards, go to How safeguards are determined (in the next section on this page).

To set a safeguard:

  1. For Safeguards, select Set a percentage of users or Set a total number of users and enter a percentage or number.
  2. Click Simulate Sync.
  3. If a safeguard is triggered, you get a notification with details about the failed sync. You can also view additional details in the audit log.

    For more information, go to Use the alert center and Check log events for Directory Sync.

How safeguards are determined

Directory Sync calculates how many user accounts exist in your external directory and compares that with how many accounts might be suspended following a sync. If the amount is larger than the specified percentage or number, the sync is automatically canceled and no action is taken.


You have 100 external directory users. During a sync, Directory Sync proposes to suspend 12 user accounts and add 3 new accounts.

Example 1: You set a numerical limit of 14 as a safeguard. Because the number of accounts it proposes to suspend (12) are fewer than the safeguard (14), Directory Sync continues with the proposed changes.

Example 2: You set a percentage limit of 10% as a safeguard. Directory Sync compares the proposed 12 candidates for suspension against the percentage limit. Because the percentage of candidates for suspension (12%) exceeds the 10% limit, Directory Sync stops the sync without applying any changes.

What happens next?

Directory Sync simulates a sync. Depending on the size of your data, the process can take up to an hour to complete.

View the status of a simulation

You can return to the directory details page to see the status of the simulation. You can also check whether the simulation is complete in the Directory Sync log events:

  1. Open the Directory Sync log events.

    For details, go to Access Directory Sync log event data.

  2. Click Add a filterand thenEvent.
  3. Select Sync Completed and click Apply.

    A Yes in the Simulation column indicates the simulation is complete. You might need to add the Simulation column to see the results.

Check the results of a simulated sync

When the simulation is complete, on the directory details page, click View Simulation log.

Related topic

Replace the domain name for synced users

Next step

Set up group sync

Google, Google Workspace, and related marks and logos are trademarks of Google LLC. All other company and product names are trademarks of the companies with which they are associated.

Was this helpful?

How can we improve it?
Clear search
Close search
Google apps
Main menu