Authentication
Digest
Cascade is equipped to handle three types of user authentication:
- Normal authentication (default) - default mode where authentication is handled natively by Cascade
- LDAP authentication - Cascade delegates authentication to an external LDAP server (e.g. Active Directory, OpenLDAP)
- Custom (3rd-party) authentication - Cascade provides an authentication API to allow developers to hook into third-party authentication/single sign-on systems (e.g. Kerberos, Shibboleth, CAS)
Technical
Normal (Built-in) Authentication
With normal authentication, users enter the usernames and passwords on the login screen and Cascade authenticates them against their encrypted credentials stored in the Cascade database.
User accounts must be created for each user before they can access the system. This is accomplished from Administration > Users, Groups, and Roles section (manually) or can be done programmatically via the Web Services API.
It is also possible to import users' usernames, emails, full names, and group/role memberships from an LDAP server but use Cascade's built-in facilities to authenticate the users.
LDAP Authentication
Users can also be set to authenticate against an existing LDAP server like Active Directory or Open LDAP. Using LDAP, allows users and passwords to be centrally managed and then synced to Cascade.
The system still requires users records in the database for each user so that their preferences, Group and Role memberships can be maintained. However, only the DN (Distinguished Name) of the user and not the password are stored in the Casdcade database.
When the user attempts to login, the supplied username is used to retrieve the DN of the user. Then, Cascade attempts to bind to the LDAP server using the DN and the supplied password. The user is authenticated if the bind is successful.
Here is more information on setting up LDAP authentication in Cascade.
Custom User Authentication
Cascade exposes an authentication API to allow developers to hook into 3rd-party authentication and single sign-on frameworks. The API provides a hooks into the authentication life cycle. Developers will be able to redirect the browser to custom login and logout screens.
Plug-in DevelopmentCascade 6.7+ users, download the custom authentication API.
For older versions of Cascade:
Cascade 6.4.x JAR
Cascade 6.2.x JAR
Cascade 6.0.x JAR
All custom authentication modules must implement the interface: com.hannonhill.cascade.model.security.authentication.Authenticator
This interface defines two main methods:
and
The redirect() method is called by the Cascade authentication framework based on what phase of the authentication life cycle is active. The AuthenticationPhase is an enum with two values: LOGIN and LOGOUT.
For the LOGIN phase, Cascade first instantiates the custom authentication module and calls redirect with the LOGIN authentication phase parameter. At this point, the module will redirect to an external webapp to perform the authentication, at which point the authentication web application should redirect the browser back to Authenticator.AUTHENTICATION_URI.
NOTE: In the Cascade 4.x series, AUTHENTICATION_URI will be /cms/customauth. In the Cascade 5.x series, this should be changed to /customauth (unless the application is purposely deployed to /cms).
Cascade will then invoke the module once more and call authenticate(). The module at that point should know whether or not the user was successfully authenticated, and should everything go well, the module should return the username of the successfully authenticated user. At this point, Cascade establishes a user session for the authenticated user and the user is considered to be logged in to Cascade.
The other phase, LOGOUT, is called when the logout link is clicked and after Cascade invalidates the user session. The typical behavior here is for the custom authentication module to redirect the browser back to the external authentication web application.
It is important to remember to not store state in the authentication module using instance members. Each call on the authentication module is made after a fresh instantiation, and as such, data stored as instance members will be lost in between invocations.
The authentication module code is typically bundled into a JAR file and placed in the $tomcat_home/webapps/ROOT/WEB-INF/lib directory. After bouncing the app server, the custom classes should be available.
A configuration file must be created to tell Cascade how to load the custom plug-in:
To use the configuration click Tools -> System -> Configuration ->Custom Authentication Configuration, then paste the contents of the configuration file when prompted.