Top Description Fields Constructors Methods
org.hsqldb.auth

public Class LdapAuthBean

extends Object
implements AuthFunctionBean
Class Inheritance
All Implemented Interfaces
org.hsqldb.auth.AuthFunctionBean
Imports
java.io.IOException, java.util.ArrayList, .Hashtable, .List, java.util.regex.Matcher, .Pattern, javax.naming.AuthenticationException, .Context, .NamingEnumeration, .NamingException, javax.naming.directory.Attribute, .Attributes, .BasicAttributes, .SearchResult, javax.naming.ldap.InitialLdapContext, .LdapContext, .StartTlsRequest, .StartTlsResponse, org.hsqldb.lib.FrameworkLogger
Authenticates to a HyperSQL catalog according to entries in a LDAP database. If using LDAP StartTLS and your server has a certificate not trusted by default by your JRE, then set system property 'javax.net.ssl.trustStore' to the path to a trust store containing the cert (as well as any other certs that your app needs for other purposes).

This class with authenticate login attempts against LDAP entries with RDN of the HyperSQL account name (the precise attribute name defaults to 'uid', but you may change that).

This class purposefully does not support LDAPS, because LDAPS is deprecated in favor of StartTLS, which we do support. If you need to support LDAPS and are using SE 1.6, use our JaasAuthBean with Sun's LdapLoginModule.

This class does not support SASL/External authentication, because the work involved with securely obtaining user-specific certs would be more complex than everything else here combined. Another AuthFunctionBean would have to be written if SASL/External is needed.

To use instances of this class, you must use at least the methods setLdapHost, setParentDn, initialize, plus rolesSchemaAttribute and/or accessAttribute.

For a user to be given HyperSQL catalog access, that user must either have a value for accessAttribute if that property is set (optionally requiring a match with accessValuePattern); or, if the accessAttribute is not set then must have some (any) value for rolesSchemaAttribute (optionally requiring a match with roleSchemaValuePattern). Consequently, if you have set both accessAttribute and rolesSchemaAttribute, the latter attribute will only be consulted if the check of the former attribute succeeds.

If you want roles assigned according to the local HyperSQL database instead of according to LDAP, then set accessAttribute but not rolesSchemaAttribute.

If what is wanted is to grant access but with no roles (overriding local roles if there are any), then set both accessAttribute and rolesSchemaAttribute, but do not set any rolesSchemaAttribute attribute values for these no-role users. (I hesitate to mention it, but you could accomplish the same thing with only a rolesSchemaAttribute attribute, by setting only a dummy role/schema value for non-role users, because HyperSQL will ignore unknown roles or schemas but still give access since a list was still supplied).

Author
Blaine Simpson (blaine dot simpson at admc dot com)
Since
2.5.0
See Also
AuthFunctionBean, setLdapHost(String), setParentDn(String), init()

Field Summary

Modifier and TypeField and Description
private String
accessAttribute

private Pattern
accessValuePattern

protected String[]
attributeUnion

private String
initialContextFactory

private boolean
initialized

private String
ldapHost

private Integer
ldapPort

private static FrameworkLogger
logger

private String
mechanism

private String
parentDn

private String
principalTemplate

private String
rdnAttribute

private Pattern
roleSchemaValuePattern

private String
rolesSchemaAttribute

private String
saslRealm

private boolean
tls

Constructor Summary

AccessConstructor and Description
public
LdapAuthBean()

Method Summary

Modifier and TypeMethod and Description
public String[]

Returns:

String[]
authenticate(String
String
userName, String
String
password)

Implements org.hsqldb.auth.AuthFunctionBean.authenticate.

Return a list of authorized roles or null to indicate that the implementation does not intend to produce a specific role list but only to indicate whether to allow access or not.

public void
init()

public void
setAccessAttribute(String
attribute
attribute)

Set the attribute name of the RDN + parentDn entries which will be consulted to decide whether the user can access the HyperSQL database.

public void
setAccessValuePattern(Pattern
Pattern
accessValuePattern)

Assign a pattern to detect honored accessAttribute values.

public void
setAccessValuePatternString(String
String
patternString)

String wrapper for method setAccessValuePattern(Pattern) Use the (x?) Pattern constructs to set options.

public void
setInitialContextFactory(String
factory
initialContextFactory)

Most users should not call this, and will get the default of "com.sun.jndi.ldap.LdapCtxFactory".

public void
setLdapHost(String
host
ldapHost)

Do not specify URL scheme ("ldap:") because that is implied.

public void
setLdapPort(int ldapPort)

public void
setParentDn(String
parent DN
parentDn)

Set DN which is parent of the user DNs.

public void
setPrincipalTemplate(String
template
principalTemplate)

A template String containing place-holder token '${username}'.

public void
setRdnAttribute(String
RDN attribute
rdnAttribute)

rdnAttribute must hold the user name exactly as the HyperSQL login will be made with.

public void
setRoleSchemaValuePattern(Pattern
pattern
roleSchemaValuePattern)

Assign a pattern to both detect honored values, and to map from a single value of "rolesSchemaAttribute"s to a HyperSQL role or schema string.

