PROVISIO DevBlog

LDAP User Mapping in SiteRemote

Note: The following applies to the current release version 5.1.0.2188 and above. For compatibility reasons with OpenLDAP the syntax of the user.config section has been changed from the original release version 5.1.0.2186. The old syntax is no longer supported.

With SiteRemote Server 5.1 we introduced LDAP user mapping for customers running their own SiteRemote server. Now you can use user credentials provided by the directory service of your company's domain (q.v. Active Directory) for authentication in SiteRemote.

LDAP users and normal SiteRemote team users can be used together. At least one SiteRemote team user is required for each team you want to map LDAP users to.

Before you can map LDAP users to SiteRemote you need to create at least one team. You can do that for example on the Teams tab of the SiteRemote Server Administration. Note that while creating the team you need to specify a user, this user must not be an LDAP user but a normal SiteRemote Team user. This is the user responsible for a team and it cannot be deleted when logged in with an LDAP user. You can only delete this user from another SiteRemote team user account within a team (Note: it is planned for future SiteRemote versions to make the primary administration user permanent, so this behaviour might change).

After the team creation you can proceed to prepare your SiteRemote server to use LDAP authentication. You now need to manually edit the configuration file of the server. You will find the SiteRemoteServer.config file under ..\PROVISIO\SiteRemote\Config. Open it with an editor like Notepad and scroll down to the bottom. There you need to change the default User.config section right before the closing configuration tag:

<User.config LdapServerPort="0" LdapSecureSocketLayer="false" />

to something like this:

<?xml version="1.0" encoding="utf-8"?>
<Configuration>
	...
	
	...
	<SiteCaster.config VideoAudioAnalyzerPath="VideoAudioAnalyzer.exe" />
	<User.config>
		<LdapImportFullFilePath>c:\ldapuserlist.csv</LdapImportFullFilePath>
		<LdapServerHost>ldapserver.yourdomain.biz</LdapServerHost>
		<LdapServerPort>389</LdapServerPort>
		<LdapSecureSocketLayer>false</LdapSecureSocketLayer>
		<LdapUserPatterns>yourcompany\{0}</LdapUserPatterns>
	</User.config>
</Configuration>

The User.config section is the parent element for all LDAP related child elements in the SiteRemote configuration.

The LdapImportFullFilePath element must include the full path to the .csv file that includes the domain users you want to map to SiteRemote. More on that file a little later.

LdapServerHost includes the full host name of your LDAP server you may also use an IP adress.

LdapServerPort specifies the port your LDAP server uses. The default LDAP port is 389 or 636 if using an SSL connection.

LdapSecureSocketLayer is a boolean value. It is true if the server uses SSL.

LdapUserPatterns defines the way SiteRemote queries the user with the LDAP server. There are three supported principal forms: LDAP DN, Kerberos and NTLM. Note that these forms cannot be mixed. {0} is a required part of the pattern and is replaced by SiteRemote to include the user name that is authenticated with the LDAP server. The same user data is also used to perform the LDAP request.
LDAP DN uses the LDAP distinguished name syntax. This is used for example in OpenLDAP installations like Novell eDirectory.

<LdapUserPatterns>cn={0},ou=users,ou=us,o=yourcompany</LdapUserPatterns>

Because that syntax is very specific in regards to the location that is queried within the LDAP structure, you can add more than one pattern. The patterns must be seperated by a semicolon.

<LdapUserPatterns>cn={0},ou=users,ou=california,ou=us,o=yourcompany;cn={0},ou=users,ou=de,o=yourcompany;cn={0},ou=users,ou=gb,o=yourcompany;</LdapUserPatterns>

Kerberos authentication is usually used in Windows Active Directory. This syntax does not require different patterns as it queries the complete LDAP tree.

<LdapUserPatterns>{0}@yourcompany.biz</LdapUserPatterns>

NTLM authentication is also commonly used in Windows Active Directory. This syntax does not require different patterns as it queries the complete LDAP tree.

<LdapUserPatterns>yourcompany\{0}</LdapUserPatterns>

Here is another full example that uses SSL and LDAP DN:

