ReportServer - ReportServer Configuration Guide 4.7

4.16. SSO related settings

In the following section we describe SSO configuration options.

4.16.1. 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 for checking your LDAP configuration before letting the real import to happen. The ldapschema, ldapguid, ldapfilter and ldapinfo terminal commands may also be useful for exploring your LDAP server and also the extended the ldaptest users, ldaptest groups and ldaptest organizationalUnits with a -s (schema) flag. While the -s flag allows you to explore the installed object class types of your users', OUs' and groups' object classes, the ldapschema allows you to explore any object class. For example, you may execute ldaptest users -s for printing the schema of the users' object class. You should get a list of optional attributes, required attributes, and the parent object class. Suppose the parent's object class is ''organizationalPerson''. You may then explore this object class with ldapschema objectClassInfo organizationalPerson. You may continue exploring the LDAP schemas until the top-most object class: top.

<disabled>true</disabled>
<provider>
   <host>directory.example.com</host>
   <port>389</port>
</provider>

The disabled property allows you to completely disable your LDAP if you don't need it. Note that LDAP is disabled by default.

The provider property 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/en/java/javase/11/security/java-secure-socket-extension-jsse-reference-guide.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/en/java/javase/11/security/java-secure-socket-extension-jsse-reference-guide.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>
<![CDATA[
(|(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.

You can analyze your installed LDAP filter with the ldapfilter terminal command. You can test your installed LDAP filter with the ldaptest filter terminal command. Check the Administration Guide for details on both commands.

Note that you have to escape some characters in your filter (e.g. parentheses, space characters, *, etc) if you need these in your filter attributes. Example filter:

<filter>
<![CDATA[
(o=Parens\20R\20Us\20\28for\20all\20your\20parenthetical\20needs\29)
]]></filter>

In the example you see \ 28 instead of |, \ 29 instead of ), and \ 20 instead of space . More information can be found here: https://www.rfc-editor.org/rfc/rfc4515#section-4.

If you do not use CDATA, you also need to escape & with &. We recommend to use CDATA for better readability.

<externalDir>/usermanager/external</externalDir>
<writeProtection>true</writeProtection>
<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.

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. In order to browse and analyze the LDAP schema of your LDAP installation, you can use the following commands: ldapschema, ldapinfo, and ldapguid. Check your Administration Guide for details.

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. ReportServer makes a best-effort guess of the appropriate GUID for your installation with the ldapguid terminal command. Check your Administration Guide for details.

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.

Note that the old allowLocalUsers setting was removed as of ReportServer 4.5.0. Instead, you should use colon-separated PAMs in your reportserver.properties as explained in the Script Guide (Custom Authenticators PAMs) if you need to allow/disallow local users to log-in. E.g. the following setting allows only LDAP users: rs.authenticator.pams = net.datenwerke.rs.ldap.service.ldap.pam.LdapPAM while the following setting allows both LDAP and local users: rs.authenticator.pams = net.datenwerke.rs.ldap.service.ldap.pam.LdapPAM:net.datenwerke.rs.authenticator.service.pam.UserPasswordPAM

4.17. TeamSpace related settings

The /etc/security/teamspace.cf configuration file allows you to configure some TeamSpace settings.

You can completely disable or enable the TeamSpace file upload by the following property:

<fileupload disabled = "false">

The default is false, so the TeamSpace file upload is enabled by default.

Futher, the maximum upload file size can be configured using the following property:

<maxSizeBytes>52428800</maxSizeBytes>

Default is 50 MB.

Only the file endings explicitely allowed in the whitelist as shown below are allowed.

<whitelist>
   <endings>
      <ending>pdf</ending>
      <ending>jpg</ending>
      <ending>jpeg</ending>
      <ending>png</ending>
      <ending>xlsx</ending>
      <ending>xls</ending>
      <ending>docx</ending>
      <ending>doc</ending>
      <ending>txt</ending>
   </endings>
</whitelist>

Note that regular expressions (refer to https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/regex/Pattern.html) are allowed in the ending whitelist. E.g., the following allows all possible file endings:

<whitelist>
   <endings>
      <ending>.*</ending>
   </endings>
</whitelist>