Active Directory Sync

Overview

The Workplace AD Sync Component lets you sync 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 AD Sync replicates from AD 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)
  • De-provision (deactivate) user accounts as people depart your organisation, or should no longer have access

Compared with building, testing, and documenting a custom SCIM API client, using AD Sync should save considerable time and effort.

Key Functionality, Limitations, and Requirements

Data Flow

AD Sync runs as a Windows Service within your IT infrastructure. After you configure it to query AD for the set of users you would like to give access to Workplace, AD Sync will run on a schedule every three hours to reconcile accounts between AD and Workplace.

AD Sync does a one-way batch replication of selected users' profile data

Limitations

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
  • Can only be configured to sync users based on: 1) LDAP filters (e.g., a specific user class or attribute value), or 2) AD security / distribution groups
  • Will only handle 100,000 users max (approx.) 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: 1) formatted name, and 2) location; All other attributes will be mapped by default logic (see the Synchronized Attributes Reference table below 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

Requirements

  • The software 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. Other 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, you may need to follow the installation and configuration procedure for AD Sync on a server in each domain
  • The following Microsoft components are required and will be installed with AD Sync if they're not already on the server: 1) .NET Framework 4.5.2, and 2) SQL Server 2014 Express LocalDB (a light version of SQL Server Express) to store user data. All cumulative updates should be installed.
  • For each group of users that you want to sync to Workplace by Facebook, you must identify: 1) the Distinguished Name (DN) of the root entry in Active Directory that contains the users, and 2) either an LDAP Filter or an Active Directory Group that identifies the users you want to sync to Workplace
  • Your Domain Controller must be able to support LDAPS (SSL) connections over port 636

Installation Guide

Before You Start

  • Choose a domain-joined Windows Server where AD Sync will run — i.e., the AD Sync Server
  • You must be able to use Remote Desktop to the AD Sync Server using a Domain Administrator account to run the installer.

After installation, AD Sync does not run with any admin privileges; it will run under the identity of a user account that you choose

  • AD Sync will always be able to read user accounts from the current domain. 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
  • An SSL Certificate must be installed on the AD DC to enable encrypted LDAPS communication to the Domain Controller
  • The AD Sync Server must have the ability to communicate to www.facebook.com over HTTPS

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.

Installation Procedure

I. Enable Your Workplace API Connection & Collect Configuration Parameters

You must have been granted the System Administrator role within your Workplace Instance so that you can view your API connection parameters.

  1. Open Workplace's Admin Panel > Settings tab
  2. Within the Integrations section:
  3. Create an integration app by following the steps described on the creating a custom integration page.

    Ensure this permission is ticked: Manage accounts

  4. When the application is created, save your Access Token since it will only be displayed once.

II. Download the Installer Binary

Download AD Sync Installer

III. Verify Installer's Authenticity

  • Verify that the installer is signed by Facebook by right clicking the installer, choosing Properties, and then click on the Digital Signatures tab.
  • Click on the signature from Facebook, Inc. and then click on the Details button.
  • Look for the text that says "This digital signature is OK."
Look for 'The digital signature is OK' from Facebook, Inc. to verify the integrity of the installer.

IV. Install AD Sync

Using a Domain Administrator account, connect to the AD Sync Server using Remote Desktop. Copy the installer binary to the server and double click it to run the installer.

  • Click Next on the welcome screen
  • Accept the license terms and click Next
  • Input your Workplace API connection parameters from Section I above and click Next to continue
  • Input a password for the user account that AD Sync will use as its logon identity. Input the same password to confirm.

AD Sync service must run under the identity of a Domain User. By default, the installer will create a new user account in the current domain called "svc.workplace" using the password you input.

You may optionally input another username to: 1) create a new user with a different username than the default, or 2) have AD Sync run under the identity of an existing Domain User account.

  • 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 on this step.

Configuration Guide

Introduction

AD Sync relies on a set of configuration values that you provide. These configuration values belong to two categories:

  1. Users - defines the set of users from your Active Directory Domain that should be synced to Workplace, e.g., one or more Active Directory distribution groups
  2. SyncComponent - Operational behavior of AD Sync itself, e.g., whether to run in test or live mode

