Account Management



Learn how you can create, update, and deactivate user accounts on Workplace.
!
Following the industry trend of migration towards Cloud identity provider (IdP) solutions, we have decided to sunset the AD Sync solution on August 5, 2021, after which our team will no longer provide support or software updates. Starting today, you will no longer be able to deploy AD Sync solution to new Workplace communities. Due to security reasons, we will sunset the current (v15) and all previous versions of the AD Sync support software on December 31, 2020.
?
Which cloud IdP solutions does Workplace integrate with?
Workplace integrates many IdP solutions, including Microsoft Azure AD, Okta, Harbor, G Suite, OneLogin, and Connect by Azuronaut. We encourage you to visit our Integration Directory for a full list of IdP solutions we partner with. We recommend Microsoft Azure AD as a viable alternative to the current AD Sync solution. You may follow steps as described to complete the migration.

What if I’m not ready to migrate to a cloud provider?
Should you prefer not to migrate to a cloud provider at this moment, we would encourage you to update your AD Sync support software to the newly released version (v16) as described in the current page, which will continue to function till August 5, 2021.
Overview

Overview

The Workplace Active Directory Sync (also called AD Sync hereafter) is a component that lets you synchronize selected groups and organization units from Active Directory to Workplace, eliminating the need for manual user administration when people join and depart your enterprise.

This guide describes the installation and configuration procedures along with providing a reference for the attributes that Active Directory Sync replicates from your Active Directory to Workplace.

AD Sync Component is designed to automatically:

  • Provision (create) user accounts as new people should be given access to Workplace.
  • Update user profile attributes over time as they change (e.g different phone number).
  • Deprovision (deactivate) user accounts as people depart your organisation, or should no longer have access.
Release Notes

Release Notes

AD Sync v1.0.16.0 contains important updates that provide enhanced security. We recommend that all customers upgrade their AD Sync v1.0.15.0 or earlier installations as soon as possible.

  • Managed Service Account Support - prior versions of AD Sync would only run under the user account of an AD domain member (i.e., a Domain User account with the default username of svc.workplace). When running a service under a domain user account, a malicious user with local access to the Windows Server could attempt to escalate privileges by running code under the service identity. Running the service under a Managed Service Account — which cannot be logged into interactively and is only usable on a single server — protects against this type of vulnerability.
  • Certificate pinning - prior versions of AD Sync would only communicate with Workplace’s SCIM API over SSL/TLS. AD Sync v16 implements a feature called certificate pinning, which adds defense against a Man in the Middle (MITM) attack by confirming, when establishing an SSL/TLS connection, that the host certificate is issued by Facebook.
  • Authenticode signing - prior versions of AD Sync did not have signed EXE files (e.g., PushService.exe), although the installer itself was signed. In AD Sync v16, all EXEs files are signed.
  • Protection Against DLL hijacking - AD Sync v16 implements a feature called Safe DLL Search Mode. This prevents a malicious user from attempting to escalate privileges in Windows by causing AD Sync to load an arbitrary DLL instead of one of the packaged DLLs.
Data Flow

Data Flow

Workplace Active Directory Sync runs as a Windows Service within your IT infrastructure. After you configure it to query Active Directory for the set of users you would like to give access to Workplace, AD Sync will run (on a schedule of every three hours, by default) a one-way batch replication of selected users' profile data to reconcile accounts between Active Directory and Workplace.

1
AD Sync queries Active Directory using LDAP filter(s) or AD Group(s).

2
Reconcile user additions, updates and deactivations with SQL database.

3
Unidirectional replication of profile information sent via Workplace SCIM API.
Requirements and Limitations

Requirements and Limitations

This section list the requirements and limitations to keep in mind when planning an AD Sync installation.

Requirements

  • Installation must be run by a user with AD Domain Administrator privileges.
  • AD Sync is designed to run on Windows Server 2012 R2 or Windows Server 2016. Older configurations may work (when the OS language is set to en_US), but are not supported by Facebook.
  • AD Sync needs to run on a computer that is domain-joined to the same AD controller that your Workplace users belong to. If your Workplace users belong to multiple AD Domains, please review our possible topologies for a multiple forests setup.
  • The Microsoft components .NET Framework (version 4.5.2) and SQL Server 2014 Express LocalDB (a light version of SQL Server Express to store user data) are required and will be installed with AD Sync if they're not already on the server (All cumulative updates should also be installed).
  • For each group of users to sync to Workplace by Facebook, you must identify either the Distinguished Name (DN) of the root entry in Active Directory that contains the users or an LDAP Filter or an Active Directory Group that identifies the users you want to sync to Workplace.
  • Your Domain Controller must support LDAPS (SSL) connections over port 636.

Limitations

  • Can only be configured to sync users based either on LDAP filters (e.g., a specific user class or attribute value), or AD security/distribution groups.
  • Will only handle 100,000 users at maximum (approximately) using the default admin-less SQL Server 2014 Express LocalDB. Syncing more users than this requires you to administer your own database.
  • Has been tested on Active Directory domains and forests at the Windows Server 2012 functional level.
  • Only allows customizing the following user profile attributes' mapping rules: formatted name, location, phone number, department; All other attributes will be mapped by default logic (see the Attribute Mappings reference table for details).
  • Will not sync users that do not have an AD value for these three required Workplace fields: 1) User name, 2) Display name, and 3) Family name.
Possible Topologies

Possible Topologies

