| <?xml version="1.0"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |
| <document> |
| |
| <properties> |
| <title>Apache James Server 3 - Users Configuration</title> |
| </properties> |
| |
| <body> |
| |
| <section name="Users Repositories"> |
| |
| <subsection name="Introduction"> |
| |
| <p>User repositories are required to store James user information and authentication data</p> |
| |
| <p>Consult <a href="https://github.com/apache/james-project/tree/master/server/apps/spring-app/src/main/resources/usersrepository.xml">usersrepository.xml</a> in GIT to get some examples and hints.</p> |
| |
| <p> |
| A user has two attributes: username and password. A valid user should satisfy these criteria: |
| </p> |
| <ul> |
| <li>username and password cannot be null or empty</li> |
| <li>username should not be longer than 255 characters</li> |
| <li>username can not contain '/'</li> |
| <li>username can not contain multiple domain delimiter('@')</li> |
| <li>A username can have only a local part when virtualHosting is disabled. E.g.'myUser'</li> |
| <li> |
| 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' |
| </li> |
| </ul> |
| <p> |
| 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. |
| </p> |
| </subsection> |
| |
| <subsection name="General configuration"> |
| |
| <p>All Users Repositories provide at least these three options</p> |
| |
| <dl> |
| <dt><strong>enableVirtualHosting</strong></dt> |
| <dd>true or false. Add domain support for users (default: false, except for Cassandra Users Repository)</dd> |
| <dt><strong>administratorId</strong></dt> |
| <dd>user's name. Allow a user to access to the <a href="https://tools.ietf.org/html/rfc4616#section-2">impersonation command</a>, acting on the behalf of any user.</dd> |
| <dt><strong>administratorIds</strong></dt> |
| <dd>List of usernames. Allows multiple administrators to access the <a href="https://tools.ietf.org/html/rfc4616#section-2">impersonation command</a>, acting on behalf of any user by specifying multiple |
| <code><administratorId></code> entries inside the <code><administratorIds></code> block. Prefer ref:imap.adoc[imapserver.xml] `auth.adminUsers` property to not enable admin impersonation onto publicly exposed interfaces. </dd> |
| <dd><em>Note:</em> Only one of the above <code><administratorId></code> property or this <code><administratorIds></code> block should be used to specify the administrator(s).</dd> |
| <dt><strong>verifyFailureDelay</strong></dt> |
| <dd>2, 2s, 2000ms, default 0s (disabled). Delay after a failed authentication attempt with an invalid user name or password.</dd> |
| </dl> |
| |
| </subsection> |
| |
| <subsection name="JPA Users Repository"> |
| |
| <p>JPA (database via OpenJPA) based user repository. This is the default implementation.</p> |
| |
| <p>The usersrepository tag as 2 attributes: name="LocalUsers" and class="org.apache.james.user.file.UsersFileRepository"> |
| The class tag should be specified for Spring, but is not taken into acount by Guice.</p> |
| |
| |
| <dl> |
| <dt><strong>algorithm</strong></dt> |
| <dd>Algorithm to hash passwords. Supported password algorithm are: MD5, SHA-256, SHA-512, NONE(then SHA-1 will be used), `PBKDF2`, `PBKDF2-SHA512` (default).<br/> |
| <b>Note</b>: 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.</dd> |
| <dd>MD5 and SHA-1 are deprecated.</dd> |
| <dt><strong>enableVirtualHosting</strong></dt> |
| <dd>true (default) or false. Defines if the usernames must (true) or may not contain (false) a domain part (user@domain.tld).</dd> |
| </dl> |
| |
| </subsection> |
| |
| <subsection name="LDAP Users Repository"> |
| |
| <p>Read-Only LDAP based UsersRepository</p> |
| |
| <p>Example:</p> |
| |
| <source> |
| <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> |
| </source> |
| |
| |
| <p>SSL can be enabled by using <code>ldaps</code> scheme. <code>trustAllCerts</code> option can be used to trust all LDAP client certificates |
| (optional, defaults to false).</p> |
| |
| <p>Example:</p> |
| |
| <source> |
| <repository 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></source> |
| |
| <p>Moreover, per domain base DN can be configured:</p> |
| |
| <source> |
| <repository 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> |
| <domains> |
| <domain.tld>ou=People,o=other.com,ou=system</domain.tld> |
| </domains> |
| </usersrepository></source> |
| |
| <p>You can connect to multiple LDAP servers for better availability by using <code>ldapHosts</code> option |
| (fallback to <code>ldapHost</code> is supported) to specify the list of LDAP Server URL with the comma <code>,</code> delimiter. |
| We do support different schemas for LDAP servers.</p> |
| |
| <p>Example:</p> |
| |
| <source> |
| <usersrepository name="LocalUsers" class="org.apache.james.user.ldap.ReadOnlyUsersLDAPRepository" ldapHosts="ldap://ldapServer1:389,ldaps://ldapServer2:636" |
| principal="uid=ldapUser,ou=system" credentials="password" userBase="ou=People,o=myorg.com,ou=system" userIdAttribute="uid" trustAllCerts="true"> |
| <enableVirtualHosting>true</enableVirtualHosting> |
| </usersrepository> |
| </source> |
| |
| <p>When VirtualHosting is on, you can enable local part as login username by configure the <code>resolveLocalPartAttribute</code>. |
| This is the LDAP attribute that allows to retrieve the local part of users. Optional, default to empty, which disables login with local part as username.</p> |
| |
| <p>Example:</p> |
| |
| <source> |
| <usersrepository name="LocalUsers" class="org.apache.james.user.ldap.ReadOnlyUsersLDAPRepository" ldapHosts="ldap://ldapServer1:389,ldaps://ldapServer2:636" |
| principal="uid=ldapUser,ou=system" credentials="password" userBase="ou=People,o=myorg.com,ou=system" resolveLocalPartAttribute="uid" userIdAttribute="mail" trustAllCerts="true"> |
| <enableVirtualHosting>true</enableVirtualHosting> |
| </usersrepository> |
| </source> |
| |
| <p>The "userListBase" configuration option is used to differentiate users that can login from those that are listed |
| as regular users. This is useful for dis-activating users, for instance.</p> |
| |
| <p>A different values from "userBase" can be used for setting up virtual logins, |
| for instance in conjunction with "resolveLocalPartAttribute". This can also be used to manage |
| disactivated users (in userListBased but not in userBase).</p> |
| |
| <p>Note that "userListBase" can not be specified on a per-domain-basis.</p> |
| |
| <p><b>LDAP connection pool size tuning</b></p> |
| |
| <p>Apache James offers some options for configuring the LDAP connection pool used by unboundid: |
| <ul> |
| <li> <b>poolSize</b>: (optional, default = 4) The maximum number of connection in the pool. Note that if the pool is exhausted, |
| extra connections will be created on the fly as needed.</li> |
| <li> <b>maxWaitTime</b>: (optional, default = 1000) the number of milli seconds to wait before creating off-pool connections, |
| using a pool connection if released in time. This effectively smooth out traffic burst, thus in some case can help |
| not overloading the LDAP</li> |
| <li> <b>connectionTimeout:</b> (optional) Sets the connection timeout on the underlying to the specified integer value</li> |
| <li> <b>readTimeout:</b> (optional) Sets property the read timeout to the specified integer value.</li> |
| </ul></p> |
| </subsection> |
| |
| </section> |
| |
| </body> |
| |
| </document> |
