org.norther.tammi.core.realm
Interface JndiRealm

All Superinterfaces:

Configurable, Realm

All Known Implementing Classes:

DefaultJndiRealm

public interface JndiRealm
extends Realm

An interface to realms working with a directory server accessed via the Java Naming and Directory Interface (JNDI) APIs.

The following constraints are imposed on the data structure in the underlying directory server:

• Each user that can be authenticated is represented by an individual element in the top level DirContext that is accessed via the connectionURL property.
• Each user element has a distinguished name that can be formed by substituting the presented username into a pattern configured by the userNamePattern property.
• Alternatively, if the userNamePattern property is not specified, a unique element can be located by searching the directory context. In this case:
  • The userSearchPattern property specifies the search filter after substitution of the username.
  • The userBase property can be set to the name that is the base of the subtree containing users. If not specified, the search base is the top-level context.
  • The userSearchScope property can be set to search one sublevel or the entire subtree of the directory context. The default value of 0 requests a search of only the current level.
• The user may be authenticated by binding to the directory with the username and password presented. This method is used when the userPasswordAttribute property is not specified.
• The user may be authenticated by retrieving the value of an attribute from the directory and comparing it explicitly with the value presented by the user. This method is used when the userPasswordAttribute property is specified, in which case:
  • The element for this user must contain an attribute named by the userPasswordAttribute property.
  • The value of the user password attribute is either a cleartext string, or the result of applying the RealmMBean digest to the cleartext string.
  • The user is considered to be authenticated if the presented credentials (after applying the digest) are equal to the retrieved value for the user password attribute.
• Each group of users that has been assigned a particular role may be represented by an individual element in the top level DirContext that is accessed via the connectionURL property. This element has the following characteristics:
  • The set of all possible groups of interest can be selected by a search pattern configured by the roleSearchPattern property.
  • The roleSearchPattern property specifies the search filter after substitution of the distinguished name, and/or the username, of the authenticated user for which roles will be retrieved.
  • The roleBase property can be set to the name that is the base of the search for matching roles. If not specified, the entire context will be searched.
  • The roleSearchScope property can be set to search one sublevel or the entire subtree of the directory context. The default value of 0 requests a search of only the current level.
  • The element includes an attribute (whose name is configured by the roleNameAttribute property) containing the name of the role represented by this element.
• In addition, roles may be represented by the values of an attribute in the user's element whose name is configured by the userRoleNameAttribute property.

Some of the properties can also be specified in a property file using the following syntax (all properties with a java prefix are passed to the context as its environment):

 ##
 # JNDI properties.
 #java.naming.provider.url: ldap://tammi.norther.org
 #java.naming.security.authentication: DIGEST-MD5
 #java.naming.security.principal: ldap@norther.org
 #java.naming.security.credentials: secret
 ##
 # A role with members from a directory group.
 # 'role'.member = 'group'
 admin.member = Domain Admins
 user.member = Domain Users
 guest.member = Domain Guests
 ##
 # The default role to give for an authenticated principal.
 default.role = user
 ##
 # An account for an anonymous user.
 anonymous.user = Guest
 ##
 # A digest algorithm.
 #digest.algorithm = MD5
 ##
 # The user base.
 user.base = cn=users,dc=norther,dc=org
 ##
 # The user search scope (0 = current, 1 = one level down, 2 = directory tree).
 user.search.scope = 1
 ##
 # The user search pattern.
 user.search.pattern = (&(objectclass=user) (sAMAccountName={0}))
 ##
 # The username pattern (an alternative to the search pattern).
 #username.pattern = cn={0},ou=tammi,o=norther
 ##
 # A password attribute (if applicable, otherwise bind is applied).
 #password.attribute = userPassword
 ##
 # The role base.
 role.base = dc=norther,dc=org
 ##
 # The role search scope (0 = current, 1 = one level down, 2 = directory tree).
 role.search.scope = 2
 ##
 # The role search pattern.
 role.search.pattern = (&(objectclass=group) (member={0}))
 ##
 # A role name attribute.
 role.name.attribute = cn
 ##
 # A user role name attribute (if applicable).
 #user.role.name.attribute = memberof
 ##
 # A default locale attribute (if applicable).
 #default.locale.attribute = defaultLocale
 

