REST Connection LDAP

Configuration located in the com.arcadsoftware.server.restful.connection.ldap.cfg file or in the section [ REST Connection LDAP ] section of the osgi.cm.ini file.

In this section, manage the connection bridge between the application's web-services and an LDAP server, including the LDAP connection parameters and other parameters allowing user importation into the application.

server

Parameter	Type	Default value
server	String

Defines the LDAP server address and port number (if different from default port number 389 or 636).

The value of this parameter is equal to "hostname" or "hostname:port" where hostname is the actual host name or IP address of the LDAP server and port is the TCP-IP port number used to serve the LDAP protocol interface.

servers

Parameter	Type	Default value
servers	String

Like the server parameter, this parameter defines the LDAP server access and port number, but this parameter accept multiple servers declaration, each one separated by a space character, allowing to support a cluster of LDAP server used as a failover server set.

host

Parameter	Type	Default value
host	String

This parameter is the legacy parameter used to define the LDAP server access and is replaced by the server and servers parameters. It sets the LDAP server host DNS or IP address.

Note

The parameters server, servers and host may be combined to define a set of failover servers. In that case, the first server in the list will be the one specified by the parameter host, followed by the one in server and then the server list of servers. However, you should avoid repeating the same "hostname:port" couple in different parameters' position. In other words, if you want to manage a cluster of LDAP servers use servers. If you have a unique server connection, use either server or host, but not both.

port

Parameter	Type	Default value
port	Integer	389 or 636

Sets the default TCP port number associated with the given list of LDAP servers. By default, this port is equal to 389 for LDAP connection, or to 636 if the TLS connection parameters are defined, assuming an LDAPS connection. 

reorderfailoverlist

Parameter	Type	Default value
reorderfailoverlist	Boolean	false

Specifies whether the list of servers used by this failover server set should be re-ordered when a failure is encountered while attempting to establish a connection. By default, the original order will be preserved. If enabled (set to true), then a failed attempt to establish a connection to the server at the beginning of the list will cause that server to be moved to the end of the list so that it will be the last server/set tried on the next attempt. By default, this option is disabled (set to false).

connection.pool.initial.size

Parameter	Type	Default value
connection.pool.initial.size	Integer	1

Defines the number of connections to establish initially when the LDAP connection pool is created. It must be greater or equal to one.

connection.pool.max.size

Parameter	Type	Default value
connection.pool.max.size	Integer	equals to connection.pool.initial.size

Define the maximum number of connections that should be maintained in the pool. It must be greater than or equal to the initial number of connections.

Whenever a connection is needed, the LDAP Connection pool first checks if there is a connection that has already been established but is not currently in use. If so, then that connection is used.

If there are not any unused connections that are already established, then the pool determines if it has yet created the maximum number of connections. If not, then it immediately creates a new connection and uses it.

If the pool has already created the maximum number of connections, then the pool waits for a period of time (as indicated by the timeout parameter) for an in-use connection to be released back to the pool. If no connection is available after the specified waiting time (or there may not be any waiting time), then the pool automatically creates a new connection to use it.

connection.pool.available.goal

Parameter	Type	Default value
connection.pool.available.goal	Integer	equals to connection.pool.initial.size

Specifies the goal for the minimum number of available connections that the pool should try to maintain for immediate use. If this goal is greater than zero, then the health checking process attempts to create enough new connections to achieve this goal. A value less than or equal to zero indicates that the pool should not try to maintain a minimum number of available connections.

connection.pool.max.age

Parameter	Type	Default value
connection.pool.max.age	Integer	120000

Specifies the maximum length of time in milliseconds that a connection in the pool may be established before it should be closed and replaced with another connection. A value of zero indicates that no maximum age should be enforced.

connection.failover.max.age

Parameter	Type	Default value
connection.failover.max.age	Integer	60000

Specifies the maximum connection age, in milliseconds, that should be used for connections that were created in order to replace defunct connections. Define a custom maximum connection age for these connections to allow them to be closed and re-established more quickly, for a potentially quicker fail-back to a normal state.

If you want to use the feature, then the maximum age for these connections should be long enough to allow the problematic server to become available again under normal circumstances (e.g., it should be long enough to allow for at least a shutdown and restart of the server, and also for potentially performing routine maintenance while the server is offline, or for a chance for an administrator to restore the server that went down).

timeout

Parameter	Type	Default value
timeout	Integer	5000

Specifies the maximum length of time, in milliseconds, to wait for a connection to become available when trying to obtain a connection from the pool. Set the parameter to 0 to indicate that the connection pool should not block at all if no connections are available and that it should create a new connection as soon as it is required.

