LDAP claims source
The Connect2id server comes with a ready connector for retrieving UserInfo and other claims about a user from an LDAP directory, such as Microsoft Active Directory, Novell eDirectory, OpenLDAP or OpenDJ.
To enable / disable or configure the LDAP claims source connector edit the
following properties file in the WEB-INF
directory of the web application:
WEB-INF/ldapClaimsSource.properties
The file contains configuration properties split into six sections:
- General settings – to enable / disable the LDAP claims source.
- LDAP server connection details – to set the LDAP server connection details.
- LDAP user credentials – to set the LDAP server connection credentials.
- LDAP search configuration – to set the LDAP search parameters, such as filter, for retrieving the user entries and attributes.
- Custom LDAP server trust and key store – to set a custom certificate trust and / or key key for secure LDAP connections.
Any configuration file property can be overridden by setting a system-wide
property with a matching key, e.g. by using the optional -D
argument at JVM
startup:
-Dop.ldapClaimsSource.enable=false
To set the mapping of the LDAP attributes to UserInfo claims edit the following JSON file:
ldapClaimsMap.json
The claims source SPI and the LDAP connector implementation are open sourced and yon use them to devise your own custom connectors (e.g. for an SQL database).
https://bitbucket.org/connect2id/openid-connect-claims-source-spi
https://bitbucket.org/connect2id/openid-connect-ldap-claims-source
1. General settings
Contains a single property to enable / disable the LDAP claims source.
op.ldapClaimsSource.enable
This boolean setting enables / disables the LDAP claims source.
To enable it:
op.ldapClaimsSource.enable = true
To disable it:
op.ldapClaimsSource.enable = false
2. LDAP server details
The op.ldapClaimsSource.server.*
properties set the LDAP server connection
details.
op.ldapClaimsSource.server.url
The LDAP URL of the directory server for sourcing the claims. 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 op.ldapClaimsSource.ldapServer.selectionAlgorithm.
Example single LDAP server URL pointing to the local host:
op.ldapClaimsSource.server.url = ldap://localhost:1389
Example list of two LDAP server URLs (for use in a failover or load-balancing configuration):
op.ldapClaimsSource.server.url = ldap://192.168.1.10:1389 ldap://192.168.1.11:1389
op.ldapClaimsSource.server.selectionAlgorithm
The preferred server selection algorithm in case op.ldapClaimsSource.server. url is an LDAP server set:
-
FAILOVER
– 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. -
ROUND-ROBIN
– 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 failover server selection:
op.ldapClaimsSource.server.selectionAlgorithm = FAILOVER
op.ldapClaimsSource.server.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 250 ms:
op.ldapClaimsSource.server.connectTimeout = 250
op.ldapClaimsSource.server.security
The LDAP connection security:
-
NONE
– Establish a plain insecure connection. -
SSL
– Establish a secure connection over SSL. -
StartTLS
– Establish a secure connection using the StartTLS protocol (recommended method).
To use StartTLS for LDAP connections:
op.ldapClaimsSource.server.security = StartTLS
op.ldapClaimsSource.server.trustSelfSignedCerts
Determines whether to accept self-signed certificates presented by the LDAP server (for secure SSL or StartTLS connections). Self-signed certificates are not trusted by default.
To reject self-signed certificates:
op.ldapClaimsSource.server.trustSelfSignedCerts = false
op.ldapClaimsSource.server.connectionPoolSize
The maximum LDAP connection pool size. The default value is five connections.
To create a pool for 5 LDAP connections:
op.ldapClaimsSource.server.connectionPoolSize = 5
op.ldapClaimsSource.server.connectionPoolMaxWaitTime
The maximum length of time in milliseconds to wait for a connection to become available when trying to obtain an LDAP 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.
To set the max LDAP connection pool wait time to 250ms:
op.ldapClaimsSource.server.connectionPoolMaxWaitTime = 250
op.ldapClaimsSource.server.connectionMaxAge
The maximum time in milliseconds that an LDAP 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. Defaults to no maximum age (zero).
To disable LDAP connection expiration:
op.ldapClaimsSource.server.connectionMaxAge = 0
3. LDAP user details
The op.ldapClaimsSource.directory.user.*
set the LDAP server connection
credentials.
op.ldapClaimsSource.directory.user.dn
The distinguished name (DN) of the LDAP directory user to perform the claims retrieval operations. Must have search and read access to the directory branch containing the subject entries. An empty value implies an anonymous user.
Example user DN:
op.ldapClaimsSource.directory.user.dn = cn=Directory Manager
op.ldapClaimsSource.directory.user.password
The directory user password. An empty value implies an anonymous user.
Example password:
op.ldapClaimsSource.directory.user.password = secret
4. LDAP search configuration
The op.ldapClaimsSource.directory.*
properties set the LDAP search
parameters, such as filter, for retrieving the user entries and attributes.
op.ldapClaimsSource.directory.baseDN
The base distinguished name (DN) of the LDAP directory branch where the subject (user) entries are stored.
op.ldapClaimsSource.directory.baseDN = ou=people,dc=wonderland,dc=net
op.ldapClaimsSource.directory.scope
The LDAP search scope for the subject entries with respect to the base DN specified in op.ldapClaimsSource.directory.baseDN:
-
ONE
– indicates that only entries that are immediate subordinates of the base entry (but not the base entry itself) should be considered. -
SUB
– Indicates that the base entry itself and any subordinate entries (to any depth) should be considered. -
SUBORDINATE_SUBTREE
– Indicates that any subordinate entries (to any depth) below the base entry should be considered, but the base entry itself should not be considered, as described in draft-sermersheim-ldap-subordinate-scope.
op.ldapClaimsSource.directory.scope = ONE
op.ldapClaimsSource.directory.filter
The LDAP search filter to retrieve the subject entries. The %u
placeholder
will be substituted with the subject identifier (sub).
op.ldapClaimsSource.directory.filter = (uid=%u)
5. Custom LDAP server trust and key store
The op.ldapClaimsSource.customTrustStore.*
and
op.ldapClaimsSource.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 LDAP servers.
op.ldapClaimsSource.customTrustStore.enable
Set to true
to use your custom trust store file for determining the
acceptable security certificates presented by the remote LDAP server.
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).
op.ldapClaimsSource.customTrustStore.enable = false
op.ldapClaimsSource.customTrustStore.file
The location of the custom trust store file.
Example:
op.ldapClaimsSource.customTrustStore.file = WEB-INF/truststore.jks
op.ldapClaimsSource.customTrustStore.password
The password required to unlock the trust store file. Leave it empty if none is required.
Example:
op.ldapClaimsSource.customTrustStore.password = secret
op.ldapClaimsSource.customTrustStore.type
The type of the trust store file, typically JKS or PKCS12. Leave it empty to assume the system default type.
Example:
op.ldapClaimsSource.customTrustStore.type = JKS
op.ldapClaimsSource.customKeyStore.enable
Set to true
to use your custom key store file for client security
certificates to be presented to the remote LDAP server 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).
op.ldapClaimsSource.customKeyStore.enable = false
The location of the custom key store file.
Example:
op.ldapClaimsSource.customKeyStore.file = WEB-INF/keystore.jks
op.ldapClaimsSource.customKeyStore.password
The password required to unlock the key store file. Leave it empty if none is required.
Example:
op.ldapClaimsSource.customKeyStore.password =
op.ldapClaimsSource.customKeyStore.type
The type of the trust store file, typically JKS
or PKCS12
. Leave it empty
to assume the system default type.
Example:
op.ldapClaimsSource.customKeyStore.type = JKS