Depending on your identity strategy, your company can manage your users in a single forest or in multiple forests. Based on such different identity strategies, you should consequently plan for different AD Sync deployment topologies.

Single forest topology

The default setup is when all your users are managed in a single forest. AD Sync will always be able to read user accounts from the current domain.

Multiple forests topology

AD Sync can only sync users from the Active Directory domain that the server belongs to or to a domain in the same AD forest that has the appropriate trust relationships established.

  • If you need to sync user accounts from other domains, you must establish appropriate trust relationships in the Active Directory forest to allow these reads.

  • If you can't create the trusts between forests, you may need to follow the installation and configuration procedure for AD Sync on a server in each domain.

Installation Guide

Installation Guide

This section covers the installation of the AD Sync tool in your IT environment. Once you have successfully completed the AD Sync installation steps below, you need to configure AD Sync to start provisioning users in Workplace from your Active Directory.

Prerequisites

In order to install Workplace AD Sync you will need to:

  • Choose a domain-joined Windows Server where AD Sync will run (called AD Sync server in these instructions).
  • Make sure that you have a domain administrator account, so that you can use Remote Desktop to connect to the AD Sync server.
  • Make sure you understand and identify your target topology.
  • Make sure that an SSL Certificate is installed on the AD Domain Controller to enable encrypted LDAPs to communicate with the Domain Controller.
  • Make sure that the AD Sync Server has the ability to communicate with www.facebook.com over HTTPS.
?
Workplace recommends that all customers run AD Sync using a Managed Service Account. After installation, AD Sync does not run with any admin privileges. It runs under the identity of a user account that you choose.
?
AD Sync will use the same proxy settings that are configured in Internet Explorer. If your network requires a proxy for communications to www.facebook.com, you must configure IE's proxy settings appropriately for your AD Sync user. If you are experiencing problems, see our Troubleshooting guide here.

High-level instructions

There are 7 stages to installing and configuring AD Sync:

1
Create a Custom Integration.

2
Download AD Sync Installer.

3
Install AD Sync.

4
Configure AD Sync.

5
Choose the users to synchronize to Workplace.

6
Run AD Sync in Test Mode.

7
Run AD Sync in Live Mode.

1. Create a Custom Integration

You must have been granted the System Administrator role within your Workplace Instance so that you can retrieve your API connection parameters required to complete AD Sync installation.

1
In the Admin Panel, select Integrations.

2
Click Create Custom Integration.

3
Fill out a Name (mandatory) and a Description (optional) for the custom integration.

4
Click on Create. The Integrations window opens.
5
Scroll down and check the Manage Accounts check box.

6
Uncheck the Automatically Invite People to Workplace as soon as they’re added using this integration.
7
Scroll up and click Create Access Token. The New Token Created dialog box opens.

8
Check the I understand checkbox. Click Done.

9
Scroll down to the bottom of the Integrations page, and click Save.

2. Download AD Sync Installer

AD Sync installer is available for download by clicking on the link below:

Download AD Sync installer

After download is completed, verify installer is authentic:

1
Right-click the installer, select Properties, then click on the Digital Signatures tab.

2
Click on the signature from Facebook Inc., then click Details.

3
Check for the text This digital signature is OK.

3. Complete AD Sync Installation

Use a Domain Administrator account to connect to the AD Sync Server using Remote Desktop.

?
AD Sync service is recommended to run under the identity of a Managed Service Account. You may either create a new managed service account as described below or have AD Sync run under the identity of an existing Managed Service account.
1
Using an elevated PowerShell, run the following commands to create the managed service account in your domain (if not available) and restrict its use to this server:
PS C:\> Import-Module ServerManager
PS C:\> Add-WindowsFeature -Name "RSAT-AD-PowerShell" –IncludeAllSubFeature
PS C:\> $machineName= HOSTNAME.EXE
PS C:\> $userName= "msvc.workplace$"
PS C:\> New-ADServiceAccount -Name $userName -RestrictToSingleComputer
PS C:\> Add-ADComputerServiceAccount -Identity $machineName -ServiceAccount $userName
PS C:\> Install-ADServiceAccount -Identity $userName

2
Test that the account was created correctly with this command, which should return “True”.
PS C:\> Test-ADServiceAccount -Identity $userName

3
Copy the installer binary to the server and double click it to run the installer.

4
Click Next on the welcome screen.

5
Accept the license terms and click Next.

6
Type In your Workplace API connection parameters from the section above and click Next.

7
Make sure that you select “AD Managed Service Account” on the screen that allows you to choose the service identity. Make sure the username matches the service account you created in Step 1 (you do not need to input a password since MSA accounts do not have one).

8
Accept the default Use local database and click Install to complete the installation. If you need to use another database (i.e., not a local admin-less database on this server) you can input a custom database connection string.
4. Configure AD Sync

4. Configure AD Sync

This section covers the configuration of the AD Sync tool. The AD Sync configuration steps below, will guide you to start provisioning users in Workplace from your Active Directory.

