com.cafesoft.cams.auth.login.module
Class AESOX509CertLdapLoginModule

java.lang.Object
  com.cafesoft.cams.auth.login.module.AESOX509CertLdapLoginModule

All Implemented Interfaces:

LoggerClient, LoginModule

public class AESOX509CertLdapLoginModule
extends Object
implements LoginModule, LoggerClient

AESOX509CertLdapLoginModule is a JAAS LoginModule used with Cams "Automatic Enterprise Sign-On" (AESO) and LDAP v3 compliant directory servers.

This LoginModule is designed to trust a user identity authenticated at the web layer via X.509 client certificate authentication and use information available within the certificate to:

1. confirm the user exists by performing an LDAP query
2. optionally assign more role principals used for Cams role based access control (RBAC).

This LoginModule attempts to bind to an administrator account DN, then perform an LDAP query for an LDAP entry corresponding to user-specific DN obtained from the X.509 certificate callback value.

Role assignment is accomplished by use of an LDAP role filter, which queries Groups to which the user is assigned and maps them directly to roles.

• debug - Enable/disable debugging [true|false].
• host - The DNS name or IP address of the LDAP host.
• port - The host's LDAP service port.
• useSSL - Enables/disables use of SSL.
• connectTimeout - (Optional) The number of milliseconds to wait for a connection to the LDAP server before timing out. For example: 3000
• bindUsername - The username or DN for an LDAP account with permissions to query for user and group information.
• bindPassword - The password for the "bindUsername" account.
• agentSecret - The expected value for the "agent_secret" callback value, which must be present in the authentication request. This value is used to authenticated Cams agents, which assert the identity of a user already authenticated at the web layer. The agent secret is used to protect against impersonation attacks via carefully created HTTP requests attempting to subvert AESO component trust relationships.
• cbValueNS - The namespace used to reference callback values in other configuration options. For example, if cbValueNS is "cb", then the value of a callback of name "email_addr" is referenced as: {cb:email_addr}
• cbValuesRequired - A comma-separated list of callback values that must be present in the authentication request before login will be attempted. This list should name all callback values that are referenced by other configuration options, plus the agent_secret and the x509_client_cert callback values.
• userResultsNS - The namespace used to reference attribute values returned from the user LDAP search in other configuration options. For example, the userResultsNS is "user" and the "uid" LDAP attribute is returned with the user LDAP search results, then the "uid" value can be referenced in another configuration option using: {user:uid}
• userBaseDN - The distinguished name at which to start a user search. This value should be the LDAP node closes to where user data is stored. For example: ou=people,dc=example,dc=com
• userAttrNames - The LDAP attribute names to be returned on user searches. If the user LDAP entry is found, the values of these attributes are made available for substitution in other configuration options, usually the "userSubjectName" and "roleFilter".
• userCertAttr - The name of the LDAP attribute where the user's X.509 certificate is store. The standard name is "userCertificate" and contains the DER-encoded (binary) certificate data.
• userFilter - The LDAP filter used to search for the user LDAP entry and associated attributes. This filter will generally reference a callback value that was created at the web layer by an AESO-enabled web agent and obtained from the X.509 client certificate presented by the user. For example, a user filter value of (mail={cb:email_addr}) indicates that the user should be selected based on LDAP attribute "mail" with the value matching the callback value named "email_addr".
• userScope - Specifies the LDAP search scope to use for user searches. Valid values are BASE (search is done only at the base DN specified by userBaseDN), ONE (search is done only at the first child tree node relative to userBaseDN), and SUB (search is done at userBaseDN and all child nodes).
• useRoleSearch - If "true", then use the LDAP role search to assign user roles (on successful login). If "false", then don't perform the role search.
• roleBaseDN - The base distinguished name to use for your LDAP schema role searches. For example: ou=groups,dc=example,dc=com
• roleAttrName - The name of the attribute used to store the role names (usually one name is used but can be a comma-delimited list). For example: cn
• roleFilter - The filter to use for role searches. This value generally needs to reference one or more callback values or values returned from the user LDAP search. For example: (uniqueMember=uid={user:uid},ou=people,dc=example,dc=com)
• roleScope - The LDAP search scope to use for role searches. Valid values are BASE (search is done only at the base DN specified by roleBaseDN), ONE (search is done only at the first child tree node relative to roleBaseDN), and SUB (search is done at roleBaseDN and all child nodes).
• defaultRoles - (Optional) A list of one or more default roles separated by a comma to be added to the user session.

Since:

12/31/2008

See Also:

Subject, CallbackHandler, LoginModule

Constructor Summary

AESOX509CertLdapLoginModule()
Default AESOX509CertLdapLoginModule Constructor.

Method Summary

boolean	abort() Method to abort the authentication process (phase 2).
boolean	commit() Method to commit the authentication process (phase 2).
void	initialize(Subject subject, CallbackHandler callbackHandler, Map sharedState, Map options) Initialize this LoginModule.
boolean	login() Method to authenticate a Subject (phase 1).
boolean	logout() Method which logs out a Subject.
void	setLogger(Logger logger) Sets the logger.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AESOX509CertLdapLoginModule

public AESOX509CertLdapLoginModule()

Default AESOX509CertLdapLoginModule Constructor.

Method Detail

setLogger

public void setLogger(Logger logger)

Sets the logger.

Specified by:

setLogger in interface LoggerClient

Parameters:

logger - logs messages

initialize

public void initialize(Subject subject,
                       CallbackHandler callbackHandler,
                       Map sharedState,
                       Map options)

Initialize this LoginModule.

This method is called by the LoginContext after this LoginModule has been instantiated. The purpose of this method is to initialize this LoginModule with the relevant information. If this LoginModule does not understand any of the data stored in sharedState or options parameters, they can be ignored.

Specified by:

initialize in interface LoginModule

Parameters:

subject - the Subject to be authenticated.

callbackHandler - a CallbackHandler for accessing callback values (e.g. certChain).

sharedState - state shared with other configured LoginModules.

options - options specified in the login Configuration for this particular LoginModule.

login

public boolean login()
              throws LoginException

Method to authenticate a Subject (phase 1).

Specified by:

login in interface LoginModule

Returns:

true if the authentication succeeded, or false if this LoginModule should be ignored.

Throws:

LoginException - if the authentication fails

commit

public boolean commit()
               throws LoginException

Method to commit the authentication process (phase 2).

This method is called if the LoginContext's overall authentication succeeded (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules succeeded).

If this LoginModule's own authentication attempt succeeded (checked by retrieving the private state saved by the login method), then this method associates relevant Principals and Credentials with the Subject located in the LoginModule. If this LoginModule's own authentication attempted failed, then this method removes/destroys any state that was originally saved.

Specified by:

commit in interface LoginModule

Returns:

true if this method succeeded, or false if this LoginModule should be ignored.

Throws:

LoginException - if the commit fails

abort

public boolean abort()
              throws LoginException

Method to abort the authentication process (phase 2).

This method is called if the LoginContext's overall authentication failed. (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules did not succeed).

If this LoginModule's own authentication attempt succeeded (checked by retrieving the private state saved by the login method), then this method cleans up any state that was originally saved.

Specified by:

abort in interface LoginModule

Returns:

true if this method succeeded, or false if this LoginModule should be ignored.

Throws:

LoginException - if the abort fails

logout

public boolean logout()
               throws LoginException

Method which logs out a Subject.

An implementation of this method might remove/destroy a Subject's Principals and Credentials.

Specified by:

logout in interface LoginModule

Returns:

true if this method succeeded, or false if this LoginModule should be ignored.

Throws:

LoginException - if the logout fails