Sync users and groups with the LDAP directory

If your company uses Active Directory, you can set up automatic synchronization of employees and groups with Yandex 360 for Business by installing and configuring a special Windows service.

Attention. If you want to enable synchronization of users from Active Directory, install YandexADSCIM (a Windows service utility) following the instructions below and run it from the LDAP directory as a user with read permissions. YandexADSCIM is managed via Services. You can change its settings in the configuration file.

Other LDAP directories will be fully supported in the future when the YandexADSCIM utility is ported to *nix platforms. It can already be used with other LDAP directories, but for this, you need to run the utility on a Windows device.

Connect and configure the ADSCIM utility

Step 1. Begin setup

Check that single sign-on (SSO) is enabled and works correctly .
Set a unique user ID: select an Active Directory attribute to transfer in the PropertyLoginName Active Directory setting and add it to the Yandex catalog.
Attention. The attribute that you set as the primary ID must not change. A user who logs in with a different attribute is considered a new user.
If your users already use Yandex 360 services and log in via ADFS, make sure that the NameID field matches the primary ID from PropertyLoginName:
- UserPrincipalName (UPN): If the login parameters won't change.
- objectSID: If you plan to make changes to the domain.
Check that the following user attributes in Active Directory are filled in:
- Primary ID.
- User SamAccountName.
- Email.

Step 2. Get a Client ID and an OAuth token

Go to the Create an application page.
Enter the name of the service and attach its icon.
In the Platforms block, select Web services. In the Redirect URI field, click Enter URL for debugging.
In the Data access block, enter Managing federations at the beginning of the line.
Enter your contact email. At the bottom of the page, click Create application.
Send a POST request to get an OAuth token. For example, you can do this via cURL using the following command:
```
curl -X POST https://oauth.yandex.ru/token -d "grant_type=client_credentials&client_id=value1&client_secret=value2"
Copied to clipboard
```
(client_id is the ID of the created application, and client_secret is its Password)
Save the ID and OAuth token. You'll need them in the next steps.

Step 3. Specify the Client ID in Yandex 360 and get a Domain ID

Open Yandex 360 for Business.
Go to the Single sign-on (SSO) tab.
Click Set up.
In the SCIM synchronization block, paste the ID you received in Step 2.
Copy your Domain ID. You'll need it in the next step.
Save changes.

Step 4. Install and configure the Windows service for synchronization

Download and install the YandexADSCIM utility.

Find and open the configuration file %ProgramData%\Yandex\YandexADSCIM\AD_Users.config in any text editor.

Tip. If you find can't find the %ProgramData% folder, enable the option todisplay hidden files.

Configure the configuration file:

Check whether the path for connecting to Active Directory is specified correctly in the LDAP parameter value. If not, correct it.
In the BearerToken parameter value, enter the OAuth token you received in Step 2.
In the DomainID parameter value, enter the Domain ID your received in Step 3.
Change the DryRun parameter value to false if you want to start SCIM synchronization immediately. If the value is set to true, the service will launch in test mode, recording requests in logs but not syncing employees and groups.

Sync a typical set of user data from Active Directory. The application will ignore the lines that begin with #.


YandexADSCIM utility setting name	Attribute name	Default value from Active Directory	Example
PropertyFirstName	First name	givenName	Ivan
PropertyMiddleName	Middle name	middleName	Ivanovich
PropertyLastName	Last name	sn (SurName)	Ivanov
PropertyWorkMail	Primary email	mail	I_ivanov@domain.ru
PropertyTitle	Position	Title	Developer


YandexADSCIM utility setting name	Attribute name	Default value from Active Directory	Example
PropertyFirstName	First name	givenName	Ivan
PropertyMiddleName	Middle name	middleName	Ivanovich
PropertyLastName	Last name	sn (SurName)	Ivanov
PropertyWorkMail	Primary email	mail	I_ivanov@domain.ru
PropertyTitle	Position	Title	Developer

The parameters of attributes that start with Property can be reassigned when creating or syncing users in Yandex 360.

Learn more

PropertyLoginName = objectSid/objectGUID/UPN, where UPN is the default value. If you use an attribute of the username and not the username@domain.com type, add the IgnoreUsernameDomain = true key. The value of this attribute must be equal to the value of the NameID attribute from the SSO settings:

PropertyFirstName = User first name
PropertyMiddleName = User middle name
PropertyLastName = User last name
PropertyDisplayName = User display name
PropertyWorkMail = User email
PropertyTitle = User job title
PropertyMobilePhoneNumber = Mobile phone number
PropertyWorkPhoneNumber = Work phone number
PropertyIpPhoneNumber = User ip phone number

Parameters that start with Property can be specified several times. In that case, the parameter value will be a list.

For example, to get the user's last name, you can set attributes PropertyLastName = surName, PropertyLastName = sn, PropertyLastName = lastName. If the surName attribute exists, its value will be used. If this attribute is missing, the sn attribute value will be used. If it's also missing, the lastName attribute value will be used.

If you need to sync mailbox aliases from Active Directory with Yandex 360 for Business, add the EnableAliases parameters with the true value. Domain mailbox aliases that are specified in the proxyAdresses user attribute in Active Directory with the SMTP type will be added to the employee account in Yandex 360 for Business automatically.

