Syncing users and groups with the LDAP directory using ADSCIM

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.

Connection and initial setup of ADSCIM

Step 1. Begin setup

1. Check that single sign-on (SSO) is enabled and works correctly. How to enable single sign-on (SSO)

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

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

1. Go to the Create an application page. Go there

2. Enter the name of the service and attach its icon.

3. In the Platforms block, select Web services. In the Redirect URI field, click Enter URL for debugging.

4. In the Data access block, enter Managing federations at the beginning of the line.

5. Enter your contact email. Click Create app at the bottom of the page.

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

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

1. Open the organization's account in Yandex 360 for Business. Open

2. Go to General settings → Single sign-on (SSO).

3. Click Set up.

4. In the SCIM synchronization block, paste the ID you received in Step 2.

5. Copy your Domain ID. You'll need it in the next step.

6. Save your changes.

Step 4. Install and configure the Windows service for synchronization

1. Download and install the YandexADSCIM utility. Download the installation file

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

   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:

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

   2. In the BearerToken parameter value, enter the OAuth token you received in Step 2.

   3. In the DomainID parameter value, enter the Domain ID you received in Step 3.

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

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

   6. To limit user upload, you can use UsersFilter and apply the standard LDAP query syntax.

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

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

      Warning

      For correct synchronization of aliases, use the YandexADSCIM utility of version 1.1.0.144 or higher. Download the installation file.

   8. 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)))
      

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

   10. 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))
       

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

       (*) You can't override non-primary email addresses (those with the smtp: prefix, proxyAddresses in Active Directory). But you can disable them by adding the ContactIgnoreProxyAddresses parameter set to true.

       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.

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

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

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

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