!
In AD Sync version 15 and earlier, the config file was stored in the service user’s local app data directory (e.g., C:\Users\svc.workplace). But running AD Sync v16 under a Managed Service Account identity means that this configuration file is not readable by the service. So you’ll need to do a one-time migration of your config file. If you are having difficulties with configuring ADSync, please review our Troubleshooting section.
!
Changes to the Console App v16: Regardless whether you choose to run under the recommended MSA account or not, as of AD Sync v16 you must now run theConsoleApp.exe using an elevated prompt from an administrator or domain administrator account. If you are having difficulties with configuring ADSync, please review our Troubleshooting section.
1
If you are upgrading to AD Sync v16, migrate your existing AD Sync configurations. Using an elevated Powershell, run the ConsoleApp tool to migrate your existing AD Sync config:
PS C:\> "C:\Program Files (x86)\Workplace by Facebook\ADSyncService\ConsoleApp.exe"

ConfigManager> MigrateConfig.Copy {prior ad sync domain username}

2
If you have completed the previous step, AD Sync v16 should now be running according to the pre-existing configuration and the upgrade to v16 has been completed at this point. Note that the log files will now be stored under the updated Managed Service Account user directory (by default, msvc.workplace$ instead of svc.workplace):
PS C:\> Get-Content 'C:\users\msvc.workplace$\AppData\Local\Workplace by Facebook\AD Sync Service\ad-sync-service-log.txt' -Wait

For example:

PS C:\> "C:\Program Files (x86)\Workplace by Facebook\ADSyncService\ConsoleApp.exe"

ConfigManager> MigrateConfig.Copy svc.workplace
Enter svc.workplace account password: ***************
Domain: {your domain}
Current service account: {per your v16 installation}
Config file migrated successfully
ConfigManager> Exit

3
To run the Configuration Manager console application (ConsoleApp.exe) after installation (this can be edited later by re-running the console application), use Remote Desktop to logon to the AD Sync Server using a domain administrator account.

4
Open an elevated Powershell and run Configuration Manager:
PS C:\Windows\system32> "C:\Program Files (x86)\Workplace by Facebook\ADSyncService\ConsoleApp.exe"

5
If successful, you will see a new window open with this prompt:
Welcome to the Workplace AD Sync Component Config Manager. This program lets you:
- Setup your Active Directory user sources (i.e., AD groups or LDAP filters)
- Control other settings like log level
To get started, type 'Config.Help'.
To quit, type 'Config.Exit'.

ConfigManager>

You can now control how AD Sync functions by using the commands in the Configuration Manager.

  • Get help with a specific command by inputting the command name and specifying the .Help option. For example:
    ConfigManager> Users.Help

    Users commands control how the Sync Component selects users ...
    * Users.Summary - get a summary of your current user source ...
    ...
  • Get general help by entering Config.Help at any time.
  • Exit the program by entering Config.Exit at any time.
5. Choose the users to synchronize to Workplace

5. Choose the users to synchronize to Workplace

Use the Users.Add command to add your Active Directory user sources (Groups or LDAP filters) to Workplace.

The relevant synchronization commands are:

  • Users.Summary. Outputs the current user sources selected.
  • Users.Add. Adds user sources (AD groups or LDAP filters) to AD Sync scope.
  • Users.Remove. Removes user sources to AD Sync scope.
  • Users.RootContainer. Displays the current AD domain's root container.

Read the guidelines on how to use these commands in the Commands Reference section.

6. Run AD Sync in Test mode

6. Run AD Sync in Test mode

By default, AD Sync runs in Test mode. No users will be created or updated in Workplace.

This gives you a chance to review and validate AD Sync's configuration without actually changing Workplace user accounts.

1
Run the SyncComponent.RunMode command and verify AD Sync is configured to run in Test mode.

2
Restart AD Sync. This changes the configuration and starts the test synchronization. Follow the steps in the AD Sync Schedule section. This will trigger AD Sync's first test synchronization.

3
Allow a full test run to complete. This could finish within a few minutes or it could take longer, depending on how many users are in your user sources.

AD Sync will output a line to the application log when it completes its run - look for the text Completed PushSyncJob.Execute() method. To verify the application logs follow the steps outlined in the AD Sync Logs section. You should also find entries in the log file that describe which users in your Active Directory user sources will be created and which existing Workplace users will be updated.

7. Run AD Sync in Live mode

When you have validated AD Sync in Test Mode:

1
Update SyncComponent to run in Live mode by running SyncComponent.RunMode LIVE.

2
Restart AD Sync. This changes the configuration and starts the synchronization. To Restart AD Sync follow the steps in the AD Sync Schedule section. This will trigger AD Sync first Live synchronization.

3
Allow a full test run to complete. Depending on how many users are in your user sources, this could finish within a few minutes or it could take longer.

Review the audit logs to confirm that the correct user accounts are being created. To verify the application logs follow the steps outlined in the AD Sync Logs section. After a full run is complete, you can request an export of all your users from Workplace to acknowledge that the user profiles are populated as you expect.

Managing Cert Pinning

Managing Cert Pinning

By default in v16, cert pinning is enabled and configured to only establish TLS/SSL communications to Workplace’s SCIM API by confirming that the certificate is correct. Most customers should not need to make any configuration changes.

Workplace SCIM API Communication Errors

If you see SSL/TLS errors in your AD Sync logs, the default configuration may be incorrect for your environment:

2020-06-07 21:05:27.6306 ERROR PushService.ScimRequestHelper One or more certificate chain validation errors occurred, request cannot be completed

Configuring an Additional Trusted Root Certificate

If you are proxying traffic from your AD Sync server you may need to add an additional trusted certificate.

1
Find the thumbprint of your trusted root cert (the thumbprint is 40 hexadecimal characters).