If role members are not specified, the directory groups themselves are used as roles.

Based on JNDIRealm in the Apache Jakarta Tomcat project.

Author:

John Holman, Craig R. McClanahan, Marketta Priha

Field Summary

Fields inherited from interface org.norther.tammi.core.realm.Realm

ANONYMOUS_USER_PROPERTY, CACHED_PASSWORDS_PROPERTY, DEFAULT_ROLE_PROPERTY, DIGEST_ALGORITHM_PROPERTY, MEMBER_PROPERTY, PUBLIC_NAME_PROPERTY

Method Summary

Attributes	getAttributes(String name) Gets all attributes associated with the named directory object.
String	getDefaultLocaleAttribute() Gets the default locale attribute used to retrieve user locale from the result of of user search.
String	getInitialContextFactory() Gets the JNDI initial context factory to apply.
String	getPasswordAttribute() Gets the password attribute used to retrieve the user password.
String	getProviderURL() Gets the provider URL to the directory of this realm.
String	getReferral() Gets the referrals processing instruction.
String	getRoleBase() Gets the base name for role searches.
String	getRoleNameAttribute() Gets the role name attribute used to retrieve user roles from the result of the role search.
String	getRoleSearchPattern() Gets the message format used to select roles for a user, with "{0}" marking the spot where the distinguished name of the user goes, and/or "{1}" marking the spot for the username of the principal.
int	getRoleSearchScope() Gets the scope for role searches.
String	getSecurityAuthentication() Gets the authentication level of the connection to the directory.
String	getSecurityPrincipal() Gets the principal for authenticating the connection to the directory.
String	getSecurityProtocol() Gets the protocol of the connection to the directory.
String	getUserBase() Gets the base name for user searches.
String	getUsernamePattern() Gets the message format pattern used to form the distinguished name of a user with "{0}" marking the spot where the specified username goes.
String	getUserRoleNameAttribute() Gets the user role name attribute used to retrieve user roles from the result of of user search.
String	getUserSearchPattern() Gets the message format pattern for searching users in this realm with "{0}" marking the spot where the username goes.
int	getUserSearchScope() Gets the scope for user searches.
DirContext	lookup() Returns a new connection to the directory that can be accessed concurrently.
List	search(String name, String filter, int scope) Searches in the named context or object for entries that satisfy the given search filter and within the given scope.
void	setDefaultLocaleAttribute(String name) Sets the default locale attribute used to retrieve user locale from the result of of user search.
void	setInitialContextFactory(String factory) Sets the JNDI initial context factory to apply.
void	setPasswordAttribute(String name) Sets the password attribute used to retrieve the user password.
void	setProviderURL(String URL) Sets the provider URL to the directory of this realm.
void	setReferral(String instruction) Sets the referrals processing instruction as specified by the javax.naming.Context inteface, e.g.
void	setRoleBase(String base) Sets the base name for role searches.
void	setRoleNameAttribute(String name) Sets the role name attribute used to retrieve user roles from the result of the role search.
void	setRoleSearchPattern(String pattern) Sets the message format used to select roles for a user, with "{0}" marking the spot where the distinguished name of the user goes, and/or "{1}" marking the spot for the username of the principal.
void	setRoleSearchScope(int scope) Sets the role search scope as specified by javax.naming.directory.SearchControls.
void	setSecurityAuthentication(String authentication) Sets the authentication level of the connection to the directory as specified by the javax.naming.Context interface, e.g.
void	setSecurityCredentials(String password) Sets the credentials for authenticating the connection to the directory.
void	setSecurityPrincipal(String username) Sets the principal for authenticating the connection to the directory.
void	setSecurityProtocol(String protocol) Sets the protocol of the connection to the directory, e.g.
void	setUserBase(String base) Sets the base name for user searches.
void	setUsernamePattern(String pattern) Sets the message format pattern used to form the distinguished name of a user with "{0}" marking the spot where the specified username goes.
void	setUserRoleNameAttribute(String name) Sets the user role name attribute used to retrieve user roles from the result of of user search.
void	setUserSearchPattern(String pattern) Sets the message format pattern for searching users in this realm with "{0}" marking the spot where the username goes.
void	setUserSearchScope(int scope) Sets the user search scope as specified by javax.naming.directory.SearchControls.