busy.retry

Parameter	Type	Default value
busy.retry	Integer	1

Sets the number of retries during binding operations, when the server returns a "Busy" error. The maximal number of retries allowed is 12 and the client has to wait 2 seconds between each retry.

ssl.type

Parameter	Type	Default value
ssl.type	String

When set, this parameter enables the secured connection with the LDAP server (using TLS). Accepted values depend on the JVM implementation and on the requirement of the LDAP server, they can be:TLS, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3.

Example

To configure the TLS support, only the following parameters are generally required:

ssl.type = TLS
ssl.truststore.path = ... with the local path to the JKS truststore containing the server certificate if it is not a CA generated certificate.
ssl.truststore.pwd = ... with the password required to open the provided truststore.

ssl.prefered.protocol

Parameter	Type	Default value
ssl.prefered.protocol	String	TLSv1.3

Defines the preferred TLS protocol to be used in TLS negociation with the server if the ssl.type parameter is set to "TLS".

ssl.protocols.enabled

Parameter	Type	Default value
ssl.protocols.enabled	String	TLSv1.2 TLSv1.3

Define the list of TLS protocols open to negotiation with the server, if the ssl.type parameter is set to "TLS". Each value is separated by a white space character.

ssl.protocols.disabled

Parameter	Type	Default value
ssl.protocols.disabled	String

Defines the list of TLS protocol to remove from the negotiation with the server, if the ssl.type parameter is set to "TLS". Each value is separated by a white space character. This parameter is not useful if the ssl.protocols.enabled parameter is defined, as only an enabled protocol will be accepted anyway.

ssl.provider

Parameter	Type	Default value
ssl.provider	String

If set, define the TLS implementation provider name to be used for this connection. Acceptable values depend on the JVM implementation currently used. If this parameter is not set, the first provider declared in the JVM is used. Acceptable values may be:  BC, SunJSSE or IBMJSSE2.

ssl.ciphersuites.enabled

Parameter	Type	Default value
ssl.ciphersuites.enabled	String

Defines the list of cipher algorithm suites explicitly authorized during the TLS negotiation with the server. The values in this list must be separated by a white space character and are case-insensitive. The complete list of the accepted cipher suites depends on the JVM implementation. You may have to refer to the security documentation of the used JVM to find the exact list, which also depends on the provider used(e.g. the currently used list of cipher suites used by the SunLSSE provider).

ssl.ciphersuites.disabled

Parameter	Type	Default value
ssl.ciphersuites.disabled	String

Defines the list of cipher algorithm suites to disable during the TLS negotiation with the server. Each value is separated by a white space character. This parameter is not useful if the ssl.ciphersuites.enabled parameter is defined, as only the enabled cipher suites will be accepted anyway.

ssl.random

Parameter	Type	Default value
ssl.random	String

Sets the random algorithm used in the TLS handshake. Acceptable values depend on the JVM implementation and the current values areSHA1PRNG, NativePRNG and DRBG. By default, the default value of the JVM implementation is used.

ssl.start

Parameter	Type	Default value
ssl.start	Boolean

If set to true, this parameter enables the Start TLS protocol, which, if the server allows it, uses the same TCP port number for a clear and secure connection.

ssl.truststore.path

Parameter	Type	Default value
ssl.truststore.path	String

Sets the local path to the trusted certificate store containing the LDAP Server public certificate. If this parameter is not set, the JVM default truststore is used.

ssl.truststore.pwd

Parameter	Type	Default value
ssl.truststore.pwd	Encoded string

Sets the password required to open the ssl.truststore.path. This value can be encrypted.

ssl.truststore.type

Parameter	Type	Default value
ssl.truststore.type	String	JKS

Sets the type of the truststore. Accepted values depend on the JVM capabilities. Most JVM implementations support the native JKS type and the PKCS12 keystore types.

ssl.truststore.algorithm

Parameter	Type	Default value
ssl.truststore.algorithm	String

Sets the algorithm used to manage the X.509 certificates from the truststore. Accepted values depend on the JVM implementation. Current accepted value are SunX509, IbmX509 or PKIX. By default, the JVM default value is used.

ssl.keystore.path

Parameter	Type	Default value
ssl.keystore.path	String

Sets the local path to the private keystore containing the LDAP Client private key. By default, the JVM default keystore is used.

ssl.keystore.pwd

Parameter	Type	Default value
ssl.keystore.pwd	Encoded string

Sets the password required to open the keystore file. This value can be encrypted.

ssl.keystore.type

