Syncing users and groups with the LDAP directory using ADSCIM

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

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.

Currently, full support is provided for Active Directory, Samba DC, and Red ADM. 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.

Connection and initial setup of ADSCIM

Step 1. Begin setup

Check that single sign-on (SSO) is enabled and works correctly . How to enable single sign-on (SSO)
Set a unique user ID:
- Select an Active Directory attribute to pass it to the PropertyLoginName parameter of the ADSCIM utility for it to be added to the Yandex directory:
  - UPN (userPrincipalName in ADSCIM) if user login names won't change.
  - objectSID, objectGUID, or another attribute if there are planned changes to the domain or business processes that may result in changes to user UPNs.
Alert

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 authenticate via the SAML 2.0 protocol, make sure the attributes match: the value of the NameID attribute specified in Active Directory must correspond to the primary ID of the ADSCIM utility, PropertyLoginName.
For more information about PropertyLoginName, see Step 4, Point 2.5.
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

Create your OAuth application according to the instructions from the Yandex ID OAuth Help. Keep in mind that:
- You need to log in to the OAuth service with the organization owner's account.
- In the section Data access, you need to enter scim and select the suggested access Managing federations.
On the application page, copy the:
- Application ID from the ClientID field.
- Secret key from the Client secret field.
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"
```
where the value of the client_id parameter is the ID of the created application, and client_secret is its secret key.
Copy the token value and save it. You'll need them in the next steps.

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

Open the organization's account in Yandex 360 for Business. View
Go to General settings → Single sign-on (SSO).
Click Set up.
In the SCIM synchronization block, paste the ID of your app you obtained 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. Download the installation file

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

Tip

If you find can't find the %ProgramData% folder, enable the option to display hidden files. How to do this

Each setting in the configuration file should be a key=value pair written in a separate line. The service ignores lines that start with the # symbol.

Configure the configuration file:

Make sure that the value of the LDAP parameter contains the correct path for connecting Active Directory. If not, correct it. Substitute your own values into the search parameters.

For the search query, use the path from the structure DIT = Directory Information Tree (reads right to left):
```
LDAP = LDAP://CN=Users,OU=DomainGroup,DC=YourCompanyName,DC=com
```
where
- 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.
If there are several paths, list each on a new line. For example:
```
LDAP = LDAP://OU=DomainGroup1,DC=YourCompanyName,DC=com
LDAP = LDAP://OU=DomainGroup2,DC=YourCompanyName,DC=com
```
Paths are combined into a list and synced in the order they are specified. There's no limit on the number of paths you can add.

A configuration with multiple LDAP paths allows connecting to multiple Active Directory forests, if there are trust relationships between them.
In the BearerToken parameter value, enter the OAuth token you received in Step 2.
In the DomainID parameter value, enter the Domain ID you received in Step 3.
By default, DryRun is set to true. If you leave this value, the service will work in test mode at this stage. Queries will be logged, but no synchronization will be performed. To enable SCIM synchronization at this point, set the parameter to false.

Synchronize user data from Active Directory. To reassign attributes when creating or synchronizing users in Yandex 360, use parameters that start with Property.

The PropertyLoginName parameter corresponds to the user ID and can take one of three values:

userPrincipalName — UPN, default value.
objectSID.
objectGUID.

The parameter value must match the value of the NameID attribute.

If you're using an attribute that looks like username, and not like username@domain.com, then additionally specify the IgnoreUsernameDomain parameter setting it to true.

For other user attributes:

Name of the parameter for the YandexADSCIM utility	Attribute name	Default value from Active Directory	Example
PropertyFirstName	First name	givenName	Ivan
PropertyMiddleName	Middle name	middleName	Ivanovich
PropertyLastName	Last name	sn (SurName)	Ivanov
PropertyDisplayName	Displayed name	displayName	Ivanov I. I.
PropertyWorkMail	Primary email	mail	I_ivanov@domain.ru
PropertyTitle	Position	title	Developer
PropertyMobilePhoneNumber	Mobile phone	mobile	+7 012 345-67-89
PropertyWorkPhoneNumber	Work phone	telephoneNumber	+7 495 123-45-67
PropertyIpPhoneNumber	IP phone	ipPhone	7495 012-34-56

Parameters that start with Property can be specified several times. In that case, the parameter value will be a list. The order of attributes is important. 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.

To prevent the blocking of users in Yandex 360 during sync, add the parameter AllowUsersDeletion with the value False. In this case, users won't be blocked in the Yandex 360 organization when they're deleted from Active Directory. Default value: True.
To limit user upload, you can use UsersFilter and apply the standard LDAP query syntax.

If you specify multiple LDAP paths in the configuration file, the filter UsersFilter is applied to all paths.
- To select users based on whether or not they're part of a certain group, use the filter:
```
UsersFilter =(memberOf=CN=groupname,CN=Users,DC=domainname,DC=com)
```
- If you need to additionally exclude users that were blocked in Active Directory, use the filter:
```
UsersFilter =(&(memberOf=CN=groupname,CN=Users,DC=domainname,DC=com) (!(userAccountControl:1.2.840.113556.1.4.803:=2)))
```
  Following the synchronization, users who are registered in the email domain of your organization but were filtered out will be blocked.
To sync mailbox aliases from Active Directory:
- Add the parameter EnableAliases with the value True.
- Specify aliases with the SMTP type and the prefix smtp: or SMTP: in the user attribute proxyAdresses.
Aliases will be added automatically to the employee's account in Yandex 360 for Business.

For correct synchronization of aliases, use the YandexADSCIM utility of version 1.1.0.144 or higher. Download the installation file
To sync aliases of certain domains only:
- Add the parameter AliasesDomains.
- List the domains separated by spaces:
```
AliasesDomains = domain1.com domain2.com domain3.org
```
Rules for processing email addresses:
- The email address on the domain from AliasesDomains is passed as an alias in SCIM.
- An email address on a domain not from the list is passed in the attribute emails with the parameter Primary = false.
- If the AliasesDomains parameter is missing, aliases of all domains in the organization are synced.
How it works
If there's an organization with settings:
- In the Yandex 360 organization, the domain domain1.com is added.
- In the SCIM configuration, AliasesDomains = domain2.com.
- In the attribute proxyAddresses of the user in Active Directory, the addresses are specified:
  - SMTP:user1@domain1.com;
  - smtp:user2@domain2.com;
  - smtp:user3@domain3.com.
Once synced, the user's alias list will include:
- user1: Domain domain1.com added to the Yandex 360 organization.
- user2: Domain domain2.com specified in AliasesDomains.
The address user3@domain3.com will be fully transferred to the attribute emails with the parameter Primary = false, since the domain domain3.com isn't added to the Yandex 360 organization and is missing from AliasesDomains.
The parameter AliasesDomains is available in version 1.1.0.156 and above. Download the installation file
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)))
```
If you specify multiple LDAP paths in the configuration file, the filter GroupsFilter is applied to all paths.
To prevent the deletion of groups in Yandex 360 during sync, add the parameter AllowGroupsDeletion with the value False. In this case, users won't be deleted from the Yandex 360 organization when they're deleted from Active Directory. Default value: True.

