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.
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, andclient_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 totrue
, 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 [email protected] 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 [email protected] PropertyTitle Position Title Developer The parameters of attributes that start with Property can be reassigned when creating or syncing users in Yandex 360.
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
Learn morePropertyLoginName = objectSid/objectGUID/UPN, where UPN is the default value. If you use an attribute of the
username
and not the[email protected]
type, add theIgnoreUsernameDomain = true
key. The value of this attribute must be equal to the value of the NameID attribute from the SSO settings: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 thesurName
attribute exists, its value will be used. If this attribute is missing, thesn
attribute value will be used. If it's also missing, thelastName
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 theproxyAdresses
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 [email protected] 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 [email protected] The parameters of attributes that start with Propertycan be reassigned when creating or syncing groups in Yandex 360.
Learn moreThese 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 thename
attribute exists, its value will be used. If this attribute is missing, the value of thecn
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 logsNotification Result CORE Update user: [email protected] (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: [email protected] (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 thensc 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:
|
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:
|
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.