Configuration

LdapAuth is configured by a simple key / values file located in the WEB-INFO directory of the distributed WAR package:

• WEB-INFO/ldapauth.properties (click to view)

Edit the configuration file to set the policy for client access and the details of the authenticating backend.

Additional configurations are available for the sample LDAP directory server, for handling cross-domain (CORS) requests and for controlling logging.

Remember to restart your LdapAuth service instance for the modified configuration to take effect.

Access control

The ldapAuth.access.* properties specify the access control policy of LdapAuth. They allow the creation of access rules based on HTTPS security, X.509 client certificate, client IP address, and / or API keys.

ldapAuth.access.https.require

If true requires clients to connect using HTTP secure (HTTPS). Plain HTTP connections will be denied with a “Requests must be sent over HTTPS” (-31100) error.

It’s recommended that HTTPS use is enforced at all times to prevent eavesdropping on user credentials and details:

ldapAuth.access.https.require = true

ldapAuth.access.https.requireClientCert

If true requires clients to authenticate with a valid X.509 certificate issued by a trusted certificate authority (CA). This forces the mutual authentication of both server and client in the HTTPS connection. HTTPS requests without a valid client certificate will be denied with a “Trusted client X.509 certificate required” (-31110) error.

ldapAuth.access.https.requireClientCert = true

ldapAuth.access.https.clientCertPrincipal

If specified, requires the X.509 client certificate subject to match the specified distinguished name (DN). Client certificates with a non-matching subject (principal) will be denied with a “Client X.509 certificate principal denied” (-31112) error.

ldapAuth.access.https.clientCertPrincipal = CN=LdapAuthClient, OU=apps, DC=wonderland, DC=net

ldapAuth.access.hosts.allow

Space-separated list of client IPs and / or hostnames that are allowed access to LdapAuth. If set to * (asterisk) any IP address is allowed. Requests from non-matching client IPs / hostnames will be denied with a “Client IP address denied access” (-31105) error.

Example: Allow access from any IP address:

ldapAuth.access.hosts.allow = *

Example: Allow only the two listed client IP addresses:

ldapAuth.access.hosts.allow = 192.168.0.1 192.168.0.2 192.168.0.3

ldapAuth.access.apiKeys.require

If true web clients must present an API key with each JSON-RPC 2.0 request. The API key is passed through the optional string parameter named apiKey. Requests without an API key will be denied with an “Missing API key” (-31121) error. Requests with an invalid API key will be denied with an “API key denied access” (-31123) error.

Example LdapAuth request with an API key:

{
  "method"  : "user.auth",
  "params"  : { "username" : "alice",
                "password" : "secret",
                "apiKey"   : "f70defbeb88141f88138bea52b6e1b9c" },
  "id"      : "0001",
  "jsonrpc" : "2.0"
}

If false API keys will not be required for LdapAuth access.

ldapAuth.access.apiKeys.require = true

ldapAuth.access.apiKeys.exemptedMethods

Space-separated list of names of exempted JSON-RPC 2.0 methods for which an API key is not required. All other methods will require an API key to be presented.

To allow public access to the ws.getName, ws.getVersion and ws.getTime LdapAuth requests:

ldapAuth.access.apiKeys.exemptedMethods = ws.getName ws.getVersion ws.getTime

ldapAuth.access.apiKeys.map.*

Map of API keys to the JSON-RPC 2.0 methods they are allowed access to. Asterisk (*) signifies any method is allowed for the given API key.

The API key strings should be random and of sufficient length to prevent their guessing. An UUID generator can be used for this purpose.

Example map defining two API keys and the corresponding allowed LdapAuth requests:

API key one:

• API key: f70defbeb88141f88138bea52b6e1b9c
• Allowed requests: user.auth, realm.get

API key two:

• API key: 08d1e641b1c14d888796e47c06430efb
• Allowed requests: any

ldapAuth.access.apiKeys.map.f70defbeb88141f88138bea52b6e1b9c = user.auth realm.get
ldapAuth.access.apiKeys.map.08d1e641b1c14d8887

Web API settings

The ldapAuth.api.* parameters enable / disable specific requests and options in the LdapAuth web API. The preferred HTTP response content type is also set here.

ldapAuth.api.allowUserAuthRequests

If true clients may make user.auth calls to request basic user authentication.

user.auth calls are allowed per default:

ldapAuth.api.allowUserAuthRequests = true

ldapAuth.api.allowUserAuthGetRequests

If true clients may make user.authGet calls to authenticate a user and retrieve selected user attributes as specified by ldapAuth.userAttributes.*.