You need to establish an initial configuration when you first install AD Sync by running the console application (ConsoleApp.exe). Afterwards, you can modify the configuration by re-running the console application and inputting different configuration values.

Prerequisites

  • You need to complete AD Sync Installation Procedure described above
  • You must be able to connect to the AD Sync Server via Remote Desktop
  • You must be able to run programs using the same user account that you have specified for the AD Sync user's logon identity

Starting the Configuration Manager Program

  • Use RemoteDesktop to logon to the AD Sync Server using a domain administrator account
  • Open a command prompt as an administrator by clicking Start > Search > cmd.exe > Right Click > Run as Administrator
  • Run the configuration manager application using the svc.workplace user's identity:
C:\> cd "C:\Program Files (x86)\Workplace by Facebook\ADSyncService"
C:\> runas /user:yourdomain\svc.workplace "ConsoleApp.exe"
  • Input the password for the user
  • 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>

The configuration manager has a set of commands and options that lets you control how AD Sync functions.

  • You can get help with the Configuration manager overall by inputting “Help” at any time
  • You can exit the program by inputting “Exit” at any time
  • You can get help with a specific command by inputting the command name and specifying the help option:
ConfigManager> Users.Help
Users commands control how the Sync Component selects users from your Active Directory domain to sync into Workplace.
* Users.Summary - get a summary of your current user source configuration
...

For more information about each of the configuration commands, see the commands reference sections below.

High-Level Configuration Steps

More detail about AD Sync audit and application log files is given in the section AD Sync Log Files below

  1. Choose the Set of Workplace Users - Use the Users.Add command to add your Active Directory user sources, e.g., one or more Active Directory groups or LDAP filters that define the set of users that should have access to Workplace
  2. Restart AD Sync - to enact the configuration changes.
  3. Allow a full run to complete - Depending on how many users are in your user sources, this could finish within a few minutes or it could take much longer. AD Sync will output a line to the application log when it completes its run - look for the text Completed PushSyncJob.Execute() method
  4. Verify Test Mode Results - By default, AD Sync runs in test mode — in other words, no users will actually be created or updated in Workplace. This gives you a chance to review AD Sync's configuration without actually changing Workplace user accounts.
  5. Run in Live Mode - When you've verified your user source configuration, update your configuration using the SyncComponent.RunMode command to use Live mode.
  6. Restart AD Sync - to enact the configuration changes.
  7. Allow a full run to complete
  8. Verify Live Mode Results - Review the audit logs to confirm that the correct user accounts are being created. After a full run is complete, you can request an export of all your users from Workplace (Admin Panel > People > Menu > Export) to verify that the user profiles are populated as you expect.

Restarting AD Sync

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.

  • Open the services management console by clicking Start > Search > services.msc
  • Within the Services Management Console, find the item Workplace AD Sync Service. Right click this entry and choose “Restart”.

Users Commands Reference

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

Summary

Name:
Users.Summary
Description:

Output the current user sources.

Usage:

Usage example

ConfigManager> Users.Summary
  Configured user sources:
1 - DC=Fabrikam,DC=COM GROUP "Domain Users"
2 - OU=Sales,DC=Fabrikam,DC=COM GROUP "AtWork Users"

Add User Source

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

Name:
Users.Add {container} {type} {value} {confirm}
Description:

You can configure AD Sync with one or more user sources, where each user source has three parts:

  1. A root container, also known as a Distinguished Name (DN), that a set of users are organized underneath within your AD
  2. A type, which is either a group or an LDAP filter
  3. A value that defines the set of users within that DN. There are two types of query: a) AD Group an AD security or distribution group's name, or b) 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

Each of these concepts is explained in more detail below.

