# Services.Properties Configuration

Quick Index

Many new security features were introduced in XNAT 1.6, but since not all XNAT installations have the same security needs, these features were made very customizable. The services.properties file in plugin-resources/conf/ contains many security options that XNAT administrators can configure. If you want to force users to change their passwords every 2 weeks and make them choose passwords that have at least 10 characters and contain multiple digits and special characters, you just make a couple changes to the configuration file. If instead you want users to be able to use whatever passwords they want for as long as they want, that's also a simple change. Once you modify the services.properties file, you must restart Tomcat for the changes to take effect.

As of XNAT 1.6, there is the option of locking users out of their accounts after a certain number of incorrect login attempts. By default this option is turned off, but it can be enabled by changing the value of security.max_failed_logins in services.properties from -1 (which disables the feature), to some positive integer. The number you choose will be the number of times that someone can attempt to access an account with bad credentials before the account is temporarily locked. Multiple incorrect login attempts in a short period of time is a sign that a malicious user is trying to access the account, so setting this to a low number can make the accounts more secure. However, if the permissible number of incorrect login attempts is set too low, then people who take multiple tries to remember their password will frequently be locked out. Once locked out, a user must wait until the end of the lockout period to log in again. By default, this period is 24 hours. So by default, at the end of every 24 hour period the incorrect login attempt counts are reset and anyone who was locked out will be able to log in. This period is also configurable by modifying the value of security.max_failed_logins_lockout_duration in services.properties. This is in milliseconds, so if you wanted to change the lockout period to one hour, you would set it to 3600000.

### Inactivity Before Lockout

If a user has not accessed their account in a long time, you can make it so that their account is automatically disabled. If that user then wants to resume using their account, an administrator can re-enable that user's account through the Users page in the website. By default, accounts are locked out after being inactive for 1 year, but this is configurable by changing security.inactivity_before_lockout in services.properties. This is in seconds, so should be set to 31556926 to lockout users after one year of inactivity or 63113852 to lock them out after two years.

### Alias Token Timeout

Alias tokens are used in a number of places through XNAT 1.6x. You can set the time limit for alias token expiration by setting. For example: security.token_timeout=2 days sets the expiration time to 2 days.

Starting in XNAT 1.6, there is an option to require passwords to adhere to certain complexity requirements. If someone tries to change their password or create a new user account, the password they enter must meet these requirements. Otherwise, the password will not be changed or the user account will not be created. Instead, the user will receive a message informing them of what the password requirements are and would then be able to chose a new password.

The complexity requirements can be configured in the services.properties file. For security.password_complexity, enter the Java regular expression that new passwords should match. By default, this is set to "^.*$" (without the quotes), which means that any password is acceptable. If you want to require users to have more complex passwords, simply change the value of this regular expression. For example, if you changed the regular expression to "^.*(?=.{8,})(?=.*[a-z])(?=.*[A-Z])(?=.*[0-9]).*$", passwords would be required to be at least 8 characters long, and have at least one digit, one uppercase character, and one lowercase character. If you change the security.password_complexity regular expression, you should also change security.password_complexity_message in services.properties so that the message corresponds to your new complexity requirements. For example, you could change this to "Password must be at least 8 characters long, and have at least one digit, one uppercase character, and one lowercase character.", if you were to change the complexity field to the above regular expression.

Beginning with XNAT 1.6, there is an option to expire passwords if users have not changed them for a long time. When a user's password expires, the user will be prompted to change their password the next time they log in and will be unable to use the site until they do so. By default, passwords expire every 365 days, but this can be configured in the services.properties file. To configure how long it takes passwords to expire, you can change the value of security.password_expiration. You can change the value to "-1" to disable the feature so that passwords never expire, or you can enter your own time interval using PostgreSQL interval notation (http://www.postgresql.org/docs/9.0/static/functions-datetime.html).

In some scenarios it may be important to set the time period that must elapse before a password can be used again. By default XNAT 1.6x sets this to 365 days or 1 year.

### Max Concurrent Sessions

XNAT 1.6x allows concurrent session by the same user. You can set the max number of these allowed by adjusting the value in the services.properties file. For example: security.sessions.concurrent_max=1000 sets the max of number of sessions allowed by one user to 1000

### Authentication

#### Local Database

By default, users can log into XNAT only using credentials that are stored in a local database (which is initialized with "admin" and "guest" user accounts).  You'll see the following configuration in services.properties:

provider.providers.enabled=db
provider.db.name=Database
provider.db.id=localdb
provider.db.type=db

#### LDAP

This configuration has changed slightly as of 1.6; 1.5 and older configurations (such as those referenced here) will not work with 1.6.

In particular, if you are copying the search filter over from your 1.5 authentication.properties, replace

%USER% (a homebrewed syntax used by XNAT 1.5)

with

{0} (Spring Security syntax)

You can also configure XNAT to also support LDAP authentication.  It's known to work with ActiveDirectory and OpenLDAP; other LDAP implementations have not been tested but should work too.

To authenticate against an LDAP server, or multiple servers, you can add these servers to services.properties. Users will then be able to log in using their LDAP credentials and will not have to remember a new username and password.  To enable LDAP authentication, you must provide some information about the LDAP server you want to use.  An LDAP properties template is included in services.properties (look for provider.ldap1.*).  Fill in this template appropriately.  Here's an example:

provider.ldap1.name=LDAP
provider.ldap1.id=ldap1
provider.ldap1.type=ldap
provider.ldap1.userdn=cn=MyServiceAccount,ou=MyGroup,dc=my,dc=domain
provider.ldap1.search.base=ou=people
provider.ldap1.search.filter=(uid={0})

These values would be used if you wanted the provider to access an LDAP server with URL ldap://ldapurl:389/dc=my,dc=domain.  Authentication would be performed by attempting to bind with the DN uid=<user-login-name>,ou=people,dc=my,dc=domain.

provider.ldap1.name is what you want your users to see. On the login page, there is a dropdown from which users select the provider they want to use. If you want the database provider to be listed as "XNAT" instead of "Database", simply set

provider.db.name=XNAT

provider.ldap1.id uniquely identifies the provider in case there are multiple providers of a given type. If you add a second ldap provider, it should have a different ID ("ldap2" is fine).

provider.ldap1.type indicates what type of provider it is. The two types that are currently supported are db and ldap.

provider.ldap1.userdn/provider.ldap1.password are credentials for the LDAP account that you're connecting with to perform the authentication.  Typically this is a service account, not an actual person's account.

provider.ldap1.search.filter is the LDAP field that contains the user's login name.  This may be different depending on your LDAP implementation.

An Active Directory implementation will need something like the following:

provider.ldap1.search.filter=(sAMAccountName={0})

With OpenLDAP it might be more like this:

provider.ldap1.search.filter=(uid={0})

Now that the template is complete, add the ldap1 provider to the provider list:

provider.providers.enabled=db, ldap1

Restart Tomcat and the LDAP authentication should be enabled (you'll see a dropdown list on the home page).

If you have a need for multiple LDAP servers, just set

provider.providers.enabled=db, ldap1, ldap2

and then create a new set of properties for ldap2.

### Require Justifications

When an authorized user attempts to delete or change a project, session, subject, or experiment a justification "note" can be required from that user by adjusting the value of this property. This is particularly useful for assembling audit trails.

audit.require_change_justification=false

audit.show_change_justification=false

This would disable the feature all together

audit.require_change_justification=false

audit.show_change_justification=true

This would allow justifications but wouldn't require them

audit.require_change_justification=true

audit.show_change_justification=true

This would require justifications