user.authGet calls are allowed per default:

ldapAuth.api.allowUserAuthGetRequests = true

ldapAuth.api.allowUserGetRequests

If true clients may make user.get calls to retrieve selected user attributes as specified by ldapAuth.userAttributes.*. The underlying LDAP calls are performed over the search user connection and require a DN resolve method set to SEARCH.

Access to user.get calls must be protected by API keys or similar method to ensure that only authorised web clients can retrieve user attributes directly.

user.get calls are denied per default:

ldapAuth.api.allowUserGetRequests = false

ldapAuth.api.allowUserResolveDNRequests

If true clients may make user.resolveDN calls to find out the distinguished name (DN) for a username. This is done by querying the backend directory and requires a DN resolve method set to SEARCH or TEMPLATE.

user.resolveDN calls are allowed per default:

ldapAuth.api.allowUserResolveDNRequests = true

ldapAuth.api.enableDNProvision

If true clients are provided with the user’s distinguished name (DN) on a successfull user.authGet or user.get call.

ldapAuth.api.enableDNProvision = true

ldapAuth.api.allowJson2LdapCIDProvision

If true clients may request a Json2Ldap connection identifier (CID) bound as the authenticated user. Applies to user.authGet calls when the ldapAuth.authBackend is set to JSON2LDAP.

Web clients may use the Json2Ldap directory connection (CID) to obtain attributes from the user’s entry, make searches, or update information.

ldapAuth.api.allowJson2LdapCIDProvision = true

ldapAuth.api.exposeExceptions

This setting controls reporting of details in JSON-RPC 2.0 “LDAP/Json2Ldap back-end service exception” messages (code -1020).

If true LdapAuth will expose the cause of the back-end exception in the “data” field of the JSON-RPC 2.0 error. Use this setting for debugging or if the web clients are trusted.

If false LdapAuth will not provide any additional information about back-end exceptions. The exact cause can be found out in the LdapAuth log. Use this setting if the web clients are not trusted or they don’t need to know any details about encountered exceptions.

To allow your web clients to inspect the cause of back-end exceptions:

ldapAuth.api.exposeExceptions = true

ldapAuth.api.responseContentType

Sets the value of the HTTP “Content-Type” header for the JSON-RPC 2.0 responses. The character set option must be explicitly set to UTF-8.

Typically set to application/json; charset=utf-8 or to text/plain; charset=utf-8 to support browser CORS requests.

ldapAuth.api.responseContentType = application/json; charset=utf-8

ldapAuth.api.reportRequestProcTime

If true enables reporting of request processing time by appending a non-standard “xProcTime” attribute to the JSON-RPC 2.0 responses.

Intended for debugging and testing purposes. Disabled by default to prevent parse exceptions by clients which don’t allow unexpected JSON attributes in the JSON-RPC 2.0 response messages.

Authenticating realm and backend type

LdapAuth authenticates users against an LDAP directory. This is done either directly or through a Json2Ldap web proxy / gateway.

ldapAuth.authRealm

Arbitrary name to identify the authenticating realm, typically a domain name. The name is returned by the realm.get call and may be used by web clients to identify the user base for which a particular LdapAuth instance provides authentication and details retrieval.

ldapAuth.authRealm = wondlerland.net

ldapAuth.authBackend

This setting specifies how the LdapAuth connects to the back-end LDAP directory.

If set to LDAP LdapAuth will establish direct LDAP v3 connections to the back-end directory. The directory details must then be specified in the ldapAuth.ldapServer.* section.

ldapAuth.authBackend = LDAP

If set to JSON2LDAP LdapAuth will use a Json2Ldap web gateway / proxy to connect to the back-end directory. The Json2Ldap details must then be specified in the ldapAuth.json2ldap.* section.

ldapAuth.authBackend = JSON2LDAP

Json2Ldap gateway / proxy

The ldapAuth.json2ldap.* properties specify the connection details for the Json2Ldap web service. These are required if ldapAuth.authBackend is set to JSON2LDAP.

ldapAuth.json2ldap.url

The HTTP(S) URL of the Json2Ldap web service.

ldapAuth.json2ldap.url = http://localhost:8080/json2ldap/

ldapAuth.json2ldap.useDefaultLDAPServer

Specifies whether to use the default LDAP server for the Json2Ldap web service.

If false the LDAP server details must be specified explicitly in the ldapAuth.ldapServer.* configuration.

ldapAuth.json2ldap.trustSelfSignedCerts

Specifies whether to accept self-signed X.509 certificates presented by the Json2Ldap web service (for HTTPS connections).