2
Confirm that this cert is in the local machine’s trusted root certs store by running certlm.msc and confirming that it has been added to Trusted Root Certification Authorities > Certificates.

3
Run the ConsoleApp program to add a new trusted certificate:
PS C:\Windows\system32> "C:\Program Files (x86)\Workplace by Facebook\ADSyncService\ConsoleApp.exe"
Welcome to the Workplace AD Sync Component Config Manager. This program lets you:
- Setup your Active Directory user sources (i.e., AD groups or LDAP filters)
- Control other settings like log level
To get started, type 'Config.Help'.To quit, type 'Config.Exit'.

ConfigManager> CertPinning.AddCert {thumbprint}

Disabling Cert Pinning

Workplace recommends that you do not disable cert pinning. But if it’s essential in your configuration, you may do so using the ConsoleApp’s CertPinning command.

AD Sync Schedule

AD Sync Schedule

By default, AD Sync runs on a schedule every three hours. When you update its configuration, instead of waiting for the next scheduled run, you can restart the AD Sync and force it to read the updated configuration immediately.

To change your AD Sync schedule:

1
Open the services management console by clicking Start > Search > services.msc.

2
Within the Services Management Console, find the item Workplace AD Sync Service. Right click this entry and choose “Restart”.
?
It is possible to change the default run schedule by using the SyncComponent.RunInteval command. Review the command specifics in the Commands Reference section.
Commands Reference

Commands Reference

This sections lists the set of commands which are used to configure Users and the AD Sync component itself.

Users Commands

These commands let you manage the set of users in your Active Directory that will be given access to Workplace.

Users.Summary

This command outputs the current user sources.

Example: List the configured user sources.

ConfigManager> Users.Summary

Configured user sources:
1 - DC=Fabrikam,DC=COM GROUP "Domain Users"
2 - OU=Sales,DC=Fabrikam,DC=COM GROUP "Sales Dept Users"

Users.Add

These commands let you manage the set of users in your Active Directory that will be given access to Workplace.

Parameters

Users.Add {container} {type} {value} {confirm}

The root container, also known as a Distinguished Name (DN), represents the set of users are organized underneath within your AD.

?
A container is similar to a web domain (e.g., www.fabrikam.com) but is written differently. An example of a container is: OU=Sales,DC=Fabrikam,DC=COM. You will need to identify the DN that contains the users for each of your user sources. Consult with an AD administrator in your enterprise for more information about DNs within your AD.

The type, which is either a group or an LDAP filter:

AD Group. An AD security or distribution group's name. Both AD group types are valid for AD Sync setup and a simple way of managing access to Workplace is to establish an AD group of either type and add those users who you want to grant access to Workplace. Then, configure AD Sync to use this group as the user source.

LDAP Filter. This is similar to a WHERE clause in a SQL query: you define one or more criteria that a AD user record must satisfy to be synced to Workplace. For example, if you want to sync all user records in AD where the record's object class is user and the record's object category is person, you would input this filter: (&(objectClass=user)(objectCategory=person)).

?
Microsoft has documented how to write LDAP Filter Queries along with tools you can use to test your queries.

A value that defines the set of users within that DN.

Example: Verify a group's name and preview the first few people in the group.

ConfigManager> Users.Add DC=Fabrikam,DC=Com GROUP "Domain Users"

Here are some few people in this source's usernames and formatted names:
reena@fabrikam.com - Reena Godais
diana@fabrikam.com - Diana Monheit
lorenzo@fabrikam.com - Lorenzo Kirby
anish@fabrikam.com - Anish Ghosh
nico@fabrikam.com - Nico Sinatra

Example: Add a group user source to the configuration.

ConfigManager> Users.Add DC=Fabrikam,DC=Com GROUP "Domain Users"True

This user source has been added to the configuration.

Example: Verify an LDAP filter and preview the first few people.

ConfigManager> Users.Add OU=Sales,DC=Fabrikam,DC=Com LDAP "(&(mail=*)(objectClass=person))"

Here are some few people in this source's usernames and formatted names:
reena@fabrikam.com - Reena Godais
diana@fabrikam.com - Diana Monheit
lorenzo@fabrikam.com - Lorenzo Kirby
anish@fabrikam.com - Anish Ghosh
nico@fabrikam.com - Nico Sinatra

Example: Add an LDAP filter user source to the configuration.

ConfigManager> Users.Add DC=Fabrikam,DC=Com GROUP "(&(mail=*)(objectClass=person))"True

This user source has been added to the configuration.

Users.RootContainer

This command outputs the current Active Directory domain's root container.

Example: Retrieve AD top level container.

ConfigManager> Users.RootContainer

The current Active Directory top-level container is: DC=Fabrikam,DC=COM

Users.Remove

This command removes a previously-configured user source. It uses the User.Summary output order to index sources.

Parameters

Users.Remove {index} {confirmed}

Example: Preview removing the second user source configured.

ConfigManager> Users.Remove 2

Confirm removing the source "OU=Sales,DC=Fabrikam,DC=COM GROUP "Sales Dept Users" with the command Users.Remove 2 True

Example: Confirm removing the second user source configured.

ConfigManager> Users.Remove 2True

This user source has been removed from the configuration.

AD Sync Commands

These settings let you control how AD Sync behaves when it runs, for example by instructing it to run in Test only mode or how detailed you would like it to output log information.

SyncComponent.Summary

This command summarizes your current AD Sync configuration.

SyncComponent.RunMode

