This administrator guide covers installation, configuration, and deployment of WebPasswordSafe into your environment.
Edit /webpasswordsafe/war/WEB-INF/encryption.properties changing values specific to your encryption environment. You absolutely should change the encryptor.jasypt.password value to a new random value as this is your secret encryption key/passphrase. It is also important it is protected properly and not changed after initial deployment, doing so will render your data unreadable.
Edit /webpasswordsafe/war/WEB-INF/jdbc.properties changing values specific to your database environment. Commonly you'll need to change jdbc.username and jdbc.password, as well as uncomment (remove # at beginning of line) the hibernate.dialect, jdbc.driverClassName, jdbc.url, jdbc.validationQuery lines that relate to your database server vendor and delete the others. Finally change the jdbc.url value to point to your database server.
Edit /webpasswordsafe/war/WEB-INF/webpasswordsafe-service.xml to customize the plugins to fit your environment via standard Spring Framework configuration XML format. In all cases you will want to set the appropriate bean definition to the implementation you want (and either deleting or commenting out all other unused implementations) and also set any other custom parameters for that implementation as needed. See Developer Guide for how to write and integrate your own implementation of these plugins.
This plugin is configured using the bean id="auditLogger" tag and can point to any class that implements the AuditLogger interface.
The DatabaseAuditLogger class implementation doesn't have any custom parameters to configure, it simply records all audit events into the audit_log table of the WebPasswordSafe database.
The Log4jAuditLogger class implementation has one parameter "delimiter" which is the text used to separate the different audit event fields when writing to a log. This plugin will send all audit events to a log4j implementation category for that class. From there log4j can be configured (see log4j.xml section) to write those logs to a file, console, syslog, or any other output log4j supports.
The CompositeAuditLogger class implementation allows for the logging to multiple AuditLogger implementations at the same time. It has one property "auditLoggers" that can take a list of references to other beans that implement AuditLogger. By default it sends to both DatabaseAuditLogger and Log4jAuditLogger.
This plugin is configured using the bean id="authenticator" tag and can point to any class that implements the Authenticator interface. Note that these plugins will only successfully authenticate users that have already been added to the WebPasswordSafe application. If authenticating with an external source, make sure the usernames match. In many cases multiple authenticators can be chained together to achieve additional functionality, details are below.
The LocalAuthenticator class implementation is the default and authenticates users against the password setup internally for them inside of the WebPasswordSafe application.
The LdapAuthenticator class implementation allows you to authenticate users against an LDAP server. It takes multiple parameters and depends on other beans. Most often you must change the "filter" parameter based on how to find people in your LDAP schema (the $1 token will get replaced by the username of user trying to authenticate, so that is important) and the "base" parameter is the base DN for your LDAP tree. Furthermore, you must configure the authnContextSource bean, setting the "url" parameter to the URL of your LDAP server, the "userDn" parameter to the DN of the user that can bind to the LDAP server, and the "password" parameter to the password of that user that can bind to the LDAP server.
The DemoAuthenticator class implementation is used mostly just for testing or demonstration purposes. When used it hardcodes the password of all users to be the same value (configured by setting the "demoPassword" parameter) that cannot be changed.
The CompositeAuthenticator class implementation allows for using multiple Authenticator implementations for different sets of users. It takes a list of maps that represent "authenticators". Each map entry in the list must have an entry key "authenticator" that references another Authenticator bean. Each map entry must also have either an entry key "users" and/or "anyUser". The "users" entry itself contains a list of string values, one value tag for each username that should be authenticated using this plugin entry. The "anyUser" entry contains a boolean value "true"/"false" that if true will attempt to authenticate any user. The plugins are attempted in the order they are listed. The example contained in the default configuration shows that the admin user gets authenticated with the localAuthenticator implementation, while all other users get authenticated with the ldapAuthenticator implementation.
The RsaSecurIdAuthenticator class implementation is an optional Authenticator implementation (see Developer Guide) that authenticates against an RSA SecurID server for multi-factor authentication. Since RSA SecurID has its own configuration file for setup, this plugin simply has on parameter "configPath" that contains the full directory and file path to the rsa_api.properties file that defines that setup.
The UserLockoutAuthenticator class implementation is used by default to chain another Authenticator implementation adding extra functionality to it. It this case, it will disable a user after a given number of consecutive failed login attempts from the chained authenticator. The "authenticator" parameter must be set to reference another valid configured Authenticator bean instance it will chain with. The "failedLoginThreshold" parameter is set to an integer, the number of consecutive failed authenticator attempts at which the user will get disabled. Finally the "whitelist" entry contains a list of string values, one value tag for each username that can be whitelisted and bypass ever getting disabled by this plugin. Typically you'll want at least one administrator role user to be whitelisted, so they can always login and enable other users who've been disabled, however best practice is to not use the default "admin" user for this, use a non-obvious username which makes a denial of service attack less likely.
The IPLockoutAuthenticator class implementation is used by default to chain another Authenticator implementation adding extra functionality to it. It this case, it will block an IP address after a given number of consecutive failed login attempts from the chained authenticator. The "authenticator" parameter must be set to reference another valid configured Authenticator bean instance it will chain with. The "failedLoginThreshold" parameter is set to an integer, the number of consecutive failed authenticator attempts at which the IP address will be blocked. The "lockoutLength" parameter is set to an integer, the number of minutes that an IP address should be blocked to prevent or slow down brute-force attacks of multiple users from the same IP address. Finally the "whitelist" entry contains a list of string values, one value tag for each IP address that can be whitelisted and bypass ever getting blocked by this plugin, you may want to set this to an internal IP address you know will never be used to stage an attack.
This plugin is configured using the bean id="roleRetriever" tag and can point to any class that implements the RoleRetriever interface.
The LocalRoleRetriever class implementation is the default which allows the defining of an "adminUsers" property that is a set of usernames (each username with its own value tag) that are given the ADMIN role. It is inferred all users get the USER role.
This plugin is configured using the bean id="authorizer" tag and can point to any class that implements the Authorizer interface.
The DefaultAuthorizer class implementation is the default which allows the defining of an "allowAdminBypassPasswordPermissions" property that is either true or false, depending if you want to allow users with ADMIN role to bypass password permissions. All permissions are hardcoded inside the plugin code using RBAC, functionality is authorized based on whether the user's role is of ADMIN or USER.
This plugin is configured using the bean id="passwordGenerator" tag and can point to any class that implements the PasswordGenerator interface.
The SimpleRandomPasswordGenerator class implementation allows for the changing of some basic parameters. Change "passwordLength" value to length of passwords it should generate, "allowLowercase"/"allowUppercase"/"allowNumeric" to either "true"/"false" based on whether to include those types of characters in the generated password, "specialChars" to a string which contains any other characters not included in the above sets in the generated password (i.e. "!@#$%^*()"), and "excludeChars" to a string which contains any characters to exclude from the above sets in the generated password (useful for "look-a-like" characters like O/0 and l/1").
This plugin is configured using the bean id="digester" tag and can point to any class that implements the Digester interface and handles one-way encryption of authentication passwords.
The JasyptDigester class implementation is the default using the Jasypt encryption library and is configured using the encryption.properties file.
The EsapiDigester class implementation is an optional implementation (see Developer Guide) using the OWASP-ESAPI encryption library and is configured using the encryption.properties and its own configuration files.
This plugin is configured using the bean id="encryptor" tag and can point to any class that implements the Encryptor interface and handles two-way encryption of password data.
The JasyptEncryptor class implementation is the default using the Jasypt encryption library and is configured using the encryption.properties file.
The EsapiEncryptor class implementation is an optional implementation (see Developer Guide) using the OWASP-ESAPI encryption library and is configured using the encryption.properties and its own configuration files.
Edit /webpasswordsafe/src/main/resources/log4j.xml changing values to suit your environment.
If using the Log4jAuditLogger, you will want to pay special attention to the appenders defined to the Log4jAuditLogger category, by default using the auditLog appender, but can also use the auditSyslog appender to send logs to Syslog. You may want to customize the "File" parameter to point the file to a different directory path or filename. For Syslog you will want to change the "SyslogHost" and "Facility" parameters specific to the IP/Host and Facility of your Syslog server.
Besides audit logging, this log4j configuration file also handles debug logging of the WebPasswordSafe application itself. You can change the "File" parameter of the "dailyFile" appender to point the debug log file to a different directory path or filename. To make the logs more verbose, helpful when trying to debug problems, you can change the various "priority" values from "info" or "error" to "debug" or "trace" instead. For further customization options please see log4j's own documentation.
Edit /webpasswordsafe/src/main/webapp/WEB-INF/web.xml changing the "session-timeout" parameter to be an integer value representing the number of minutes a server session can be idle before it timeouts and requires the user to re-authenticate. The default is 10 minutes.