ldapAuth.json2ldap.connectTimeout

Specifies an HTTP connect timeout for Json2Ldap requests, in milliseconds. Zero implies the option is disabled (the default).

To set a connect timeout of one second (1000ms):

ldapAuth.json2ldap.connectTimeout = 1000

ldapAuth.json2ldap.readTimeout

Specifies an HTTP read timeout for Json2Ldap requests, in milliseconds. Zero implies the option is disabled (the default).

To set a read timeout of one second (1000ms):

ldapAuth.json2ldap.readTimeout = 1000

LDAP server

The ldapAuth.ldapServer.* properties specify the connection details for the LDAP server. These are required if ldapAuth.authBackend is set to LDAP or if the back-end is set to JSON2LDAP and a non-default directory is used.

ldapAuth.ldapServer.url

The LDAP URL of the directory server. The schema must be ldap or ldaps, it must specify a valid host name or IP address as well as the port number if a non-default is used.

If the directory is replicated across several LDAP servers for the purpose of failover or load-balancing, the value is a space-separated list of the corresponding LDAP URLs. Server selection is handled according to ldapAuth.ldapServer.selectionAlgorithm.

The LDAP URL of a directory server that listens on the default 389 port:

ldapAuth.ldapServer.url = ldap://ldap.mydomain.com

To specify a non-standard port:

ldapAuth.ldapServer.url = ldap://ldap.mydomain.com:10389

To specify a primary and failover LDAP server:

ldapAuth.ldapServer.url = ldap://primary-ldap.mydomain.com ldap://secondary-ldap.mydomain.com

ldapAuth.ldapServer.selectionAlgorithm

The preferred server selection algorithm in case ldapAuth.ldapServer.url is an LDAP server set.

If set to FAILOVER LdapAuth will attempt to establish connections to the LDAP servers in the order they are provided. If the first server is unavailable, then it will attempt to connect to the second, then to the third and so on.

If set to ROUND-ROBIN LdapAuth will use a round-robin algorithm to select the LDAP server to which the connection should be established. Any number of servers may be included in the set and each request will attempt to retrieve a connection to the next server in the list, circling back to the beginning of the list as necessary. If a server is unavailable when an attempt is made to establish a connection to it, then the connection will be established to the next available server in the list.

To specify LDAP server failover:

ldapAuth.ldapServer.selectionAlgorithm = FAILOVER

To specify round-robin server selection:

ldapAuth.ldapServer.selectionAlgorithm = ROUND-ROBIN

ldapAuth.ldapServer.connectTimeout

The timeout in milliseconds for LDAP connect requests. If zero the underlying LDAP client library will handle this value.

To specify a connect timeout of 100 milliseconds:

ldapAuth.ldapServer.connectTimeout = 100

ldapAuth.ldapServer.security

The LDAP connection security.

• Set to none to establish a plain insecure connection.

• Set to SSL to establish a secure connection over SSL.

• Set to StartTLS to establish a secure connection using the StartTLS protocol (recommended method).

Choose StartTLS or SSL for secure LDAP connections:

ldapAuth.ldapServer.security = StartTLS

ldapAuth.ldapServer.trustSelfSignedCerts

Determines whether to accept self-signed certificates presented by the LDAP server (for secure SSL or StartTLS connections).

To trust self-signed X.509 server certificates:

ldapAuth.ldapServer.trustSelfSignedCerts = true

ldapAuth.ldapServer.connectionPoolSize

The target search connection pool size. Applies only if ldapAuth.dnResolution.method is set to SEARCH and ldapAuth.authBackend is LDAP.

The default LDAP connection pool size is five:

ldapAuth.ldapServer.searchConnectionPoolSize = 5

ldapAuth.ldapServer.connectionPoolMaxWaitTime

The maximum length of time in milliseconds to wait for a connection to become available when trying to obtain a search connection from the pool. A value of zero should be used to indicate that the pool should not block at all if no connections are available and that it should either create a new connection or throw an exception.

Applies only if ldapAuth.dnResolution.method is set to SEARCH and and ldapAuth.authBackend is LDAP.

The default max wait time is 500 milliseconds:

ldapAuth.ldapServer.connectionPoolMaxWaitTime = 500

User DN resolution

The ldapAuth.dnResolution.* properties specify the procedure for resolving a user’s distinguished name (DN) from the username / email supplied with the auth request.

ldapAuth.dnResolution.method

The preferred user DN resolution method.

• Set to TEMPLATE to resolve the DN by substituting the supplied username in a DN template. You then must also set a DN template.