public void
setRoleSchemaValuePatternString(String
pattern
patternString)

String wrapper for method setRoleSchemaValuePattern(Pattern) Use the (x?) Pattern constructs to set options.

public void
setRolesSchemaAttribute(String
attribute
attribute)

Set the attribute name of the RDN + parentDn entries in which is stored the list of roles and optional schema for the authenticating user.

public void
setSaslRealm(String
realm
saslRealm)

Some LDAP servers using a SASL mechanism require a realm to be specified, and some mechanisms allow a realm to be specified if you wish to use that feature.

public void
setSecurityMechanism(String
Either 'SIMPLE' (the default) for LDAP Simple, or one of the LDAP SASL mechanisms, such as 'DIGEST-MD5'.
mechanism)

Defaults to "SIMPLE".

public void
setStartTls(boolean
boolean
isTls)

If this is set, then the entire (brief) transaction with the LDAP server will be encrypted.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

accessAttributeback to summary
private String accessAttribute
accessValuePatternback to summary
private Pattern accessValuePattern
attributeUnionback to summary
protected String[] attributeUnion
initialContextFactoryback to summary
private String initialContextFactory
initializedback to summary
private boolean initialized
ldapHostback to summary
private String ldapHost
ldapPortback to summary
private Integer ldapPort
loggerback to summary
private static FrameworkLogger logger
mechanismback to summary
private String mechanism
parentDnback to summary
private String parentDn
principalTemplateback to summary
private String principalTemplate
rdnAttributeback to summary
private String rdnAttribute
roleSchemaValuePatternback to summary
private Pattern roleSchemaValuePattern
rolesSchemaAttributeback to summary
private String rolesSchemaAttribute
saslRealmback to summary
private String saslRealm
tlsback to summary
private boolean tls

Constructor Detail

LdapAuthBeanback to summary
public LdapAuthBean()

Method Detail

authenticateback to summary
public String[] authenticate(String userName, String password) throws DenyException

Implements org.hsqldb.auth.AuthFunctionBean.authenticate.

Doc from org.hsqldb.auth.AuthFunctionBean.authenticate.

Return a list of authorized roles or null to indicate that the implementation does not intend to produce a specific role list but only to indicate whether to allow access or not. A return value of String[0] is different from returning null, and means that the user should not be granted any roles.

Parameters
userName:String

String

password:String

String

Returns:String[]

String[]

Exceptions
DenyException:
on access denial
initback to summary
public void init()
Exceptions
IllegalStateException:
if any required setting has not been set.
setAccessAttributeback to summary
public void setAccessAttribute(String attribute)

Set the attribute name of the RDN + parentDn entries which will be consulted to decide whether the user can access the HyperSQL database.

There is no default. If you set this attribute, then the attribute will determine whether the user can access the HyperSQL database, regardless of whether the rolesSchemaAttribute attribute is set.

If you set just this property, then the local HyperSQL database will decide all roles for the user. If you set this property and property rolesSchemaAttribute then this attribute will determine access, and if this attribute grants access then the rolesSchemaAttribute value will determine the user's roles.

Parameters
attribute:String

attribute

setAccessValuePatternback to summary
public void setAccessValuePattern(Pattern accessValuePattern)

Assign a pattern to detect honored accessAttribute values. If you set accessAttribute but not accessValuePattern, then all that will be checked for access is if the RDN + parentDN entry has the accessAttribute attribute. (I.e. the specific value will not matter whatsoever).

You may only use this property if you have set property accessAttribute. If you have set accessAttribute but not this property, then access will be decided based solely upon existence of this attribute.

Capture groups in the pattern will be ignored and serve no purpose.

N.b. this Pattern will be used for the matches() operation, therefore it must match the entire candidate value strings (this is different than the find operation which does not need to satisfy the entire candidate value).

Example1 :

TRUE
This will match true values per OpenLDAP's boolean OID.
Parameters
accessValuePattern:Pattern

Pattern

See Also
Matcher#matches()
setAccessValuePatternStringback to summary
public void setAccessValuePatternString(String patternString)

String wrapper for method setAccessValuePattern(Pattern) Use the (x?) Pattern constructs to set options.

Parameters
patternString:String

String

See Also
setAccessValuePattern(Pattern)
setInitialContextFactoryback to summary
public void setInitialContextFactory(String initialContextFactory)

Most users should not call this, and will get the default of "com.sun.jndi.ldap.LdapCtxFactory". Use this method if you prefer to use a context factory provided by your framework or container, for example, or if you are using a non-Sun JRE.

Parameters
initialContextFactory:String

factory

setLdapHostback to summary
public void setLdapHost(String ldapHost)

