The purpose of the LPPE module is to detect a number scenarios that would otherwise prevent user authentication, specifically using an Ldap instance as the primary source of user accounts. To understand the general overview and intent of the LPPE functionality, please review this page.
This document serves to highlight and explain the architectural changes that are proposed for upcoming CAS 4 release. In additional to various bug and security fixes, the following goals and improvements are planned:
Change in Package Structure
All LPPE functionally is proposed to be contained inside the new package: org/jasig/cas/adaptors/ldap/lppe as much as possible. There may be overlap in some areas, but the effort is concentrated on keeping the changeset in one subpack of the ldap integration module.
Support for Retrieval of Custom Ldap Authentication Attributes
TODO
Support for Non-Expiring ActiveDirectory Accounts
Current version of LPPE in CAS 3.5.x contains a bug in calculating the expiration date for AD accounts that are flagged to never expire. The correct approach would be to look up the bitwise value in the userAccountControl attribute of the AD container to detect account state. This fix can be accommodated through support for retrieval of custom attributes as descrfibed above.
The bitwise flags are define as such:
private enum ActiveDirectoryUserAccountControlFlags {
UAC_FLAG_ACCOUNT_DISABLED(2),
UAC_FLAG_LOCKOUT(16),
UAC_FLAG_PASSWD_NOTREQD(32),
UAC_FLAG_DONT_EXPIRE_PASSWD(65536),
UAC_FLAG_PASSWORD_EXPIRED(8388608);
private int value;
ActiveDirectoryUserAccountControlFlags(final int id) {
this.value = id;
}
public final int getValue() {
return this.value;
}
}
Support for Custom WebFlow States
TODO
Internalization of Ldap Error Codes Pre-Authentication
LPPE attempts to intercept authentication errors by detecting a set of ldap error codes. By translating the error codes into a webflow state, LPPE is then able to redirect the user the page appropriate and relevant for the issue experienced. Currently, these error codes are visibly defined in the configuration and are somewhat easily accessible by the deployer:
<property name="ldapErrorDefinitions">
<list>
<bean class="org.jasig.cas.adaptors.ldap.LdapErrorDefinition"
p:ldapPattern="data 530"
p:type="badHours" />
<bean class="org.jasig.cas.adaptors.ldap.LdapErrorDefinition"
p:ldapPattern="data 533"
p:type="accountDisabled" />
<bean class="org.jasig.cas.adaptors.ldap.LdapErrorDefinition"
p:ldapPattern="data 773"
p:type="mustChangePassword" />
<bean class="org.jasig.cas.adaptors.ldap.LdapErrorDefinition"
p:ldapPattern="data 775"
p:type="accountLocked" />
<bean class="org.jasig.cas.adaptors.ldap.LdapErrorDefinition"
p:ldapPattern="data 531"
p:type="badWorkstation" />
<bean class="org.jasig.cas.adaptors.ldap.LdapErrorDefinition"
p:ldapPattern="data (701|532)"
p:type="passwordExpired" />
</list>
</property>
A better way perhaps to handle the abstraction of ldap error codes, which was also suggested previously by developers, would be to internalize the above errors whose type is indicated by the name of the object. The following is proposed in place of the configuration:
<property name="ldapErrorDefinitions">
<list>
<bean class="org.jasig.cas.adaptors.ldap.lppe.AccountDisabledLdapErrorDefinition" />
<bean class="org.jasig.cas.adaptors.ldap.lppe.AccountLockedLdapErrorDefinition" />
<bean class="org.jasig.cas.adaptors.ldap.lppe.InvalidLoginHoursLdapErrorDefinition" />
<bean class="org.jasig.cas.adaptors.ldap.lppe.InvalidLoginWorkstationLdapErrorDefinition" />
<bean class="org.jasig.cas.adaptors.ldap.lppe.AccountMustChangePasswordLdapErrorDefinition" />
<bean class="org.jasig.cas.adaptors.ldap.lppe.AccountPasswordExpiredLdapErrorDefinition" />
</list>
</property>
Ldap error definitions are optional. If none is found, authentication is prevented and the appropriate exception is thrown back. As such, deployers may choose to only pick definitions that are relevant to their environment and configuration.
It's important to note that these error codes may prevent authentication. Examination of a successfully-authenticated ldap account for state, password expiration and other conditions needs to occur AFTER the authentication once the credential is established and constructed.
The above approach is completely extensible and exposes hooks for other implementations of the LdapErrorDefinition, should a use case arise. The changeset is provided and facilitated by having support for retrieval of custom attributes.
Support for Account Examiners Post-Authentication
To detect and calculate the account expiration warning, the account state needs to be examined after a successful authentication. Based on LPPE configuration, the account state through retrieval of custom attributes is examined and appropriate prompts and alterations in the flow may occur.
This changeset proposes an extensiable API for examining account state post authentication. By default the implementation exposes an instance of LdapPasswordExpirationPolicyExaminer that calculates password expiration warning. Other implementation that need to evaluate the account from other aspects may also be provided.
<property name="ldapPasswordPolicyExaminers">
<list>
<bean class="org.jasig.cas.adaptors.ldap.lppe.LdapPasswordExpirationPolicyExaminer">
<property name="ignorePasswordExpirationWarningFlags" value="${ldap.authentication.lppe.noWarnValues}" />
<property name="alwaysDisplayPasswordExpirationWarning" value="${ldap.authentication.lppe.warnAll}" />
<property name="ldapDateConverter">
<bean class="org.jasig.cas.adaptors.ldap.lppe.ActiveDirectoryLdapDateConverter" />
</property>
</bean>
</list>
</property>
The above approach is completely extensible and exposes hooks for other implementations of the LdapPasswordPolicyExaminer, should a use case arise. The changeset is provided and facilitated by having support for retrieval of custom attributes. Examiners are also optional and may or may not be used in conjunction with detection of ldap error codes during authentication.
Support for Custom Date Formatters
To calculate the password expiration warning based on a given LDAP attribute date (specified in the lppe configuration), this changeset proposes various implementations of the LdapDateConverter interface. This interface provides for not only configuring the given timezone used in date calculation, but defines the general contract between LPPE and the following implementations:
ActiveDirectoryLdapDateConverter used specifically with ActiveDirectory ldap instances, feature the ability to convert a special AD date value into its equivalent java.util.Date object.
- SimpleDateFormatLdapDateConverter expects the received date value form LDAP to be consistent with a given DateTimeFormatter's pattern.
- TimeUnitLdapDateConverter expects the received ldap date value to be defined in milliseconds. It will convert the value to the time unit specified. The final date is initialized from a given date (or epoch).
Reduce Ldap Query Overhead
TODO
Component Diagram
TODO
Flow Diagram
TODO