• Set to SEARCH to resolve the DN by performing a search operation against the LDAP directory for the supplied username / email. You then must also set a search user DN, search user password, search base DN, a search scope and a search filter.

• Set to NONE to let the back-end directory resolve the user DN. Requires directory support for plain SASL bind with usernames (RFC 4616).

To use a simple DN template:

ldapAuth.dnResolution.method = TEMPLATE

ldapAuth.dnResolution.dnTemplate

The DN template (if method TEMPLATE is selected, otherwise ignored). Each occurrence of the %u placeholder is substituted by the supplied username (leading and trailing whitespace trimmed), the resulting string then becomes the user DN.

Example:

ldapAuth.dnResolution.dnTemplate = UID=%u,OU=people,DC=example,DC=com

ldapAuth.dnResolution.searchUserDN

The search user DN (if method SEARCH is selected, otherwise ignored). A blank value signifies an anonymous user.

Example:

ldapAuth.searchUser.dn = CN=Search User,DC=Example,DC=com

ldapAuth.dnResolution.searchUserPassword

The search user password (if method SEARCH is selected, otherwise ignored). A blank value signifies an anonymous user.

ldapAuth.dnResolution.searchBaseDN

The search base DN (if method SEARCH is selected, otherwise ignored).

Example:

ldapAuth.dnResolution.searchBaseDN = OU=people,DC=example,DC=com

ldapAuth.dnResolution.searchScope

The search scope (if method SEARCH is selected, otherwise ignored).

• Set to BASE to consider only the entry specified by the base DN.

• Set to ONE to consider only entries that are immediate subordinates of the entry specified by the base DN (but not the base entry itself).

• Set to SUB to consider the base entry itself and any subordinate entries (to any depth).

Example:

ldapAuth.dnResolution.searchScope = ONE

ldapAuth.dnResolution.searchFilter

The search filter string (if method SEARCH is selected, otherwise ignored). Each occurrence of the %u placeholder is substituted by the supplied username / email (leading and trailing whitespace trimmed), the resulting string then becomes the final search filter.

Example: Authenticate users by username and email:

ldapAuth.dnResolution.searchFilter = (|(uid=%u)(mail=%u))

User attributes for retrieval

The ldapAuth.userAttributes.* properties specify the user attributes to return with a user.authGet or user.get response. The respective ldapAuth.api.allowUserAuthGetRequests and / or ldapAuth.api.allowUserGetRequests setting must also be enabled.

ldapAuth.userAttributes.single.*

Specifies single-valued user entry attributes to retrieve. Use for attributes such as name, initials and IDs.

These must be key/value pairs where the keys define the JSON attribute names and the values the corresponding LDAP attribute names, e.g.

JSON-field-name = LDAP-attribute-name

Example:

ldapAuth.userAttributes.single.userID = uid
ldapAuth.userAttributes.single.name = cn

ldapAuth.userAttributes.multi.*

Specifies multi-valued user entry attributes to retrieve. User for attributes such as email addresses, contact details and permissions / authorisations.

These must be key/value pairs where the keys define the JSON attribute names and the values are one or more corresponding LDAP attribute names, e.g.

JSON-field-name = LDAP-attribute-name-1 LDAP-attribute-name-2 ...

Example:

ldapAuth.userAttributes.single.phone = telephoneNumber mobile homePhone
ldapAuth.userAttributes.single.groups = memberOf

Custom trust and key store for TLS/SSL LDAP

The ldapAuth.customTrustStore.* and ldapAuth.customKeyStore.* properties specify custom trust and key stores (apart from those provided by the underlying JVM) to establish the security context of TLS/SSL connections to the back-end LDAP server.

ldapAuth.customTrustStore.enable

Set to true to use your custom trust store file for determining the acceptable security certificates presented by remote LDAP servers.

Set to false to use the default trust store of the web server / host system (if one has been provided and correctly configured).

If you set this to true you must also specify a trust store file, type and password (see the corresponding parameters below).

ldapAuth.customTrustStore.file

The location of the custom trust store file.

Example:

ldapAuth.customTrustStore.file = WEB-INF/truststore.jks

ldapAuth.customTrustStore.type

The type of the trust store file, typically JKS or PKCS12.

Set to an empty string to assume the system default type.

ldapAuth.customTrustStore.password

The password required to unlock the trust store file.

Set to an empty string if none is required.

ldapAuth.customKeyStore.enable

Set to true to use your custom key store file for client security certificates to be presented to remote LDAP servers requiring such authentication.

Set to false to use the default key store of the web server / host system (if one has been provided and correctly configured).

If you set this to true you must also specify a key store file, type and password (see the corresponding parameters below).

