The default behaviour of the application is to use password based authentication with login passwords stored (encrypted and salted) within the person database table. This is implemented by a Composite. Users self-register with the application and the users Email address is verified as part of the sign-up process. This is chosen as the default mechanism because it is the most flexible, anybody with an email account and a web-browser is capable of using this configuration. However the application can also be configured to use different authentication mechanisms, depending on your requirements:
This is the default configuration. Password based authentication is supported if the person table contains a composite registered under the PasswordAuthComposite type. The default is to register a DatabasePasswordComposite that stores an encrypted and salted password in database fields of the person table. The following parameters allow fine-tuning of the password configuration.
Property password.salt_length length of password salt used.
Property password.hash password hash algorithm. This should be one of MD5,SHA1,SHA256,SHA384,SHA512. Provided the Alg field exists in the person table (to store the hash algorithm used when the password was set) you can change this parameter without breaking existing entries. You may however have to change the length of the password field in the database.
Property hash-name.allowed Set this to true/false so enable/disable the use of a particular password algorithm. The default algorithm is always allowed. If a non-default algorithm is allowed users whose password were stored using that algorithm will still be able to login using their old password. They will be updated to the new default the next time they change their password.
Property max_password_fails number of consecutive password fails before the account is locked and the user has to change their password.
Property notify_password_fails number of consecutive password fails before failed attempts are logged as errors.
Property service.feature.password.check_complexity enable complexity checking of user supplied passwords.
password.min_length minimum password length (not counting repeated letters or letters consecutive in the alphabet)
password.min_diff_char minimum number of different characters that should occur within the password this should give better password entropy than requiring characters from particular sets like digits because all characters are treated equally.
password.min_digits minimum number of digits needed in a password.
password.min_special minimum number of non alpha-numeric characters needed in a password.
If all of your users already have existing web-credentials (for example a campus/federated Single-Sign-On system) you may want to configure the application to use this external authentication system instead of internal passwords. These changes should ideally be performed when setting up the system for the first time rather than being applied to an existing application instance.
Configure apache level authentication to use the existing web-credentials. This is usually done using a Location statement within the apache configuration. The exact syntax depends on the version of httpd and the SSO system you are using. It is not necessary to protect every application URL (In fact you probably want different authentication for URLs accessed via scripts. The minimum set of URLs to protect are:
/login.jsp
/RegisterServlet
/ (Not strictly required but this is the default URL that users will usually visit first)
Edit the person.composites property to remove the DatabasePasswordComposite and replace it with AppUserNameFinder.WebName. If you are making this change to an existing database that was originally created for password based authentication, you will also have to use the table edit forms to drop the Password related database fields and add the WebName field. You will also have to edit any existing users (With the Developer role active) to set the WebName field to the REMOTE_USER string for that user.
Set the property service.feature.allow_external_auth=on. With this feature enabled the application will try to match any REMOTE_USER identity generated by Apache to WebName values in the person table and automatically log-in if a match is found.
The default behaviour is if the REMOTE_USER name does not correspond to the WebName field for any existing database record then the user will be presented with a sign-up form and a record will be created for them. If you don't want users to self-register the first time they visit the application you will have to set service.feature.allow_signup=off in which case you will have to manually create each user (using the Create person form or an automated data upload) before they can log-in to the application.
It is also possible to install a custom AppUserNameFinder that can query some external directory (such as a LDAP server) and automatically create the record based on information from the directory. However (at the time of writing) there is not a generic configurable plug-in that does this only custom solutions for particular cases. If you require this get in touch with the application developers.
You can also use an external SSO system as a secondary login system in addition to a password mechanism. Every application user will still have a password as in the default configuration but (if they have an identity in the SSO system) they have the option of binding this identity to their application account and using this as an alternative login mechanism. You don't need to know users identities in advance to do this because the SSO identities are captured when the user links their identity to the application.
Configure apache level authentication to use the existing web-credentials. Pick a top-level URL the application to protect that is specific to this for example /Campus-sso
Edit the application web.xml file to bind a RemoteAuthServlet to this location.
<servlet>
<description>Allows access from campus logins</description>
<servlet-name>SSOServlet</servlet-name>
<servlet-class>uk.ac.ed.epcc.webapp.servlet.RemoteAuthServlet</servlet-class>
</servlet>
<servlet>
<servlet-mapping>
<servlet-name>SSOServlet</servlet-name>
<url-pattern>/Campus-sso</url-pattern>
</servlet-mapping>
Add AppUserNameFinder.WebName to the person.composites list. If you are adding this to an existing application you will also have to create the WebName database field in the person table via the table admin forms.
Set property service.feature.web_login=on
Set property service.web_login.url=/Campus-sso
Set property service.web_login.login-text=Login using Campus SSO. This is the text that appears on the login page form.
Set property service.web_login.update-text=Register Campus SSO identity. This is the text that appears on the form where users can link their identities to the application.
If you need a choice of secondary methods you can configure more than one RemoteAuthServlet instances to handle different authentication mechanisms. Each mechanism corresponds do a different naming “realm”.
The service.web_login configuration parameters become comma separated lists of values one for each mechanism.
The additional servlets needs to be configured with an init-parameter remote_auth.realm to change the realm from the default WebName realm.
Additional composites need to be added to implement the new realms e.g.
Define the property class.Realm2=FieldnameFinder and add the composite Realm2 to person.composites. The REMOTE_USER value for this realm will be stored in field Realm2 in the person table.
If you need a third realm use SecondaryNameFinder rather than FieldNameFinder. This works exactly the same as the FieldNameFinder but registers under a different type allowing it to co-exist with the FieldNameFinder and the default WebNameFinder.
It is also possible to perform password authentication directly against an LDAP server rather than storing the passwords in the internal database. This is done using a custom PasswordAuthComposite that verifies the users password against an external LDAP (and creates the corresponding database entry if one does not already exist). However (at the time of writing) there is not a generic configurable plug-in that does this only custom solutions for particular cases. If you require this get in touch with the application developers.