This command allows to retrieve and set AD Sync run mode.

Parameters

SyncComponent.RunMode {TEST | LIVE}

AD Sync can run in two modes, Live or Test. By default it runs in Test mode which lets you run AD Sync using your API Connection, configured AD Attributes and User Sources but without actually doing any create or update operations to your Workplace instance.

?
Workplace recommends that you run AD Sync in Test mode when you make a change to your configuration so that you can confirm by reviewing the log files that your configuration is correct.

In Test mode, AD Sync will:

1
Simulate sync behavior using the current configuration but without creation or changing user accounts in Workplace.

2
Iterate over your User Sources and compare to existing users within Workplace.

3
Output to the application log files whether a given user will be created or updated.

In Live mode, AD Sync will:

1
Actually run and create/update/deactivate users in Workplace using the current configuration.

2
Create users in Workplace, if there is newly added user source which contains new users, or there are new users added to existing user sources in Active Directory, since last run.

3
Deactivate users in Workplace, if the user accounts are no longer retrievable through any of the configured user sources, or the corresponding user account is disabled in Active Directory.

Example: Verify the current AD Sync run mode.

ConfigManager> SyncComponent.RunMode

The Sync Component is configured to run in Test mode.

Example: Update the AD Sync run mode.

ConfigManager> SyncComponent.RunMode LIVE

The Sync Component will now run in Live mode.

SyncComponent.RunInterval

This command allows to retrieve and override the frequency of AD Sync runs.

Parameters

SyncComponent.RunInterval {hours}

By default, AD Sync will run approximately every 3 hours. It is possible to override this frequency to be as often as approximately every 1 hour or as infrequently as approximately every 24 hours.

?
AD Sync will not run more than once at a time, so depending on the duration of each run, the actual schedule frequency may vary.

Example: Verify the current AD Sync run interval.

ConfigManager> SyncComponent.RunInterval

The run interval is approx. every 3 hours.

Example: Update the AD Sync run interval.

ConfigManager> SyncComponent.RunInterval 1

The run interval has been updated to run approx. every: 1 hours.
You must restart the service to enact the new schedule.

SyncComponent.ForceSync

This command allows to force a full AD Sync run.

Parameters

SyncComponent.ForceSync {TRUE | FALSE}

You can force AD Sync to perform one full sync, synchronizing all accounts in the configured user sources, ignoring the data in the AD Sync database. This command performs only one full sync cycle. After finishing it, AD Sync will only sync the changes identified in your Active Directory. Like other AD Sync configurations, it requires a restart in the AD Sync Service (follow the steps in the AD Sync Schedule section).

?
A forced sync will touch all users included in your configured user sources and accordingly to the total number of users, you can expect a longer execution time.

Example: Update AD Sync to force a full sync in the next run.

ConfigManager> SyncComponent.ForceSync TRUE

The Sync Component will execute a full sync.

SyncComponent.LogLevel

This command allows to retrieve and set the current AD Sync log level.

Parameters

SyncComponent.LogLevel {level}

Under normal circumstances you should run AD Sync under the default Warn level. If you need to adjust the detail level, you can input any of these values:

{Fatal,Error,Warn,Info,Debug,Trace,Off}

Example: View the current log level.

ConfigManager> SyncComponent.LogLevel

The log level is: Warn

Example: Update the current log level.

ConfigManager> SyncComponent.LogLevel DEBUG

The log level has been updated to: Debug

SyncComponent.UsernameSource

This command allows to retrieve and set the AD field that is used as a source for Workplace username.

Parameters

SyncComponent.UsernameSource {EMAIL_ADDRESS | UPN}

AD Sync will use a person's email address as their Workplace username by default. If your organization needs to use the UPN field instead, you can change this configuration.

?
In most situations, you should use email address as the username source, since Workplace uses this field's value as the person's contact point. If you choose UPN as the username source, you should also make sure you can route emails sent to this address to each individual.

Example: View the current username source.

ConfigManager> SyncComponent.UsernameSource

The username source is: EMAIL_ADDRESS

Example: Update the username source.

ConfigManager> SyncComponent.UsernameSource EMAIL_ADDRESS

The username source has been updated to: EMAIL_ADDRESS

SyncComponent.FormattedNameStyle

This command allows to decide the format for the name field in Workplace.

Parameters

SyncComponent.FormattedNameStyle { DISPLAY_NAME | COMMON_NAME | GIVEN_THEN_SURNAME | SURNAME_THEN_GIVEN | SURNAME_COMMA_GIVEN_MIDDLE_INITIAL }

Depending on which AD value(s) you want to use within Workplace as an individual's display name, you have five options:

  • Display Name
  • Common Name
  • Given Name first and then Surname (e.g., Mickey Mouse)
  • Surname first and then Given Name (e.g., Mouse Mickey)
  • Surname first then Given Name and Middle Initial (e.g., Mouse, Mickey J.)
?
To see the values in your AD, you can use the Windows Server Active Directory Users Attribute Editor. The AD Admin Center tool's User Attribute Editor shows the formatted name style source attribute alternatives: displayName, cn, givenname, and sn.

Example: View the current formatted name style.

ConfigManager> SyncComponent.FormattedNameStyle

The formatted name style is: GIVEN_THEN_SURNAME

Example: Update the formatted name style.

ConfigManager> SyncComponent.FormattedNameStyle COMMON_NAME

The formatted name style has been updated to: COMMON_NAME

