LDAP configuration parameters
The OpenKM LDAP integration is based on several LDAP searches to retrieve data.
LDAP queries are composed of three elements:
- Attribute or object to retrieve.
- Node base to scope the request.
- Filtering options.
Sample query
Section titled “Sample query”The query to retrieve the mail attribute from an object of type person with sAMAccountName attribute value {0} - this parameter indicates the userId - from node cn=users,dc=company,dc=local and its descendants.
principal.ldap.mail.attribute
mail
principal.ldap.mail.search.base
cn=users,dc=company,dc=local
principal.ldap.mail.search.filter
(&(objectclass=person)(sAMAccountName={0}))LDAP queries
Section titled “LDAP queries”- principal.ldap.user.* is used to retrieve the user list.
- principal.ldap.username.* is used to retrieve the user name.
- principal.ldap.mail.* are used to retrieve users’ email addresses.
- principal.ldap.role.* are used to retrieve the role list.
- principal.ldap.roles.by.user.* are used to retrieve a user’s roles.
- principal.ldap.users.by.role.* are used to retrieve users of a role.
For retrieving data, arguments are injected into option filters. For example, to get the user’s email, the application uses parameter {0} to set the argument value - userId - in the filtering options.
Queries that use parameters for filtering:
- principal.ldap.mail.search.filter=(sAMAccountName={0}). Where {0} is the attribute value retrieved from the principal.ldap.user.attribute.
- principal.ldap.roles.by.user.search.filter=(&(objectclass=user)(sAMAccountName={0})). Where {0} is the attribute value retrieved from the principal.ldap.user.attribute.
- principal.ldap.username.search.filter=(sAMAccountName={0}). Where {0} is the attribute value retrieved from the principal.ldap.user.attribute.
- principal.ldap.users.by.role.search.filter=(&(objectClass=group)(cn={0})). Where {0} is the attribute value retrieved from the principal.ldap.role.attribute.
Parameters
Section titled “Parameters”| Field / Property | Type | Description |
|---|---|---|
| principal.adapter | String | The parameter is deprecated as of version 8.1.12 Class used to connect with LDAP. |
| system.login.lowercase | String | By default, it is empty. When connecting to AD (Microsoft Active Directory), this must be set to “true”, which forces all users to log in with a lowercase user ID. The reason is OpenKM is case-sensitive, and Microsoft Active Directory is not. |
| principal.ldap.server | String | LDAP server. |
| principal.ldap.security.principal | String | LDAP user distinguished name (DN). |
| principal.ldap.security.credentials | String | LDAP user password. |
| principal.ldap.referral | String | This property specifies how OpenKM handles the referrals sent by AD in the search results. In most cases, this value is empty. Note for Active Directory (AD) users: AD servers cannot handle referrals automatically, which causes a PartialResultException to be thrown whenever a referral is encountered in a search. To avoid this, set the ignorePartialResultException property to true. There is currently no way to manually handle these referrals as a ReferralException; i.e., either you get the exception (and your results are lost), or all referrals are ignored (if the server is unable to handle them properly). There is no simple way to get notified that a PartialResultException has been ignored (other than in the log).More information at Spring LdapTemplate. Values might be: “ignore” If principal.ldap.referral=ignore, the following exception will be thrown when a referral is encountered: bash<br>javax.naming.PartialResultException: Unprocessed Continuation Reference(s); remaining name 'dc=company,dc=com'<br>“follow” If principal.ldap.referral=follow, OpenKM will automatically follow the referral. To be successful, make sure OpenKM can access the referred server. The errors about ReferralExceptions should not be shown. “throw” If principal.ldap.referral=throw, the following exception will be thrown: bash<br>com.sun.jndi.ldap.LdapReferralException: Continuation Reference; remaining name 'dc=company,dc=com'<br>More information at Referrals in the JNDI. |
| principal.ldap.users.from.roles | Boolean | When “true”, it tries to retrieve all users from the roles list. |
| principal.ldap.user.attribute | String | User attribute. |
| principal.ldap.user.search.base | List | List of node bases. |
| principal.ldap.user.search.filter | String | Filter options. |
| principal.ldap.username.attribute | String | Username attribute |
| principal.ldap.username.search.base | String | Node base. |
| principal.ldap.username.search.filter | String | Filter options. |
| principal.ldap.mail.attribute | String | Mail attribute. |
| principal.ldap.mail.search.base | String | Node base. |
| principal.ldap.mail.search.filter | String | Filter options. |
| principal.ldap.role.attribute | String | Role attribute. |
| principal.ldap.role.search.base | List | List of node bases. |
| principal.ldap.role.search.filter | String | Filter options. |
| principal.ldap.roles.by.user.attribute | String | User attribute. |
| principal.ldap.roles.by.user.search.base | String | Node base. |
| principal.ldap.roles.by.user.search.filter | String | Filter options. |
| principal.ldap.users.by.role.attribute | String | Role attribute. |
| principal.ldap.users.by.role.search.base | String | Node base. |
| principal.ldap.users.by.role.search.filter | String | Filter options. |
Sample configuration
Section titled “Sample configuration”| Field / Property | Type | Description |
|---|---|---|
| principal.adapter | String | The parameter is deprecated as of version 8.1.12 com.openkm.plugin.principal.LdapPrincipalAdapter |
| system.login.lowercase | String | true |
| principal.ldap.server | String | ldap://192.168.1.20:389 |
| principal.ldap.security.principal | String | CN=Administrator,OU=OpenKM,DC=company,DC=com |
| principal.ldap.security.credentials | String | password |
| principal.ldap.referral | String | |
| principal.ldap.users.from.roles | Boolean | false |
| principal.ldap.user.attribute | String | sAMAccountName |
| principal.ldap.user.search.base | List | DC=company,DC=com |
| principal.ldap.user.search.filter | String | objectclass=person |
| principal.ldap.username.attribute | String | cn |
| principal.ldap.username.search.base | String | DC=company,DC=com |
| principal.ldap.username.search.filter | String | (sAMAccountName={0}) |
| principal.ldap.mail.attribute | String | |
| principal.ldap.mail.search.base | String | DC=company,DC=com |
| principal.ldap.mail.search.filter | String | (sAMAccountName={0}) |
| principal.ldap.role.attribute | String | cn |
| principal.ldap.role.search.base | List | DC=company,DC=com |
| principal.ldap.role.search.filter | String | objectclass=group |
| principal.ldap.roles.by.user.attribute | String | memberOf |
| principal.ldap.roles.by.user.search.base | String | DC=company,DC=com |
| principal.ldap.roles.by.user.search.filter | String | (&(objectclass=person)(sAMAccountName={0})) |
| principal.ldap.users.by.role.attribute | String | member |
| principal.ldap.users.by.role.search.base | String | DC=company,DC=com |
| principal.ldap.users.by.role.search.filter | String | (&(objectClass=group)(cn={0})) |