Methods inherited from interface org.norther.tammi.core.realm.Realm

authenticate, authenticate, authenticate, authenticate, authenticate, authenticate, authenticate, authenticate, digest, generateAuthenticate, getAnonymousUser, getAuthType, getDefaultRole, getDigestAlgorithm, getPublicName, identify, identify, isAuthenticated, isAuthenticated, isCachedPasswords, isUserInRole, setAnonymousUser, setCachedPasswords, setDefaultRole, setDigestAlgorithm, setPublicName

Methods inherited from interface org.norther.tammi.core.config.Configurable

addProperty, addProperty, clearProperties, containsProperty, getConfigKey, getProperties, getProperty, getPropertyFilePath, indexOfProperty, propertyMap, propertyMap, removeProperty, removeProperty, setConfigKey, setProperties, setProperty, setPropertyFilePath, setPropertyFilePath, storeProperties

Method Detail

getInitialContextFactory

String getInitialContextFactory()

Gets the JNDI initial context factory to apply.

Returns:

the JNDI initial context factory.

setInitialContextFactory

void setInitialContextFactory(String factory)

Sets the JNDI initial context factory to apply.

Parameters:

factory - the initial context factory.

getProviderURL

String getProviderURL()

Gets the provider URL to the directory of this realm.

Returns:

the provider URL.

setProviderURL

void setProviderURL(String URL)

Sets the provider URL to the directory of this realm.

Parameters:

URL - the provider URL.

getSecurityPrincipal

String getSecurityPrincipal()

Gets the principal for authenticating the connection to the directory.

Returns:

the security principal.

setSecurityPrincipal

void setSecurityPrincipal(String username)

Sets the principal for authenticating the connection to the directory.

Parameters:

username - the security principal.

setSecurityCredentials

void setSecurityCredentials(String password)

Sets the credentials for authenticating the connection to the directory.

Parameters:

password - the security credentials.

getSecurityAuthentication

String getSecurityAuthentication()

Gets the authentication level of the connection to the directory.

Returns:

the security authentication.

setSecurityAuthentication

void setSecurityAuthentication(String authentication)

Sets the authentication level of the connection to the directory as specified by the javax.naming.Context interface, e.g. "none", "simple" or a SASL mechanism like "DIGEST-MD5".

Parameters:

authentication - the security authentication.

getSecurityProtocol

String getSecurityProtocol()

Gets the protocol of the connection to the directory.

Returns:

the security protocol.

setSecurityProtocol

void setSecurityProtocol(String protocol)

Sets the protocol of the connection to the directory, e.g. "ssl".

Parameters:

protocol - the security protocol.

getReferral

String getReferral()

Gets the referrals processing instruction.

Returns:

the referral processing instruction.

setReferral

void setReferral(String instruction)

Sets the referrals processing instruction as specified by the javax.naming.Context inteface, e.g. "follow", "ignore" or "throw".

Parameters:

instruction - the referrals processing instruction.

getUserBase

String getUserBase()

Gets the base name for user searches.

Returns:

the user base name.

setUserBase

void setUserBase(String base)

Sets the base name for user searches.

Parameters:

base - the user base name.

getUserSearchScope

int getUserSearchScope()

Gets the scope for user searches.

Returns:

the user search scope.

setUserSearchScope

void setUserSearchScope(int scope)

Sets the user search scope as specified by javax.naming.directory.SearchControls.

Parameters:

scope - the user search scope.

getUserSearchPattern

String getUserSearchPattern()

Gets the message format pattern for searching users in this realm with "{0}" marking the spot where the username goes.