Parameter	Type	Default value
ssl.keystore.type	String	JKS

Sets the type of the keystore. Accepted values depend on the JVM capabilities. Most of the JVM implementation support the native JKS type and the PKCS12 keystore types.

ssl.keystore.algorithm

Parameter	Type	Default value
ssl.keystore.algorithm	String

Sets the algorithm used to manage the X.509 certificates from the keystore. Accepted values depend on the JVM implementation. Current accepted values are SunX509, IbmX509or PKIX. By default, the JVM default value is used, e.g. SunX509 with the ORACLE JVM or ibmX509 with the IBM one.

ssl.keystore.keypwd

Parameter	Type	Default value
ssl.keystore.keypwd	String	same value as ssl.keystore.pwd

Sets the password required to access to the keys stored into the keystore. By default the same password used to open the keystore is used here, but if this keystore is also used to store other key materials, a different password is recommended.

bind.type

Parameter	Type	Default value
bind.type	String	simple

This parameter define the method used to bind the user into the LDAP server. The accepted values are:

• simple (the default method): this method performs an LDAPv3 simple bind operation, which authenticates using a bind DN and password.
• plain: this method performs an SASL PLAIN bind request using the authentication ID and password. Even if compatible with SASL, this method will not use any external authorization token to bind to the LDAP server.
• scram-sha-1: this method performs an SASL bind request using the salted challenge-response authentication mechanism (SCRAM) with SHA-1 digest algorithm as described in RFC5802.
• scram-sha-256: this method performs an SCRAM  SASL bind request with SHA-256 algorithm as described in RFC 7677.
• scram-sha-512: this method performs an SCRAM  SASL bind request with SHA-512 algorithm and an HmacSHA512 MAC algorithm.
• cram-md5: this method performs an SASL CRAM-MD5 bind request allowing to authenticate over an insecure channel without exposing the credentials (although it requires that the server has access to the clear-text password). That is, the dn.login.pattern parameter should be set either to "dn:%s" with the distinguished name of the target user, or "u:%s" to use the username to authenticate. If the "u:" form is used, then the mechanism used to resolve the provided username to an entry may vary from server to server.
• digest-md5: this method performs an SASL DIGEST-MD5 bind request, as described in RFC 2831. This mechanism can be used to authenticate over an insecure channel without exposing the credentials (although it requires that the server has access to the clear-text password).  It is similar to CRAM-MD5, but provides better security by combining random data from both the client and the server. It also allows for greater security and functionality, including the ability to specify an alternate authorization identity and the ability to use data integrity or confidentiality protection. Note that the current implementation does not exploit the alternate authorization identity, and can only target the server default realm.
• gssapi: this method performs a SASL GSSAPI bind request as described in RFC 4752. It makes it possible to authenticate to a directory server using Kerberos V. This implementation uses the Java Authentication and Authorization Service (JAAS) to perform all Kerberos processing. This framework requires a configuration file to indicate the underlying mechanism to be used, this configuration file may change according to the used JVM.

Note that each of these methods require a specific server configuration and specific changes in the following parameters, especially the dn.login.pattern parameter.

realm

Parameter	Type	Default value
realm	String

Specifies the realm into which the user should authenticate. If this is not provided, an attempt is made to determine the appropriate value from the system configuration.

kerberos.kdc

Parameter	Type	Default value
kerberos.kdc	String

Specifies the IP address or resolvable name for the Kerberos key distribution center for the gssapi bind type. If this is not provided, an attempt is made to determine the appropriate value from the system configuration.

dn.base

Parameter	Type	Default value
dn.base	String

Sets the LDAP base distinguished name to search users from. The value must be a valid LDAP distinguished name representing the LDAP node in which the user is allowed to connect to this application.

This parameter is required only to perform search operations in the LDAP, like user import and login verification. These operations are disabled if this parameter is not set.

search.user.dn

Parameter	Type	Default value
search.user.dn	String

Sets the distinguished name of a permanent LDAP connection used to bind other users and manage the import operations. This LDAP user must be permanently accessible to the application server, if not no LDAP user connection will be possible.

This connection allows to search the login of any user trying to connect to the application into the LDAP tree before trying to authenticate them. To do so, the attribute.login parameter must be defined, and the dn.login.pattern parameter must not be used.

This mode of authentication of the application users, and the search.user.* parameter are optional, it may lower performance compared to a direct binding of the LDAP user and may require to permanently store the corresponding LDAP user password into the configuration files.

search.user.password

Parameter	Type	Default value
search.user.password	String

Sets the password used by the corresponding search.user.dn parameter.