Important. For correct synchronization of aliases, use the YandexADSCIM utility of version 1.1.0.144 or higher.
Create an LDAP directory address by entering your own values in the search parameters.
For a search query, use the path from the DIT = Directory Information Tree structure (read from right to left): LDAP = LDAP://CN=Users,OU=DomainGroup,DC=YourCompanyName,DC=com
- DC: domainComponent, your own domain and domain zone.
- OU: OrganizationUnit, company\department\ from which you want to get users.
- CN: commonName, the name of the object you want to get from the catalog.
To limit user upload, you can use UsersFilter and apply the standard LDAP query syntax:
UsersFilter =(memberOf=CN=groupname,CN=Users,DC=domainname,DC=com)
Sync groups from Active Directory by adding the EnableGroups parameter with the true value.

To limit the list of groups, you can use GroupsFilter and apply the standard LDAP query syntax. For example, to upload all mailing lists, use the following filter:

GroupsFilter =(&(objectClass=group)(!(groupType:1.2.840.113556.1.4.803:=2147483648)))

Sync a typical set of group attributes from Active Directory.


YandexADSCIM utility setting name	Attribute name	Default value from Active Directory	Example
PropertyGroupDisplayName	Name	name	Integration project
PropertyGroupDescription	Description	description	Employees involved in the integration project
PropertyGroupEmail	Mailing list	mail	int@domain.ru


YandexADSCIM utility setting name	Attribute name	Default value from Active Directory	Example
PropertyGroupDisplayName	Name	name	Integration project
PropertyGroupDescription	Description	description	Employees involved in the integration project
PropertyGroupEmail	Mailing list	mail	int@domain.ru

The parameters of attributes that start with Propertycan be reassigned when creating or syncing groups in Yandex 360.

Learn more

These parameters can be specified several times. In this case, the parameter value will be a list.

For example, to get the name of a group, you can set attributes PropertyGroupDisplayName = name, PropertyGroupDisplayName = cn. If the name attribute exists, its value will be used. If this attribute is missing, the value of the cn attribute will be used.

Change the value of the DryRun parameter to true before launching the service for the first time. The service launch frequency is determined by the UpdateEveryMins = N parameter, where N is the interval in minutes. Launch the service via a snap-in and analyze the log file.

System messages in logs


Notification	Result
CORE Update user: user@domain.ru (Active:true -> false)	User will be blocked.
SCIM Update user	User attributes in the Yandex catalog changed.
SCIM Add user	User added to the Yandex catalog.
CORE Users: added 0, removed 3237, modified 0	Added – 0, blocked – 3237, changed – 0.
SCIM GET Users: Response is successful	Users successfully read from the Yandex catalog.
AD Received user count: N	N users loaded from Active Directory.
AD Received groups count: N	N groups loaded from Active Directory.
AD_CONFIG Wrong line N	Error in line 31 of the configuration file.


Notification	Result
CORE Update user: user@domain.ru (Active:true -> false)	User will be blocked.
SCIM Update user	User attributes in the Yandex catalog changed.
SCIM Add user	User added to the Yandex catalog.
CORE Users: added 0, removed 3237, modified 0	Added – 0, blocked – 3237, changed – 0.
SCIM GET Users: Response is successful	Users successfully read from the Yandex catalog.
AD Received user count: N	N users loaded from Active Directory.
AD Received groups count: N	N groups loaded from Active Directory.
AD_CONFIG Wrong line N	Error in line 31 of the configuration file.

Stop the service and run it again to apply the changes from the configuration file. To do this, enter sc stop yandexadscim and then sc start yandexadscim in the command line (cmd.exe). You can also do this in the task manager on the Services tab.

Change settings

If you want to change settings, make changes to the configuration file and then restart the YandexADSCIM utility via the command line or from the task manager.

View logs

All logs are saved in the folder %ProgramData%\Yandex\YandexADSCIM.

Stop the service

YandexADSCIM is a Windows service, so it is launched automatically at system startup and doesn't depend on the user's status. You can disable it manually by entering sc stop yandexadscim in the command line or clicking Stopin the task manager.

If you want to delete the service permanently, use the command sc delete yandexadscim.

Possible situations during service operation


Situation	Result
User attributes in Active Directory have changed, but the ID hasn't changed.	The system will update the attributes in the Yandex catalog (except for the primary email and NameID).
User ID has changed.	The system won't be able to find the object with the original ID and will block the user. Then the system will try to add a user with a new ID but won't be able to do this because the username is already taken. If you delete a blocked user, the system will add a new user without transferring any data from the old account.
User has been deleted in Active Directory.	The user will be blocked in the Yandex catalog.
New user in Active Directory.	The user will be added to the Yandex catalog with the appropriate attributes.
All users in the Yandex catalog are blocked.	This might happen if: The main ID field has changed. For some reason, the application failed to read users from Active Directory.


Situation	Result
User attributes in Active Directory have changed, but the ID hasn't changed.	The system will update the attributes in the Yandex catalog (except for the primary email and NameID).
User ID has changed.	The system won't be able to find the object with the original ID and will block the user. Then the system will try to add a user with a new ID but won't be able to do this because the username is already taken. If you delete a blocked user, the system will add a new user without transferring any data from the old account.
User has been deleted in Active Directory.	The user will be blocked in the Yandex catalog.
New user in Active Directory.	The user will be added to the Yandex catalog with the appropriate attributes.
All users in the Yandex catalog are blocked.	This might happen if: The main ID field has changed. For some reason, the application failed to read users from Active Directory.

App updates

The application periodically makes a request to the developer about the availability of a new version and is automatically updated if the flag is set to AutoUpdate = True. The setting doesn't work if launch the application from a particular user.