SyncComponent.FormattedAddressStyle

This command allows to decide the format for the location field in Workplace.

Parameters

SyncComponent.FormattedAddressStyle { LOCALITY | CONCATENATE_ALL | PHYSICAL_DELIVERY_OFFICE_NAME | CONCATENATE_LOCALITY_AND_OFFICE }

Depending on which AD value(s) you want to use within Workplace as an individual's location, you have four options:

  • Locality = l attribute from AD
  • Concatenate All. Combines street address, locality, region, zip/postal code, and country = streetAddress, l, st, postalCode and c attributes from AD
  • Physical Delivery Office Name = physicalDeliveryOfficeName from AD
  • Concatenate Locality and Office. Combines locality and physical delivery office name = l and physicalDeliveryOfficeName from AD
?
To see the values in your AD, you can use the Windows Server Active Directory Users Attribute Editor.

Example: View the current formatted address style.

ConfigManager> SyncComponent.FormattedAddressStyle

The formatted address style is: PHYSICAL_DELIVERY_OFFICE_NAME

Example: Update the formatted address style.

ConfigManager> SyncComponent.FormattedAddressStyle LOCALITY

The formatted address style has been updated to: LOCALITY

SyncComponent.PrimaryPhoneType

This command allows to decide which field should be used for the phone number field in Workplace.

Parameters

SyncComponent.PrimaryPhoneType {type}

You can specify which AD field should be mapped to the Workplace phone number for this person:

{Telephone,Fax,Home,IP,Mobile,Pager}

Example: View the current primary phone type.

ConfigManager> SyncComponent.PrimaryPhoneType

The primary phone type is: TELEPHONE_NUMBER

Example: Update the primary phone type.

ConfigManager> SyncComponent.PrimaryPhoneType MOBILE_NUMBER

The primary phone type has been updated to: MOBILE_NUMBER

SyncComponent.DepartmentSource

This command allows to retrieve and set the AD field that is used as a source for Workplace department.

Parameters

SyncComponent.DepartmentSource {DEPARTMENT | COMPANY_PLUS_DEPARTMENT}

AD Sync will set the Workplace department value to the AD department field by default. You can choose to configure the Workplace department to be the combination of the AD company and department instead.

Example: View the current department source.

ConfigManager> SyncComponent.DepartmentSource

The department source is: DEPARTMENT

Example: Update the department source.

ConfigManager> SyncComponent.DepartmentSource COMPANY_PLUS_DEPARTMENT

The department source has been updated to: COMPANY_PLUS_DEPARTMENT

SyncComponent.ClaimEmailLanguage

This command allows to retrieve and set the language of claim emails (ie. the email sent when a user is invited to Workplace).

Parameters

SyncComponent.ClaimEmailLanguage {language}

AD Sync will always use the AD preferredLanguage field to set the claim email language for each user. However, if the AD value is not set or if the value is not valid in Workplace, you can also set a default claim email language for people in your organization.

Example: View the current default claim email language.

ConfigManager> SyncComponent.ClaimEmailLanguage

The claim email language code is: en_GB.

Example: Update the default claim email language.

ConfigManager> SyncComponent.ClaimEmailLanguage fr_FR

The claim email language code has been updated to: fr_FR.

SyncComponent.SuppressedFields

These command allows to select which fields should never be synched to Workplace.

?
Field suppression happens prior to any other applicable field formatting you have configured (e.g., building a formatted address) in AD Sync.

Parameters

SyncComponent.SuppressedFields
SyncComponent.AddSuppressedField {field}
SyncComponent.RemoveSuppressedField {field}

Should you need to ensure that selected AD data field values should never be synced to Workplace, you can use the suppressed fields commands to manage the list of fields you do not want synced. The complete list of suppressable fields is:

{Country, EmailAddress, EmployeeId, FaxNumber, GivenName, HomeDirectory, HomePhone, IpPhone, Locality, MiddleName, MobileNumber, PagerNumber, PhysicalDeliveryOfficeName, PreferredLanguage, PostalCode, Region, StreetAddress, VoiceTelephoneNumber, ScriptPath, Description, DisplayName, SamAccountName, UserPrincipalName, Name}

Example: View the current list of suppressed fields.

ConfigManager> SyncComponent.SuppressedFields

The current list of suppressed fields is: IpPhone

Example: Add a suppressed field.

ConfigManager> SyncComponent.AddSuppressedField Region

The current list of suppressed fields is: IpPhone, Region

Example: Remove a suppressed field.

ConfigManager> SyncComponent.RemoveSuppressedField IpPhone

The current list of suppressed fields is: Region

SyncComponent.IncludeNotSetFields

AD Sync will sync blank fields to Workplace. Default behavior is to skip synchronization of blank fields.

Parameters

SyncComponent.IncludeNotSetFields { TRUE | FALSE }

Should you need to overwrite blank (unset) fields in Active Directory to the user profile in Workplace, you can set this command to TRUE. Where the default behavior (FALSE) is to ignore the fields that are blank on Active Directory.

?
Using this command will force an overwrite of the existing data to the user profile in Workplace if the data is blank on Active Directory.
Attribute Mappings

Attribute Mappings

The table below explains each of the AD attributes that are synchronized into Workplace:

Attribute

Active Directory Source

Workplace Target Field

User Name

mail

userName

External ID

GUID

externalId

Active

enabled

active

Title

title

title

Formatted Name

Configurable

formattedName