ldapAuth.customKeyStore.file

The location of the custom key store file.

Example:

ldapAuth.customKeyStore.file = WEB-INF/keystore.jks

ldapAuth.customKeyStore.type

The type of the trust store file, typically JKS or PKCS12.

Set to an empty string to assume the system default type.

ldapAuth.customKeyStore.password

The password required to unlock the key store file.

Set to an empty string if none is required.

Sample directory server

A sample LDAP directory server is included in the LdapAuth WAR to enable evaluation and testing of the service without an external directory. The sample directory is enabled / disabled and configured by the following properties file:

/WEB-INF/sampleDirectory.properties

If enabled, access to the sample directory server is limited to read and bind (authenticate) only. So after the directory is populated with the initial data no further changes can be made to it.

sampleDirectoryServer.enable

Set to true to enable the sample directory server. Access is limited to read and bind (authenticate) only. If enabled you must also specify the additional server details below.

Set to false to disable the sample directory server.

sampleDirectoryServer.enable = true

sampleDirectoryServer.port

The port number on which the sample directory server accepts LDAP client connections. SSL and StartTLS connections are not supported at present.

Set to zero to let the server automatically select an available port which will be recorded in the Json2Ldap log.

Note that the server may require a special OS permission to use a privileged port number below 1024.

sampleDirectoryServer.port = 10389

sampleDirectoryServer.schema

Specifies an alternative schema for the sample directory server. The alternative schema must be supplied in a single LDIF file. Its location must be relative to the web application (WAR) root directory.

If undefined the default built-in server schema will be used.

sampleDirectoryServer.schema = /WEB-INF/sampleDirectorySchema.ldif

sampleDirectoryServer.baseDN

The base distinguished name (DN) of the directory information tree (DIT). It must match the top level entry of the content LDIF (if supplied).

sampleDirectoryServer.baseDN = dc=wonderland,dc=net

sampleDirectoryServer.content

Reads entries from the specified LDIF file to populate the directory tree. The location of the file must be relative to the web application (WAR) root directory.

If undefined the directory will be left empty.

LdapAuth comes with a demo LDIF file containing a directory tree with 26 person entries and 4 groups.

sampleDirectoryServer.content = /WEB-INF/sampleDirectoryContent.ldif

Cross-Origin Resource Sharing (CORS)

The LdapAuth web service includes a CORS Filter to allow transparent handling of browser cross-site requests according to the W3C Cross-Origin Resource Sharing (CORS) mechanism.

To configure the CORS policy edit the following properties file in the WEB-INF directory of the web application:

WEB-INF/cors.properties

cors.allowGenericHttpRequests

Set to true to allow generic HTTP requests, else only valid and accepted CORS requests will be allowed (strict CORS filtering).

Recommended value: true

cors.allowOrigin

Lists the allowed CORS origins. They must be specified as whitespace-separated URLs. Requests from origins not included here will be refused with an HTTP 403 “Forbidden” response. If set to * any origin is allowed.

Example: Allow any origin:

cors.allowOrigin = *

Example: Allow cross-domain requests from the following three origins only:

cors.allowOrigin = http://example.com http://example.com:8080 https://secure.net

cors.allowSubdomains

If true the CORS filter will allow requests from any origin which is a subdomain origin of the allowed origins. A subdomain is matched by comparing its scheme and suffix (host name / IP address and optional port number).

cors.supportedMethods

Lists the supported HTTP methods. Requests for methods not included here will be refused by the CORS filter with an HTTP 405 “Method not allowed” response.

LdapAuth supports only GET and POST. Do not change this parameter.

cors.supportedHeaders

Lists the supported non-simple (according to the CORS standard) header names.

Applications that wish to specify an application/json request content type should be allowed so.

Recommended value: Content-Type

cors.exposedHeaders

Lists the non-simple headers (according to the CORS standard) that the web client (browser) should expose.

LdapAuth sets a custom X-Web-Service header to identify itself. Do not change this parameter.

cors.supportsCredentials

Indicates whether user credentials, such as cookies, HTTP authentication or client-side certificates, are supported.

LdapAuth doesn’t support such user credentials. Do not change this parameter.

cors.maxAge

Indicates how long the results of a CORS preflight request can be cached by the web client, in seconds. If -1 unspecified.

Recommended value: 1 day (86400 seconds).

Logging

LdapAuth uses the popular Log4j framework to handle logging.

The Log4j configuration file is located in the WEB-INF directory of the web application:

WEB-INF/log4j.xml

Refer to the Log4j manual for how to edit the configuration file.