search.user.sso

Parameter	Type	Default value
search.user.sso	String

Makes it possible to exploit an existing token or method to authenticate the permanent connection to the LDAP, defined by the search.user.dn and search.user.password parameters, allowing this connection, and only to this one, to perform a "single sign-on" operation.

The accepted values are the following:

• kerberos: the permanent connection is bound using a GSSAPI protocol. In that case, if an opened kerberos token is accessible through the operating system, the application uses it and the search.user.dn and search.user.password parameters are not required.
Note

This method relies on the JAAS implementation of Kerberos and may require a specific configuration of the JVM.

• external: use an SASL EXTERNAL bind request implementation as described in RFC 4422. The EXTERNAL mechanism is used to authenticate using information that is available outside of the LDAP layer (e.g., a certificate presented by the client during TLS or StartTLS negotiation). Depending on the External mechanism, a search.user.dn may still be required to perform the bind operation.

attribute.login

Parameter	Type	Default value
attribute.login	String

Sets the LDAP attribute associated with the user login used by the application. Accepted values depend on the LDAP server.

This parameter is only required to perform user importation from the LDAP server. But it may also be used as the replacement of the dn.login.pattern parameter.

dn.login.pattern

Parameter	Type	Default value
dn.login.pattern	String

This parameter transforms the user login into an acceptable LDAP identifier for the bind request. The value of this parameter should contain the "%s" placeholder which will be replaced by the actual user login. Its value may depend on the bind.type used and the LDAP server capabilities, but current usage are as the following:

• %s if the login is directly equal to the required binding identifier. This may be the required pattern to authenticate to an Active Directory server with the same identifier used to connect to the Windows account (the complete login including the domain name, e.g. "login@domain.com" or "NTDOMAIN\login").
• or %s@domain.com to simply use as a login the short version of the UserPrincipalName attribute in Active Directory.
• or even uid=%s,ou=UserOrganization,dc=domain,dc=com to use any part of the distinguished names as login.

If this parameter is not set, then if dn.login and dn.base are set, the binding identifier will be build as the result of the following pattern "dn.login= %s ,dn.base". For exemple, if dn.login=sAMAccountName and dn.base=dc=domain,dc=com, the default pattern will be "sAMAccountName=%s,dc=domain,dc=com". If dn.login is not set, then the default pattern will be "%s", i.e. the user login is directly used as the binding identifier.

A "%S" placeholder, with an upper-case S, may be used to automatically transform all "login" in upper-case before using them to bind to the LDAP server.

Reference

For more information about the syntax of LDAP distinguished names , refer to the LDAP DN documentation.

attribute.password

Parameter	Type	Default value
attribute.password	String	userPassword

Sets the LDAP attribute associated to store the user password. Accepted value depend on the LDAP implementation, it may be possible that the LDAP Server do not authorize the modification of the user password through an LDAP connection.

Note

This parameter is only used when the password.modify parameter is set to true.

password.modify

Parameter	Type	Default value
password.modify	Boolean

If set to true, allows the users are allowed to change their LDAP user account password through this application's services. To do so, thedn.passwordparameter must be set to a non-empty value.

Important!

In a production environment, it is not recommended to allow the end users to change their password through an external application. Moreover, only LDAP passwords stored in clear into the LDAP server can be modified through the LDAP connection.

userimportenabled

Parameter	Type	Default value
userimportenabled	Boolean	false

Define if the import of LDAP user in the database of the application is enabled. By default, this option is disabled (set to false). To use this function, it is also required to define the parameters dn.login, dn.base and ldapmap.

login.casesensitive

Parameter	Type	Default value
login.casesensitive	Boolean	true

If enabled (set to true), the LDAP user logins are case-sensitive. By default, this option is enabled (set to true).

ldapmap.x

Parameter	Type	Default value
ldapmap.	String

Every parameter starting with the prefix ldapmap defines the LDAP attributes that are associated with the corresponding attribute ("x" in this example) of the user entity in the database of the application. The values of these parameters accept multiple LDAP attribute names, separated by a white space. This list is a priority list: the first LDAP attribute existing in the corresponding LDAP node is used. For the user importation feature, a default constant value can be specified at the end of the list, using a double-quoted string. In this case, the imported user attribute in the database of the application is filled with the content of the quoted string, if no previous LDAP attribute is found in the corresponding LDAP node.

host = < your server DNS name>
port = 389
dn.attribute= sAMAccountName
dn.login.pattern = %s@<local domain name>
user.forcebinding = true
dn.base = <depends on your LDAP tree>