Container
  • a container or DN is similar to a web domain (e.g., www.facebook.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.

AD Group

AD has two types of groups: security and distribution. In either case, a simple way of managing access to Workplace is to:

  1. Establish an AD group of either type and add those users who you want to grant access to Workplace
  2. Configure AD Sync to use this group as the user source
LDAP Filter Query
  • The other alternative is to define an LDAP filter for the set of users underneath a DN that should 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 on TechNet.

Usage:

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 the first 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
keeva@fabrikam.com - Keeva Adams

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.

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 the first 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
keeva@fabrikam.com - Keeva Adams

Add an LDAP filter user source to the configuration:

ConfigManager> Users.Add OU=Sales,DC=Fabrikam,DC=Com LDAP "(&(mail=*)(objectClass=person))" True
  This user source has been added to the configuration.

Root Container

Name:
Users.RootContainer
Description:

Output the current Active Directory domain's root container.

Usage:

Usage example

ConfigManager> Users.RootContainer
  The current Active Directory top-level container is: DC=Fabrikam,DC=COM

Remove User Source

Name:
Users.Remove {index} {confirmed}
Description:

Remove a previously-configured user source.

Usage:

Preview removing a user source:

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

Confirm removing a user source:

ConfigManager> Users.Remove 2 True
  This user source has been removed from the configuration.

AD Sync Commands Reference

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.

Summary

Name:
SyncComponent.Summary
Description:

Summarizes your current AD Sync configuration.

Run Mode

Name:
SyncComponent.RunMode {TEST | LIVE}
Description:

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

In Test mode, AD Sync will:

  • Simulate sync behavior using the current configuration but without creation or changing user accounts in Workplace
  • Iterate over your User Sources and compare to existing users within Workplace
  • Output to the application log files whether a given user will be created or updated

In Live mode, AD Sync will:

  • Actually run and create / update / deactivate users in Workplace using the current configuration.
  • Create users in Workplace, if (1) there is newly added user source which contains new users, or (2) there are new users added to existing user sources in Active Directory, since last run.
  • Deactivate users in Workplace, if (1) the user accounts are no longer retrievable through any of the configured user sources, or (2) the corresponding user account is disabled in Active Directory.

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.

Usage:

Verify the current run mode:

ConfigManager> SyncComponent.RunMode
  The Sync Component is configured to run in TEST mode.

Update the run mode:

ConfigManager> SyncComponent.RunMode LIVE
  The Sync Component will now run in LIVE mode.

Force Sync

Name:
SyncComponent.ForceSync {TRUE | FALSE}
Description:

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.

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.

Usage:

Update the force sync:

ConfigManager> SyncComponent.ForceSync TRUE
  The Sync Component will execute a full sync.

Log Output Level

Name:
SyncComponent.LogLevel {level}
Description:

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
Usage:

View the current log level:

ConfigManager> SyncComponent.LogLevel 
  The log level is: Warn

Update the current log level:

ConfigManager> SyncComponent.LogLevel DEBUG
  The log level has been updated to: Debug

Formatted Name Style

Name:
SyncComponent.FormattedNameStyle { DISPLAY_NAME | COMMON_NAME |
  GIVEN_THEN_SURNAME | SURNAME_THEN_GIVEN | SURNAME_COMMA_GIVEN_MIDDLE_INITIAL }
Description:

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. This screenshot highlights the key fields related to a user's name

The AD Admin Center tool's User Attribute Editor shows the formatted name style source attribute alternatives: displayName, cn, givenname, and sn.

Usage:

View the current formatted name style:

ConfigManager> SyncComponent.FormattedNameStyle
  The formatted name style is: GIVEN_THEN_SURNAME

Updated the formatted name style:

ConfigManager> SyncComponent.FormattedNameStyle COMMON_NAME
  The formatted name style has been updated to: COMMON_NAME

Formatted Address Style

Name:
SyncComponent.FormattedAddressStyle { LOCALITY | CONCATENATE_ALL | 
PHYSICAL_DELIVERY_OFFICE_NAME | CONCATENATE_LOCALITY_AND_OFFICE }
Description:

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 - physicalDelivery OfficeName 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

Usage:

View the current formatted address style:

ConfigManager> SyncComponent.FormattedAddressStyle
  The formatted address style is: PHYSICAL_DELIVERY_OFFICE_NAME
Update the formatted address  style:
ConfigManager> SyncComponent.FormattedAddressStyle LOCALITY
  The formatted address style has been updated to: LOCALITY

Primary Phone Type

Telephone numbers must be in the format +{country code} number in order to display in Workplace. Eg +6512345678

Name:
SyncComponent.PrimaryPhoneType {type}
Description:

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

  • Telephone
  • Fax
  • Home
  • IP
  • Mobile
  • Pager
Usage:

View the current primary phone type:

ConfigManager> SyncComponent.PrimaryPhoneType 
  The primary phone type is: TELEPHONE_NUMBER

Update the primary phone type:

ConfigManager> SyncComponent.PrimaryPhoneType MOBILE_NUMBER
  The primary phone type has been updated to: MOBILE_NUMBER

Run Interval

Name:
SyncComponent.RunInterval {hours}
Description:

By default, AD Sync will run approx. every 3 hours. It is possible to override this frequency to be as often as approx. every 1 hour or as infrequently as approx. 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.

Usage:

View the current run interval:

ConfigManager> SyncComponent.RunInterval
  The run interval is approx. every 3 hours

Update the current 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.

Default Claim Email Language

Name:
SyncComponent.ClaimEmailLanguage {language}
Description:

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.

Usage:

View the current default claim email language:

ConfigManager> SyncComponent.ClaimEmailLanguage
  The claim email language code is: en_GB

Update the default claim email language:

ConfigManager> SyncComponent.ClaimEmailLanguage fr_FR
  The claim email language code has been updated to: fr_FR

Username Source

Name:
SyncComponent.UsernameSource {EMAIL_ADDRESS | UPN}

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.

Description:

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.

Usage:

View the current username source:

ConfigManager> SyncComponent.UsernameSource
  The username source is: EMAIL_ADDRESS

Update the username source:

ConfigManager> SyncComponent.UsernameSource EMAIL_ADDRESS
  The username source has been updated to: EMAIL_ADDRESS

Department Source

Name:
SyncComponent.DepartmentSource {DEPARTMENT | COMPANY_PLUS_DEPARTMENT}
Description:

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.

Usage:

View the current department source:

ConfigManager> SyncComponent.DepartmentSource
  The department source is: DEPARTMENT

Update the department source:

ConfigManager> SyncComponent.DepartmentSource COMPANY_PLUS_DEPARTMENT 
  The department source has been updated to: COMPANY_PLUS_DEPARTMENT 

Suppressed Fields

Name:
SyncComponent.SuppressedFields
Description:

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.

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

The complete list of suppressable fields is:

  • Country
  • EmailAddress
  • EmployeeId
  • FaxNumber
  • GivenName
  • HomeDirectory
  • HomePhone
  • IpPhone
  • Locality
  • MiddleName
  • MobileNumber
  • PagerNumber
  • PhysicalDeliveryOfficeName
  • PreferredLanguage
  • PostalCode
  • Region
  • StreetAddress
  • Surname
  • VoiceTelephoneNumber
  • HomeDrive
  • ScriptPath
  • Description
  • DisplayName
  • SamAccountName
  • UserPrincipalName
  • Name
Usage:

View the current list of suppressed fields:

ConfigManager> SyncComponent.SuppressedFields
  The current list of suppressed fields is: IpPhone 

Add a suppressed field:

ConfigManager> SyncComponent.AddSuppressedField Region 
  The current list of suppressed fields is: IpPhone, Region

Remove a suppressed field:

ConfigManager> SyncComponent.RemoveSuppressedField IpPhone 
  The current list of suppressed fields is: Region

Log Files

AD Sync writes application and audit logs that you can use to verify results and troubleshoot if necessary:

  • Using the same procedure you used to start the Config Manager, open a command prompt to run programs using the workplacesync user's identity
c:\>runas /user:yourdomain\svc.workplace "cmd.exe"
  • Navigate to the application log directory and find the most recent log file:
c:\>cd %LocalAppData%\"Workplace by Facebook\AD Sync Service"
C:\Users\workplacesync\AppData\Local\Workplace by Facebook\AD Sync Service> dir
Directory of C:\Users\workplacesync\AppData\Local\Workplace by Facebook\AD Sync Service
06/25/2016  10:38 PM    <DIR>          .
06/25/2016  10:38 PM    <DIR>          ..
06/23/2016  11:56 PM            12,232 2016-06-23-ad-sync-service-audit.csv
06/23/2016  11:56 PM           107,922 2016-06-23-ad-sync-service-log.txt
  • Note: because of Windows security defaults, you may not yet have access to C:\Users\workplacesync until you navigate to that directory in Explorer and grant your Admin user access to the directory
  • 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

Synchronized Attributes Reference

The table below explains each of the Active Directory attributes that are synchronized into Workplace.

Attribute NameActive Directory SourceWorkplace Destination
User Name

mail

userName

External ID

GUID

externalId

Active

enabled

active

Title

title

title

Formatted Name

Configurable:

DISPLAY_NAME,

COMMON_NAME,

GIVEN_THEN_SURNAME,

SURNAME_THEN_GIVEN,

SURNAME_COMMA_GIVEN_MIDDLE_INITIAL

formattedName

Given Name

givenName

name.givenName

Family Name

sn

name.familyName

Middle Name

middleName

name.middleName

Email Address

mail

emails.value

Location

Configurable:

LOCALITY,

CONCATENATE_ALL,

PHYSICAL_DELIVERY_OFFICE_NAME,

CONCATENATE_LOCALITY_AND_OFFICE

addresses['work'].formatted

Phone Number

Configurable:

TELEPHONE_NUMBER,

FAX_NUMBER,

HOME_NUMBER,

IP_NUMBER,

MOBILE_NUMBER,

PAGER_NUMBER

phoneNumbers['work'].value

Department

department

extension:enterprise.department

Division

division

extension:enterprise.division

Organization

o

extension:enterprise.organization

Manager

manager

extension: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

Troubleshooting

1. Installer Error

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.

2. Installer Error

MESSAGE

Could not determine that you are a domain administrator. Domain administrator privileges are 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.

3. Installer Error

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.

4. Installer Error

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

5. ConsoleApp Error

ACTION

Within the ConsoleApp, you input a user source with the command Users.Add {param list}

MESSAGE

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

ROOT CAUSE ONE

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 ONE

You can create a self-signed certificate in case that you've installed IIS (https://technet.microsoft.com/en-us/library/cc753127(v=ws.10).aspx) 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 TWO

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 TWO

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 THREE

You've entered the wrong parameters in the “Users.Add” command.

SOLUTION THREE

Make sure that you enter the correct parameters which you can find on the developer docs (https://developers.facebook.com/docs/workplace/account-management/sync-tool#userscommands). 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.

6. ConsoleApp Error

ACTION

Within the ConsoleApp, you tried to quit the program with the command Config.Exit

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 developer docs

7. PushService Unexpected Behavior

BEHAVIOR

The “Users.Summary” lists my user sources but no users are synced to Workplace

ROOT CAUSE ONE

There aren't any valid users contained within the sources you have configured

SOLUTION ONE

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

ROOT CAUSE TWO

The ConsoleApp is still configured to run in TEST mode

SOLUTION TWO

Change the "SyncComponent.RunMode" from TEST to LIVE mode

8. PushService Error

MESSAGE (IN LOG FILE)

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

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.

9. PushService Error

MESSAGE (IN LOG FILE)

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

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 the pushdb)
    • sqllocaldb d “pushdb” (delete the pushdb)
    • sqllocaldb c “pushdb” (recreate the pushdb)
    • sqllocaldb s “pushdb” (start the pushdb)
  5. Start the Workplace AD Sync Service

10. PushService Error

MESSAGE (IN LOG FILE)

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

11. PushService Error

MESSAGE (IN LOG FILE)

ERROR PushService.AtWorkScimApi.IsWorkplaceReachable IsWorkplaceReachable failed. System.Net.WebException: The remote server returned an error: (407) Proxy Authentication 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>