LDAP Server and Active Directory

If you use the default installation of webPDF, the users found in the conf/users.xml XML database are used for authentication. It is also possible to use the users from an LDAP or Active Directory (AD) service.

You can set an LDAP or AD service via the server's Admin Portal under "Server > User source".

tip

The following explanations (under "Manual configuration") can also help when entering the necessary data on the portal, as they explain the general functioning of LDAP or AD usage.

Manual configuration

The user database can be modified by changing the settings in conf/server.xml.

tip

If possible, use the Admin Portal of the server to change the user database.

To take the users from an LDAP server or Active Directory, you must add the entry <ldap> to the <user>. Below is an example of a complete configuration of LDAP settings.

note

Please note that some of the configuration settings have to be specified as "Distinguished Names". This is especially the case when LDAP or AD objects have to be referenced.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>  
<server xmlns="http://schema.webpdf.de/1.0/configuration/server">  
...  
  <user roleAdminGroup="webPDFAdmin" roleUserGroup="webPDFUser">  
    <ldap connectionName="cn=ldapuser,cn=Users,dc=example,dc=local"  
          connectionPassword="my_password"  
          connectionURL="ldap://server.example.com:389/"  
          roleBase="CN=Users,DC=example,DC=local"  
          roleField="cn"  
          roleSearch="(member={0})"  
          userBase="CN=Users,DC=example,DC=local"  
          userSearch="(sAMAccountName={0})"/>  
  </user>  
...  
</server>

After making this modification, you must configure the access to the LDAP server or the Active Directory. For this purpose, adjust the values in the example above to match your configuration. In the example, "example.com" is used as the domain. Change the values accordingly to those of your own domain.

Basically, you need to adjust the server name and domain in the connectionURL entry. In this example they are shown as "server" and "example.com".

Important

Note that ldap:// must be replaced with ldaps:// if you want to use an SSL connection to the LDAP server. As a rule, the port must also be changed from 389 to 636.

Under the entries connectionName and connectionPassword please enter a user and the associated password to be used for accessing the LDAP or AD server.

note

If no user is required for LDAP access, then these settings can be left empty.

userBase and userSearch define the basis on which the directory search is to take place and how the login name for the user is to be found. userBase provides the list of users (objects) in which userSearch is used to search for the login name of the user. The wildcard {0} is replaced by the login name of the user during evaluation of the query. In the previously listed example, CN=Users,DC=example,DC=local and (sAMAccountName={0}) are typical values for a search in an Active Directory used as LDAP. You may need to modify these values to match the structure of your directory service.

Example: (sAMAccountName=jdo) (with jdo as login name for user "John Doe")

Once the user is found, the "Distinguished Name" (DN) is taken from the user object (attribute distinguishedName) and used to find the matching group.

Example: distinguishedName: CN=John Doe,CN=Users,DC=example,DC=local

The roleBase and roleSearch settings are used to search for the group. While roleBase is the base for the search, roleSearch is used to find all groups that have the previously determined DN as an attribute. The placeholder {0} in roleSearch is replaced with the DN.

Example: (member=CN=John Doe,CN=Users,DC=example,DC=local)

In all found groups the attribute defined via roleField is read (in this example cn). If the value that was read, i.e. the name of the group, matches user and admin, then the corresponding permission role (webPDF group) is assigned:

• user - Access authorization as a normal user
• admin - Access authorization as administrator (access to the Admin Portal)

note

For more information about the groups, see User groups.

With the entries roleAdminGroup and roleUserGroup you define your own group names (LDAP and AD groups respectively) to be assigned to the webPDF groups user and admin. Change the group names to the names of your LDAP or AD groups:

Example: Use LDAP group webPDFAdmin (roleAdminGroup) for webPDF group admin and webPDFUser (roleUserGroup) for user.

<user roleAdminGroup="webPDFAdmin" roleUserGroup="webPDFUser">

Users who need administrator access should also be members of the group configured via roleUserGroup. Otherwise, they may be able to authenticate but still receive WEBSERVICE_AUTHORIZATION_NO_USER_ROLE (-86) because their authorization does not include the required user role.

Troubleshooting

Admin Portal login is not possible

If LDAP or AD settings prevent access to the Admin Portal, manually edit conf/server.xml and restore the local XML user source:

<user>
    <xml/>
</user>

This switches the server back to the local conf/users.xml user database. Restart the webPDF server after saving the file so the change takes effect.

caution

Before manually editing conf/server.xml, create a backup copy of the file. Manual editing should only be used as a recovery step when the Admin Portal is not accessible.

