4.12. SSO related properties

In the following section we describe SSO configuration options.

4.13. LDAP

LDAP-related properties, described below, are defined in the /fileserver/etc/sso/ldap.cf configuration file. These are relevant for the ''ldapimport'' terminal command and the ldapimport.groovy script available here: https://github.com/infofabrik/reportserver-samples/blob/main/src/net/datenwerke/rs/samples/admin/ldap/ldapimport.groovy.

Note that you can (and should) test your LDAP configuration with the ''ldaptest'' commands described in the Administration Guide.
<provider>
   <host>directory.example.com</host>
   <port>389</port>
</provider>

Configures the host (or IP) and port where your LDAP server is installed. Note that if you use SSL (LDAPS) this port is different than the LDAP port. StartTLS uses the same LDAP port.

<security>
   <encryption>none</encryption>
   <principal>CN=ldaptest,CN=Users,DC=directory,DC=example,DC=com</principal>
   <credentials>password</credentials>
</security>

The ''encryption'' property defines the encryption protocol to use. Valid values are ''none'' (for no encryption), ''starttls'' (for StartTLS encryption (recommended)) and ''ssl'' (for SSL (LDAPS) encryption).

In order for encryption to work, you have to install the certificates needed for these to be trusted by ReportServer.

This means that you must add the LDAP server's certificate (or a certificate higher up the trust chain) to a truststore that is known to ReportServer during startup.

This can be achieved in two different ways:

  • Passing the truststore where the certificate is installed. If you use JKS keystores you can pass the keystore analogous to: -Djavax.net.ssl.trustStore=/path/to/security/truststore.jks -Djavax.net.ssl.trustStorePassword=myTrustStorePassword -Djavax.net.ssl.trustStoreType=JKS If you use PKCS12 you can pass the keystore analogous to: -Djavax.net.ssl.trustStore=/path/to/security/truststore.p12 -Djavax.net.ssl.trustStorePassword=myTrustStorePassword -Djavax.net.ssl.trustStoreType=PKCS12 Refer to the Java Documentation for details: https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html Be aware that if you use this method, you may need to add other certificates as well in order for your Email, SFTP, OneDrive, etc to continue working, as these certificates are contained in the cacerts truststore, see below. You may of course create a copy of cacerts and add your certificates to this copy instead of using the java cacerts truststore directly.
  • Or installing the certificate into your JVM trust store (usually located here java-home/lib/security/cacerts). Refer to the Java Documentation for details: https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html.

You can test your SSL configuration, i.e. if your certificate was installed correctly, with the ''ssltest'' terminal command. Check the Administration Guide for details.

The ''principal'' and ''credentials'' properties allow you to authenticate to your LDAP server.

<base>OU=EXAMPLE,DC=directory,DC=example,DC=com</base>
<filter>(|(objectClass=organizationalUnit)(objectClass=user)(objectClass=group))</filter>

The ''base'' property defines the address of the root object in the LDAP directory. All objects are stored below the base.

The ''filter'' allows you to retrieve a subset of all the nodes found below the base DN.

<externalDir>/usermanager/external</externalDir>
<writeProtection>true</writeProtection>
<includeNamespace>false</includeNamespace>
<logResultingTree>false</logResultingTree>
<flattenTree>false</flattenTree>

The ''externalDir'' property defines the directory in ReportServer where your users/groups and OUs will be imported into. These objects will be write-protected if the ''writeProtection'' is set to ''true''.

If ''includeNamespace'' is set to true, the full name of the bindings are used. Else, the relative names are used.

When the ''logResultingTree'' property is set to ''true'', a summary and some statistics of the changes done in your ReportServer are logged into your logs.

If you need to import all nodes into the root directory (i.e. into the ''externalDir'' directory described above) instead of using the original LDAP tree, you can set ''flattenTree'' to ''true''. Note that all OUs will be empty in this case. If you don't want to include the empty OUs, you have to remove them via the filter attribute.

<attributes>
   <objectClass>objectClass</objectClass>
   <guid>entryUUID</guid>
   <organizationalUnit>
      <objectClass>organizationalUnit</objectClass>
      <name>name</name>
   </organizationalUnit>
   <group>
      <objectClass>group</objectClass>
      <name>name</name>
      <member>member</member>
   </group>
   <user>
      <objectClass>inetOrgPerson</objectClass>
      <firstname>givenName</firstname>
      <lastname>sn</lastname>
      <username>sAMAccountName</username>
      <mail>mail</mail>
   </user>
</attributes>

The properties above define the attributes used in your AD nodes.

General object class attributes are defined by the ''attributes - objectClass'' attribute, while object GUIDs are defined by the ''guid'' attribute. Note that GUIDs must be unique.

The ''organizationalUnit - objectClass'' defines a OU with name specified by ''organizationalUnit - name''. The same applies to the ''group'' attributes.

The ''user'' attributes specify a given user. The node is determined as a user by the ''user - objectClass'' attribute, while the ''firstname'', ''lastname'', ''username'' and ''mail'' attributes allow ReportServer to fetch these attributes from a user node.

<attributes>
   <additional>
      <attribute>department</attribute>
      <attribute>office</attribute>
   </additional>
</attributes>

If you need additional attributes, i.e. attributes not included in the standard attribute list, you can fetch them from your LDAP by defining them in the ''additional'' list as shown above. The example would fetch the ''department'' and ''office'' attributes, which can be then used in a ''LdapNodePostProcessHook'' hooker as shown in this example: https://github.com/infofabrik/reportserver-samples/blob/main/src/net/datenwerke/rs/samples/admin/ldap/ldapUserVariableProcessorHooker.groovy. The example uses the ''department'' LDAP attribute in order to set the appropriate value into a given user-variable ''myUserVar''.

<authentication>
	<allowLocalUsers>true</allowLocalUsers>
</authentication>

The ''allowLocalUsers'' setting allows you to control whether local, non-LDAP users are being allowed to authenticate or not alongside with the LDAP users. If this is set to ''false'', only LDAP users are allowed to authenticate.