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
Step 1: Select the users-
Sign in to your Google Admin console.
Sign in using your administrator account (does not end in @gmail.com).
-
In the Admin console, go to Menu
Directory
Directory sync.
- Click the name of your external directory.
- Click Set up user sync.
- Enter the name of the external directory group and press Enter.
Directory Sync syncs the group members to your Google cloud directory.
Note: Groups must have their own associated email address in the external directory.
- Enter any additional group names.
- (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.
- Click Verify to check that the groups exist in your external directory.
- Click Continue.
- If you want to map users to a single organizational unit, select the organizational unit
- (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.
- Click Continue.
- Choose an option:
- If you want to place users in a single organizational unit, click Select organizational unit, go to and select the organizational unit
- 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).
- If you want to place users in a single organizational unit, click Select organizational unit, go to and select the organizational unit
- (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.
- Click Continue.
Add an organizational unit as an attribute in your external directory
- Set up the organizational unit structure in your Google Admin console. For details, go to Add an organizational unit.
- 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 yuri@example.com to the Sales organizational unit that's under the Finance organizational unit, you would follow these steps:
- In the external directory, for yuri@example.com, set the Department attribute to Finance/Sales.
- When you set up Directory Sync, click Place users in the OU stored as an attribute and add the Department attribute.
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 defaultProceed 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).
- 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).
- 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.
- (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) |
City |
| st (AD) state (Azure AD) |
State/Province |
| postalCode (AD & Azure AD) | Zip/Postal code |
| co (AD) country (Azure AD) |
Country |
| preferredLanguage (Azure AD) | Language |
| aboutMe (Azure AD) | About |
| employeeOrgData.costCenter (Azure AD) | Cost center |
| uidNumber (AD) | POSIX UID |
|
primaryGroupID (AD) |
POSIX GID |
| sAMAccountName (AD) | POSIX Username |
| unixHomeDirectory (AD) | POSIX home directory |
Related topics
- 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.)
- Send activation email—Users get an email message about activating their new account and setting a password.
- 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:
- In their original email account, open the email message and click Sign in
- Click Send to get a verification code.
- In their original account, open the verification code message and copy the code.
- In their new Google account, enter the verification code and click Next.
- Accept the Terms of Service.
- Create a strong password and click Change password.
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:
- Check the Suspend user in Google box.
If you don't want to suspend users, uncheck the box.
- 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.
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:
- For Safeguards, select Set a percentage of users or Set a total number of users and enter a percentage or number.
- Click Simulate Sync.
- 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.
Examples
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:
- Open the Directory Sync log events.
For details, go to Access Directory Sync log event data.
- Click Add a filter
- 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
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.