Returns:

the user search pattern.

setUserSearchPattern

void setUserSearchPattern(String pattern)

Sets the message format pattern for searching users in this realm with "{0}" marking the spot where the username goes.

Parameters:

pattern - the user search pattern.

getUsernamePattern

String getUsernamePattern()

Gets the message format pattern used to form the distinguished name of a user with "{0}" marking the spot where the specified username goes.

Returns:

the username pattern.

setUsernamePattern

void setUsernamePattern(String pattern)

Sets the message format pattern used to form the distinguished name of a user with "{0}" marking the spot where the specified username goes.

Parameters:

pattern - the username pattern.

getRoleBase

String getRoleBase()

Gets the base name for role searches.

Returns:

the role base name.

setRoleBase

void setRoleBase(String base)

Sets the base name for role searches.

Parameters:

base - the role base name.

getRoleSearchScope

int getRoleSearchScope()

Gets the scope for role searches.

Returns:

the role search scope.

setRoleSearchScope

void setRoleSearchScope(int scope)

Sets the role search scope as specified by javax.naming.directory.SearchControls.

Parameters:

scope - the role search scope.

getRoleSearchPattern

String getRoleSearchPattern()

Gets the message format used to select roles for a user, with "{0}" marking the spot where the distinguished name of the user goes, and/or "{1}" marking the spot for the username of the principal.

Returns:

the role search pattern.

setRoleSearchPattern

void setRoleSearchPattern(String pattern)

Sets the message format used to select roles for a user, with "{0}" marking the spot where the distinguished name of the user goes, and/or "{1}" marking the spot for the username of the principal.

Parameters:

pattern - the new role search pattern.

getPasswordAttribute

String getPasswordAttribute()

Gets the password attribute used to retrieve the user password.

Returns:

the password attribute.

setPasswordAttribute

void setPasswordAttribute(String name)

Sets the password attribute used to retrieve the user password.

Parameters:

name - the password attribute

getRoleNameAttribute

String getRoleNameAttribute()

Gets the role name attribute used to retrieve user roles from the result of the role search.

Returns:

the role name attribute.

setRoleNameAttribute

void setRoleNameAttribute(String name)

Sets the role name attribute used to retrieve user roles from the result of the role search.

Parameters:

name - the role name attribute.

getUserRoleNameAttribute

String getUserRoleNameAttribute()

Gets the user role name attribute used to retrieve user roles from the result of of user search.

Returns:

the user role name attribute.

setUserRoleNameAttribute

void setUserRoleNameAttribute(String name)

Sets the user role name attribute used to retrieve user roles from the result of of user search.

Parameters:

name - the user role name attribute.

getDefaultLocaleAttribute

String getDefaultLocaleAttribute()

Gets the default locale attribute used to retrieve user locale from the result of of user search.

Returns:

the default locale attribute.

setDefaultLocaleAttribute

void setDefaultLocaleAttribute(String name)

Sets the default locale attribute used to retrieve user locale from the result of of user search.

Parameters:

name - the deafult locale attribute.

getAttributes

Attributes getAttributes(String name)
                         throws NamingException

Gets all attributes associated with the named directory object.

Parameters:

name - the name of the object.

Returns:

the found attributes.

Throws:

IllegalStateException - if not started.

NamingException - if a naming exception is encountered.

search

List search(String name,
            String filter,
            int scope)
            throws NamingException

Searches in the named context or object for entries that satisfy the given search filter and within the given scope. The scope is given as specfied by javax.naming.directory.SearchControls. A list of javax.naming.directory.SearchResult objects is returned as the result.

Parameters:

name - the name of context or object.

filter - the search filter.

scope - the scope of the search.

Returns:

the list of found entries.

Throws:

IllegalStateException - if not started.

NamingException - if a naming exception is encountered.

lookup

DirContext lookup()
                  throws NamingException

Returns a new connection to the directory that can be accessed concurrently. The caller is responsible for closing it.

Returns:

the connection as a directory context.

Throws:

NamingException - if a naming exception is encountered.