Synchronize group attributes from Active Directory. To reassign attributes when creating or synchronizing groups in Yandex 360, use parameters that start with PropertyGroup.

Name of the parameter for the YandexADSCIM utility	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

Parameters that start with Property can be specified several times. In that case, the parameter value will be a list. The order of attributes is important. 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.

Synchronize external contacts if you use them in Yandex 360. To do this, add the EnableContacts parameter setting it to true.

Warning

For proper contact synchronization, the version of the YandexADSCIM utility should be 1.1.0.156 or higher. Download the installation file

By default, all objects that satisfy the LDAP query (&(objectClass=contact)) will be synchronized as contacts from Active Directory. To limit the list of contacts, you can use the ContactsFilter and apply the standard LDAP query syntax. For example, to export only the contacts from the groupname, use the filter:
```
ContactsFilter = (&(objectClass=contact)(memberOf=CN=groupname,CN=Users,DC=domainname,DC=com))
```
If you specify multiple LDAP paths in the configuration file, the filter ContactsFilter is applied to all paths.
To prevent the deletion of contacts from Yandex 360 during sync, add the parameter AllowContactsDeletion with the value False. In this case, contacts won't be deleted from the Yandex 360 organization when they're deleted from Active Directory. Default value: True.

Synchronize contact attributes from Active Directory. To reassign attributes when creating or synchronizing contacts in Yandex 360, use parameters that start with PropertyContact.