Given Name

givenName

name.givenName

Family Name

sn

name.familyName

Middle Name

middleName

name.middleName

Email Address

mail

emails.value

Location

Configurable

addresses['work'].formatted

Phone Number

Configurable

phoneNumbers['work'].value

Department

department

enterprise.department

Division

division

enterprise.division

Organization

o

enterprise.organization

Manager

manager

enterprise.manager.managerId

Preferred Language

preferredLanguage

preferredLanguage

Locale

N/A

N/A

Display Name

N/A

N/A

Nickname

N/A

N/A

Profile URL

N/A

N/A

Timezone

N/A

N/A

Honorific Prefix

N/A

N/A

Honorific Suffix

N/A

N/A

Cost Center

N/A

N/A

Photos

N/A

N/A

Start Date

N/A

N/A

Term Date

N/A

N/A

AD Sync Logs

AD Sync Logs

AD Sync writes application and audit logs that you can use to verify results and troubleshoot if necessary. Logs are available under:

C:\Users\{Service Account}\AppData\Local\Workplace by Facebook\AD Sync Service

?
Replace {Service Account} with the user you configured for running AD Sync (defaults to msvc.workplace$). Because of Windows security defaults, you may not yet have access to C:\Users\{Service Account} until you navigate to that directory in Explorer and grant your Admin user access to the directory.
C:\> cd "C:\Users\msvc.workplace$\AppData\Local"
C:\> cd ".\Workplace by Facebook\AD Sync Service"
C:\> dir

Directory of AD Sync Service

09/25/2019 10:38 PM <DIR> .
09/25/2019 10:38 PM <DIR> ..
09/25/2019 11:56 PM 12,232 2019-09-25-ad-sync-service-audit.csv
09/25/2019 11:56 PM 107,922 2019-09-25-ad-sync-service-log.txt

To troubleshoot AD Sync, open the latest log file and review the contents:

  • If you are running in Test mode, you should find entries in the log file that describe which users in your Active Directory user sources will be created and which existing Workplace users will be updated.
  • If you are running in Live mode: 1) You will see entries in the log file that describe the actual create and update actions that AD Sync has taken, along with other application log information, and 2) Separately, just user create and update actions are summarized in the audit log.
  • If you find error messages, try to fix the issue by looking at the error and checking that the installation is complete or get in contact with your Workplace technical point of contact.
Troubleshooting

Troubleshooting

This section covers the most frequent issues that can occur when installing and configuring AD Sync.

Installer: Windows cannot access specified device, path, or file.

Message: During installation you receive a message:

Windows cannot access the specified device, path, or file.
You may not have the appropriate permissions to access the item.

Root Cause: The user that is trying to run the installer doesn't have permissions to read the location where the installer is located.

Solution: You need to make sure that the user running the installer, has read rights to the folder where the installer is located. You can either do this by adding the installer in the user's local location (C:\Users\UserName) when running the installer as a different user or you can choose to run the installer as an administrator.

Installer: Could not determine that you are a domain administrator.

Message: During installation you receive a message:

Could not determine that you are a domain administrator.
Domain administrator is required to create the service account.
Setup will fail if you are not a domain administrator.
Do you wish to continue?

Root Cause: You're running the installer as a user that doesn't have domain administrator rights.

Solution: With the installer, it is possible to create a domain account or use an existing one, so the solution is different in both cases:

  • Creating a new service user requires domain administrator rights, so you will need to click on the “No” button when prompted and run the installer as administrator.
  • You can ignore the message by clicking on the “Yes” button in case you've already created a domain user that will be used in the next step.

Installer: User not domain admin.

Message: During installation you receive a message:

Workplace AD Sync Service installation failed:
User DOMAIN\UserName IS NOT a domain admin.

Root Cause: The service user that you've entered during the installation didn't exist in the current domain. Because of that, the installer will create a domain user but the user running the installer doesn't have domain admins rights.

Solution: You need to run the installer as a domain admin when you're creating a new domain user via the installer.

Installer: Failed to secure cache path.

Message: During installation you receive a message:

Workplace AD Sync Service installation failed:
Error 0x8007051b: Failed to secure cache path:
C:\ProgramData\Package Cache\

Root Cause: When you're running the installer, you need permissions to write to C:\Program Data\Package Cache\.

Solution: Run the installer as administrator.

ConsoleApp: Could not connect to the user source that you configured.

Message: Within the ConsoleApp, after you input a user source with the command Users.Add {param list}, you receive as a message:

Could not connect to the user source that you configured.
Double check your inputs.

Root Cause #1: When the synchronization server is reading the domain controller, the communication happens via LDAPS and this requires a certificate to ensure the SSL connection.

Solution #1: You can create a self-signed certificate in case that you've installed IIS which you need to install on both the synchronization server and the domain controller. You can also request a wildcard domain certificate in case that you don't want to use self-signed certificates.

Root Cause #2: When the synchronization server is reading the domain controller, the communication happens via LDAPS and this requires the firewall to be opened for port 636 (TCP).

Solution #2: Change the firewall of the domain controller to allow incoming connections through port 636 (TCP). Change the firewall of the synchronization server to allow outgoing connections through port 636 (TCP).

Root Cause #3: You've entered the wrong parameters in the Users.Add command.

Solution #3: Make sure that you enter the correct parameters which you can find in the AD Sync commands reference section. When you add a distribution list or security group, you don't need to specify the FQDN of the OU. When you add an organizational unit, you need to specify the FQDN of the OU along with the LDAP query.