Do not specify URL scheme ("ldap:") because that is implied. (Since we purposefully don't support LDAPS, there would be no reason to change that).

If using StartTLS, then this host name must match the cn of the LDAP server's certificate.

If you need to support LDAPS and are using SE 1.6, use our JaasAuthBean with Sun's LdapLoginModule instead of this class.

Parameters
ldapHost:String

host

See Also
JaasAuthBean
setLdapPortback to summary
public void setLdapPort(int ldapPort)
setParentDnback to summary
public void setParentDn(String parentDn)

Set DN which is parent of the user DNs. E.g. "ou=people,dc=admc,dc=com"

Parameters
parentDn:String

parent DN

setPrincipalTemplateback to summary
public void setPrincipalTemplate(String principalTemplate)

A template String containing place-holder token '${username}'. All occurrences of '${username}' (without the quotes) will be translated to the username that authentication is being attempted with.

If you supply a principalTemplate that does not contain '${username}', then authentication will be user-independent.

It is common to authenticate to LDAP servers with the DN of the user's LDAP entry. In this situation, set principalTemplate to <RDN_ATTR=>${username},<PARENT_DN>. For example if you use parentDn of "ou=people,dc=admc,dc=com" and rdnAttribute of uid, then you would set 

"uid=${username},ou=people,dc=admc,dc=com"

By default the user name will be passed exactly as it is, so don't use this setter if that is what you want. (This works great for OpenLDAP with DIGEST-MD5 SASL, for example).

Parameters
principalTemplate:String

template

setRdnAttributeback to summary
public void setRdnAttribute(String rdnAttribute)

rdnAttribute must hold the user name exactly as the HyperSQL login will be made with.

This is the RDN relative to the Parent DN specified with setParentDN. Defaults to 'uid'.

Parameters
rdnAttribute:String

RDN attribute

See Also
setParentDn(String)
setRoleSchemaValuePatternback to summary
public void setRoleSchemaValuePattern(Pattern roleSchemaValuePattern)

Assign a pattern to both detect honored values, and to map from a single value of "rolesSchemaAttribute"s to a HyperSQL role or schema string. If your rolesSchemaAttribute holds only the String values precisely as HyperSQL needs them, then don't use this method at all and all matching attribute values will be passed directly.

You may only use this property if you have set property rolesSchemaAttribute. If rolesSchemaAttribute is set but this property is not set, then the value will directly determine the user's roles and schema.

Unlike the rolesSchemaAttribute, the property at-hand uses the singular for "role", because whereas rolesSchemaAttribute is the attribute for listing multiple roles, roleSchemaValuePattern is used to evaluate single role values.

These are two distinct and important purposes for the specified Pattern.

  1. Values that do not successfully match the pattern will be ignored.
  2. Optionally uses parentheses to specify a single capture group (if you use parentheses to specify more than one matching group, we will only capture for the first). What is captured by this group is exactly the role or schema that HyperSQL will attempt to assign. If no capture parens are given then the Pattern is only used for the acceptance decision, and the LDAP-provided value will be returned verbatim.

Together, these two features work great to extract just the needed role and schema names from 'memberof' DNs, and will have no problem if you also use 'memberof' for unrelated purposes.

N.b. this Pattern will be used for the matches() operation, therefore it must match the entire candidate value strings (this is different than the find operation which does not need to satisfy the entire candidate value).

Example1 :

cn=([^,]+),ou=dbRole,dc=admc,dc=com
will extract the CN value from matching attribute values.

Example1 :

cn=[^,]+,ou=dbRole,dc=admc,dc=com
will return the entire cn...com string for matching attribute values.
Parameters
roleSchemaValuePattern:Pattern

pattern

See Also
Matcher#matches()
setRoleSchemaValuePatternStringback to summary
public void setRoleSchemaValuePatternString(String patternString)

String wrapper for method setRoleSchemaValuePattern(Pattern) Use the (x?) Pattern constructs to set options.

Parameters
patternString:String

pattern

Exceptions
PatternSyntaxException:
exception
See Also
setRoleSchemaValuePattern(Pattern)
setRolesSchemaAttributeback to summary
public void setRolesSchemaAttribute(String attribute)

Set the attribute name of the RDN + parentDn entries in which is stored the list of roles and optional schema for the authenticating user.

There is no default. You must set this attribute if you want LDAP instead of the local HyperSQL database to determine the user's roles! You must set the rolesSchemaAttribute property and/or the accessAttribute property. Consequently, if you do no tset this property, then you must set the accessAttribute property, and this LdapAuthBean will only determine access not roles.

To use the nice reverse group membership feature of LDAP, set this value to "memberof".

If you have set both rolesSchemaAttribute and this value, then the attribute set here will only be consulted if the accessAttribute check succeeds.

Parameters
attribute:String

attribute

setSaslRealmback to summary
public void setSaslRealm(String saslRealm)

Some LDAP servers using a SASL mechanism require a realm to be specified, and some mechanisms allow a realm to be specified if you wish to use that feature. By default no realm will be sent to the LDAP server.

Don't use this setter if you are not setting a SASL mechanism.

Parameters
saslRealm:String

realm

setSecurityMechanismback to summary
public void setSecurityMechanism(String mechanism)

Defaults to "SIMPLE".

Parameters
mechanism:String

Either 'SIMPLE' (the default) for LDAP Simple, or one of the LDAP SASL mechanisms, such as 'DIGEST-MD5'.

setStartTlsback to summary
public void setStartTls(boolean isTls)

If this is set, then the entire (brief) transaction with the LDAP server will be encrypted.

Parameters
isTls:boolean

boolean