<?xml version="1.0" encoding="utf-8"?>
<Configuration>
	...
	
	...
	<SiteCaster.config VideoAudioAnalyzerPath="VideoAudioAnalyzer.exe" />
	<User.config>
		<LdapImportFullFilePath>c:\ldapuserlist.csv</LdapImportFullFilePath>
		<LdapServerHost>ldapserver.yourdomain.biz</LdapServerHost>
		<LdapServerPort>636</LdapServerPort>
		<LdapSecureSocketLayer>true</LdapSecureSocketLayer>
		<LdapUserPatterns>cn={0},ou=users,ou=california,ou=us,o=yourcompany;cn={0},ou=users,ou=de,o=yourcompany</LdapUserPatterns>
	</User.config>
</Configuration>

After making and saving the changes to the SiteRemoteServer.config file you need to restart the SiteRemote Server service in the Microsoft Management Console for Windows Services (services.msc).

Now its time to create and place the .csv file with your LDAP user list at the location you specified in the SiteRemote configuration file. Note that the file only needs to contain the LDAP users you actually want to use with SiteRemote and not all LDAP users in your domain. Each line of the .csv file represents one LDAP user. The syntax is as follows:

[<oldusername>],<username>,<team>,<role(s)>,[<group(s)>]

oldusername is optional and required if you want to rename a user and keep this user's assignments within a SiteRemote team. This can be useful due to a name change because of marriage for example. oldusername then specifies the existing name of the user and username would contain the new one. Providing a name in this field is optional, if you don't provide a name you still need to write the comma to separate this field from the next. Note that user names must be unique, each user name can only be used once.

username specifies the name of the user. This field is required. Note that user names must be unique, each user name can only be used once.

team specifies the SiteRemote team name you want to assign the user to. This field is required.

role(s) (optional since SiteRemote Server 5.2 or higher) specifies the role or roles that you want to assign to the user. The role names of the default roles are language specific and depend on the language that was assigned at the time the team was created. For example the default roles for English are Administrator, User and Guest, in German they are Administrator, Benutzer and Gast. Other roles can be created and individually named in a SiteRemote team under Administration -> User Roles. If you want to assign more than one role you need to use quotation marks and separate each role by a comma.

group(s) is optional and only available with SiteRemote Server 5.2 or higher. You can assign LDAP users to groups you have created. If you want to assign more than one group you need to use quotation marks and separate each group by a comma. Note that each user will be automatically assigned to the Everyone group of a SiteRemote team.

Generally quotation marks are recommended to be used for each field. Here is an example of how the file can look like:

,"LDAPuser1","team1","Administrator"
,"LDAPuser2","team1","Guest"

,"LDAPuser3","team2","Administrator"
,"LDAPuser4","team2","User,Team2Role1,Team2Role2"
"LDAPuser5","LDAPuser7","team2","Guest"

,"LDAPuser6","team3","Administrator","Admin Group"

Note that the empty lines between the teams are not required, yet they can be used to better visualize assignments for different teams.

Each time you edit and save the .csv file or overwrite the existing file with a new one, the changes are applied.

To remove a user, simply delete the line from the .csv file and save it. The following would remove LDAPuser4 from team2:

,"LDAPuser1","team1","Administrator"
,"LDAPuser2","team1","Guest"

,"LDAPuser3","team2","Administrator"
,"LDAPuser7","team2","Guest"

,"LDAPuser6","team3","Administrator","Admin Group"

To remove all LDAP users from a team, just remove them all from the file. Placing an empty file will remove all LDAP users from all teams. The next example will remove all LDAP users from team2:

,"LDAPuser1","team1","Administrator"
,"LDAPuser2","team1","Guest"

,"LDAPuser6","team3","Administrator","Admin Group"

In case you want to assign a group but no role, the line would look like this:

,"LDAPuser6","team3",,"Admin Group"

Status messages regarding the processing of the file can be found in the SiteRemote server log file. The file SiteRemote.log can be found under ..\PROVISIO\SiteRemote\Log.

For full functionality the LDAP user authentication requires SiteKiosk Android 2.2 or higher or SiteKiosk Windows 8.9 or higher. Older versions cannot be registered with the SiteRemote server using an LDAP user.

In case you are using the TerminalCommander tool please make sure you are using the version that comes with SiteRemote Server 5.1 or higher.

Please note that the AutoRegister tool does not support LDAP users due to technical limitations.