Name of the parameter for the YandexADSCIM utility	Attribute name	Default value from Active Directory	Example
PropertyContactFirstName	First name	givenName	Ivan
PropertyContactMiddleName	Middle name	middleName	Ivanovich
PropertyContactLastName	Last name	sn (SurName)	Ivanov
PropertyContactTitle	Position	title	Developer
PropertyContactDepartment	Department	department	Development department
PropertyContactCompany	Company	company	Wonderland LLC
PropertyContactMail	Primary email*	mail	I_ivanov@domain.ru
PropertyContactWorkPhone	Primary work phone	telephoneNumber	+7 495 123-45-67
PropertyContactOtherWorkPhone	Other work phones	otherTelephone	+7 495 765-43-21
PropertyContactMobile	Primary mobile phone	mobile	+7 012 345-67-89
PropertyContactOtherMobile	Other mobile phones	otherMobile	+7 987 654-32-10
PropertyContactIpPhone	Primary IP phone	ipPhone	7495 012-34-56
PropertyContactOtherIpPhone	Other IP phones	otherIpPhone	7495 987-65-43
PropertyContactAddress1	Address: Street	streetAddress	Yubileynaya
PropertyContactAddress2	Address: City	l	Podolsk
PropertyContactAddress3	Address: Region	st	Moscow Region
PropertyContactAddress4	Address: Zip code	postalCode	142121

Parameters that start with PropertyContact can be specified several times. In that case, the parameter value will be a list. The order of attributes is important.

You can also disable each of these parameters by specifying the value - (minus) for it. For example, to disable the synchronization of the "Position" attribute, you need to specify PropertyContactTitle = -.

If you changed the value of the DryRun parameter to False in Point 2.4, revert it back 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 3 237, 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 N of the configuration file.
AD Received contacts count: N	N contacts uploaded from Active Directory.
SCIM Add SharedContact:	Adding a contact to the Yandex catalog.

Stop the service and run it again to apply the changes from the configuration file. How to do this

Changing settings

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

Viewing logs

All logs are saved in the folder %ProgramData%\Yandex\YandexADSCIM. By default, the service records only the key events: service launch, configuration loads, data receipt events, and final results. There's no logging of outgoing network requests.

To enable detailed logging, use the parameter VerboseLog. Acceptable values:

False (by default): Recording only key events. Use for regular work to avoid excessive logging and reduce the size of logs.
True: Includes detailed logging of all stages and internal processes, including parameters of network requests to the SCIM API: request type, HTTP headers, and other data. Use it for debugging, troubleshooting, or auditing the YandexADSCIM utility.

The values of the parameter VerboseLog don't affect data processing, but only determine the level of detail in the logs.

To limit the number of archived logs with the extension .log.gz, use the parameter MaxLogFileCount. When the limit is exceeded, the oldest files will be deleted during rotation.

Parameter values:

Bby default: 14.
Minimum: 2 (any values below are ignored).

Updating ADSCIM

The application updates automatically: by default, the configuration file has the value AutoUpdate = True, or this parameter isn't listed because it's True by default.

If you want to update the application manually, specify AutoUpdate = False. To update the application, you'll need to download the latest version of YandexADSCIM (download here) and run the installation file.

Stopping and restarting ADSCIM

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 (cmd.exe) or clicking Stop in the task manager.

To restart the service, enter sc start yandexadscim in the command line. You can also restart ADSCIM in the task manager in the Services tab.

Deleting ADSCIM

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

Possible situations when working with ADSCIM

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. To ensure that accounts remain in the Yandex catalog when they're deleted from Active Directory, set the value for the AllowUsersDeletion parameter to `False` in the configuration file.
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.

Was the article helpful?

Configure Multifactor

Changing the identity provider (IdP)