= Distributed James Server &mdash; usersrepository.xml
:navtitle: usersrepository.xml

User repositories are required to store James user information and authentication data.

Consult this link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/usersrepository.xml[example]
to get some examples and hints.

== The user data model

A user has two attributes: username and password.

A valid user should satisfy these criteria:

* username and password cannot be null or empty
* username should not be longer than 255 characters
* username can not contain '/'
* username can not contain multiple domain delimiter('@')
* A username can have only a local part when virtualHosting is disabled. E.g.'myUser'
* When virtualHosting is enabled, a username should have a domain part, and the domain part should be concatenated
after a domain delimiter('@'). E.g. 'myuser@james.org'

A user is always considered as lower cased, so 'myUser' and 'myuser' are the same user, and can be used as well as
recipient local part than as login for different protocols.

== Configuration

.usersrepository.xml content
|===
| Property name | explanation

| enableVirtualHosting
| true or false. Add domain support for users (default: false, except for Cassandra Users Repository)

| administratorId
|user's name. Allow a user to access to the https://tools.ietf.org/html/rfc4616#section-2[impersonation command],
acting on the behalf of any user.

| verifyFailureDelay
| Delay after a failed authentication attempt with an invalid user name or password. Duration string defaulting to seconds, e.g. `2`, `2s`, `2000ms`. Default `0s` (disabled).

| algorithm
| use a specific hash algorithm to compute passwords, with optional mode `plain` (default) or `salted`; e.g. `SHA-512`,  `SHA-512/plain`, `SHA-512/salted`, `PBKDF2`, `PBKDF2-SHA512` (default).
Note: When using `PBKDF2` or `PBKDF2-SHA512` one can specify the iteration count and the key size in bytes. You can specify it as part of the algorithm. EG: `PBKDF2-SHA512-2000-512` will use
2000 iterations with a key size of 512 bytes.

| hashingMode
| specify the hashing mode to use if there is none recorded in the database: `plain` (default) for newer installations or `legacy` for older ones

|===

== Configuring a LDAP

Alternatively you can authenticate your users against a LDAP server. You need to configure
the properties for accessing your LDAP server in this file.

Consult this link:https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/usersrepository.xml[example]
to get some examples and hints.

Example:

....
<usersrepository name="LocalUsers" class="org.apache.james.user.ldap.ReadOnlyUsersLDAPRepository" ldapHost="ldap://myldapserver:389"
    principal="uid=ldapUser,ou=system" credentials="password" userBase="ou=People,o=myorg.com,ou=system" userIdAttribute="uid">
    <enableVirtualHosting>true</enableVirtualHosting>
</usersrepository>
....

SSL can be enabled by using `ldaps` scheme. `trustAllCerts` option can be used to trust all LDAP client certificates
(optional, defaults to false).

Example:

....
<usersrepository name="LocalUsers" class="org.apache.james.user.ldap.ReadOnlyUsersLDAPRepository" ldapHost="ldaps://myldapserver:636"
    principal="uid=ldapUser,ou=system" credentials="password" userBase="ou=People,o=myorg.com,ou=system" userIdAttribute="uid"
    trustAllCerts="true">
    <enableVirtualHosting>true</enableVirtualHosting>
</usersrepository>
....

Moreover, per domain base DN can be configured:

....
<usersrepository name="LocalUsers" class="org.apache.james.user.ldap.ReadOnlyUsersLDAPRepository" ldapHost="ldap://myldapserver:389"
    principal="uid=ldapUser,ou=system" credentials="password" userBase="ou=People,o=myorg.com,ou=system" userIdAttribute="uid"
    <enableVirtualHosting>true</enableVirtualHosting>
    <domains>
        <domain.tld>ou=People,o=other.com,ou=system</domain.tld>
    </domains>
</usersrepository>
....