ConsoleApp: Could not save configuration as it is not valid.

Message: Within the ConsoleApp, you tried to quit the program with the command Config.Exit but you receive as a message:

Could not save your configuration as it is not valid.
Make sure you have:
1) added and validated your API configuration, and
2) added at least one user source.

Root Cause: You haven't successfully added at least one user source via the Users.Add command.

Solution: You can add a user query by running the Users.Add command as described in the AD Sync commands section.

PushService: No users are synced to Workplace.

Message: The Users.Summary command lists my user sources but no users are synced to Workplace.

Root Cause #1: There aren't any valid users contained within the sources you have configured.

Solution #1: Make sure that all users have an email address or that users are added in the group/scope of the LDAP query.

Root Cause #2: The ConsoleApp is still configured to run in Test mode.

Solution #2: Change the SyncComponent.RunMode from Test to Live mode. Commands are described in the AD Sync commands reference section.

PushService: Remote service returned an error (401).

Message: While checking logs you observe the following error message:

PushService.AtWorkScimApi.IsWorkplaceReachable
IsWorkplaceReachable failed. System.Net.WebException:
The remote server returned an error: (401) Unauthorized.

Root Cause: The access token that was used during the installer was reset or the application itself has been deleted.

Solution: In case that the application was deleted, you'll need to recreate an application that has the manage accounts permissions. Once the application is created, you'll receive a new access token.

In case that the application is still there, you'll need to reset the token to retrieve a new token. If this is the case, please check within your organization if someone intentionally did a token reset for the application.

Once you've got a new token, you can rerun the Workplace AD Sync Installer, click on reconfigure, enter the new access token and continue with the installer without changing any other values. You might need to restart the server once you've reconfigured the Workplace AD Sync Installer.

PushService: Remote service returned an error (404).

Message: While checking logs you observe the following error message:

PushService.ScimRequestHelper.ExecuteRequest
WebException during SCIM invocation. System.Net.WebException:
The remote server returned an error: (404) Not Found.

Root Cause: The user was deleted in Workplace from the Admin Panel > People Section.

Solution: Rebuilding the database will resolve this issue. You can use the following steps to rebuild the database:

1
Stop the Workplace AD Sync Service.

2
Verify that the PushService.exe disappears from the Activity Monitor - Details tab.

3
Open the Command Line Prompt as the service user.

4
Run the following commands.

sqllocaldb i (list local db's)
sqllocaldb p “pushdb” (stop pushdb)
sqllocaldb d “pushdb” (delete pushdb)
sqllocaldb c “pushdb” (recreate pushdb)
sqllocaldb s “pushdb” (start pushdb)

5
Start the Workplace AD Sync Service.

PushService: Remote service returned an error (409).

Message: While checking logs you observe the following error message:

PushService.ScimRequestHelper.ExecuteRequest
WebException during SCIM invocation. System.Net.WebException:
The remote server returned an error: (409) Conflict.

Root Cause: This user has already been created within Workplace but the PushService does not have the user in the local cache.

Solution: In most cases, the PushService will automatically resolve this mismatch and no action is required by the admin.

PushService: Remote service returned an error (407).

Message: While checking logs you observe the following error message:

PushService.ScimRequestHelper.ExecuteRequest
WebException during SCIM invocation. System.Net.WebException:
The remote server returned an error: (407) Proxy Authn Required.

Root Cause: The machine uses a proxy which is not set up within the config.

Solution: Adding the following snippet in Pushservice.exe.config will resolve the issue, please make sure you replace the proxy details with your own:

</runtime>
<!-- new entry -->
<system.net>
<defaultProxy enabled="true"useDefaultCredentials="true">
<proxy proxyaddress="http://proxy IP:proxy port"
usesystemdefault="False"
bypassonlocal="True"
autoDetect="False" />
</defaultProxy>
</system.net>
<!-- end new entry -->
</configuration>

PushService: Invalid Config - No search roots exist

Message: After migrating the ADSync configuration, service log reported below error:

"Invalid Config - no search roots exist”

2020-06-25 17:26:15.7395 ERROR
PushService.ConfigManager.IsValidConfiguration Invalid config - no search roots exist.

2020-06-25 17:26:15.7395 FATAL
PushService.PushSyncSchedulerJob.Execute AD Sync Service configuration not found.

Solution: Restart the ADSync Service once.

ConsoleApp: Unauthorized Users Cannot Run the ConsoleApp

Message: If you run the console app, you receive a failure message:

PS C:\Windows\system32> "C:\Program Files (x86)\Workplace by Facebook\ADSyncService\ConsoleApp.exe"

You are not authorized to run the console app.
You must run the console app: 1) using an elevated prompt, and 2) as a member of the AD Domain Admins or Administrators group.

Solution: Run ConsoleApp using an elevated prompt using an administrator or domain administrator account.

ConsoleApp: Not a member of DomainAdmins or Administrators group

Message: In v15 and earlier, you would use runas to run the ConsoleApp.exe as the svc.workplace user:

C:\> runas /user:fbpe\svc.workplace "C:\Program Files (x86)\Workplace by Facebook\ADSyncService\ConsoleApp.exe"

Cannot start the console app. The current user is not a member of DomainAdmins or Administrators group.

Solution: Login to the server using an administrator / domain admin account and start an Elevated Powershell again.