Login works, but the user still has no access to the portal or web services

If authentication succeeds but the user cannot use the portal or API, verify that the LDAP or AD user is assigned to the group configured by roleUserGroup.

If the user should also have administrator permissions, verify that the same user is a member of both configured groups:

<user roleAdminGroup="webPDFAdmin" roleUserGroup="webPDFUser">

An administrator must be mapped to both the admin role and the user role.

The LDAP connection cannot be established

Review the connection settings first:

• Confirm that connectionURL uses the correct host name, protocol, and port.
• Use ldap:// with port 389 for non-TLS connections.
• Use ldaps:// with port 636 for TLS-secured connections.
• If ldaps:// is used, verify that the LDAP server certificate chain is trusted by the server environment.

Also verify connectionName and connectionPassword. Leave them empty only if anonymous LDAP access is allowed by your directory service.

The user can be found, but no groups are mapped

If user authentication succeeds but no roles are assigned, review the group lookup settings:

• Verify that roleBase points to the correct container or organizational unit for groups.
• Verify that roleSearch="(member={0})" matches how your directory stores group membership.
• Verify that roleField returns the actual group name to compare with roleAdminGroup and roleUserGroup.
• If your directory uses nested groups, check whether the configured LDAP query can resolve those memberships.

The login name is not found

Review the user lookup settings:

• Verify that userBase points to the correct container or organizational unit for users.
• Verify that userSearch uses the correct login attribute for your directory, for example sAMAccountName in many Active Directory environments or uid in other LDAP directories.

If necessary, compare the configured search attributes with a known working user entry in your directory.

Check the server logs

If the configuration still does not work, inspect the server logs for LDAP bind errors, TLS or certificate problems, and failed user or group searches. These messages are usually the fastest way to distinguish between connection, search base, and role mapping issues.

Linux command line diagnostics

If webPDF runs on Linux, command line tools can help identify whether the problem is caused by DNS resolution, network connectivity, TLS, LDAP bind credentials, or LDAP search filters.

note

The examples below use common Linux tools. Package names may differ slightly between distributions.

Install the required tools

Install the tools that match your Linux distribution:

• Ubuntu or Debian: sudo apt install ldap-utils openssl dnsutils netcat-openbsd
• RHEL, Rocky Linux, AlmaLinux, or CentOS: sudo dnf install openldap-clients openssl bind-utils nmap-ncat
• SUSE Linux Enterprise Server or openSUSE: sudo zypper install openldap2-client openssl bind-utils netcat-openbsd

tcpdump can also be useful for low-level network diagnostics if packet capture is allowed in your environment.

Check DNS resolution

Verify that the LDAP host name resolves correctly from the webPDF server:

host server.example.com
dig server.example.com

If the host cannot be resolved, fix DNS or use a reachable host name or IP address in connectionURL.

Check network connectivity

Verify that the LDAP or LDAPS port is reachable:

nc -vz server.example.com 389
nc -vz server.example.com 636

If the connection fails, check routing, firewall rules, container network policies, and whether the LDAP server is listening on the expected port.

Check the TLS handshake for LDAPS

When ldaps:// is used, verify that the TLS handshake and certificate chain are valid:

openssl s_client -connect server.example.com:636 -showcerts

If the handshake fails or the certificate is not trusted, review the LDAP server certificate chain and the trust configuration of the server environment.

Check LDAP bind and user lookup

Use ldapsearch to verify that the configured bind account can connect and that the user search returns the expected entry:

ldapsearch -x -H ldap://server.example.com:389 \
  -D "cn=ldapuser,cn=Users,dc=example,dc=local" -W \
  -b "CN=Users,DC=example,DC=local" \
  "(sAMAccountName=jdo)"

This helps confirm that connectionURL, connectionName, connectionPassword, userBase, and userSearch are correct.

Check LDAP group lookup

Use ldapsearch again to confirm that the group search returns the groups used by roleAdminGroup and roleUserGroup:

ldapsearch -x -H ldap://server.example.com:389 \
  -D "cn=ldapuser,cn=Users,dc=example,dc=local" -W \
  -b "CN=Users,DC=example,DC=local" \
  "(member=CN=John Doe,CN=Users,DC=example,DC=local)"

This helps confirm that roleBase, roleSearch, and roleField match your directory structure.

Inspect active connections

If requests appear to hang or time out, inspect active TCP connections on the server:

ss -tan | grep ':389\|:636'

This can help determine whether connections are established, stuck during handshake, or immediately closed.

After all modifications have been made, the webPDF server must be restarted so that all the settings take effect and the users are read.