cloudstack/docs/en-US/password-storage-engine.xml

<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
%BOOK_ENTITIES;
]>

<!-- 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.
-->
<section id="password-storage-engine">
  <title>Changing the Default Password Encryption</title>
  <para>Passwords are encoded when creating or updating users. &PRODUCT; allows you to determine the
    default encoding and authentication mechanism for admin and user logins. Two new configurable
    lists have been introduced&mdash;userPasswordEncoders and userAuthenticators.
    userPasswordEncoders allows you to configure the order of preference for encoding passwords,
    whereas userAuthenticators allows you to configure the order in which authentication schemes are
    invoked to validate user passwords. </para>
  <para>Additionally, the plain text user authenticator has been modified not to convert supplied
    passwords to their md5 sums before checking them with the database entries. It performs a simple
    string comparison between retrieved and supplied login passwords instead of comparing the
    retrieved md5 hash of the stored password against the supplied md5 hash of the password because
    clients no longer hash the password. The following method determines what encoding scheme is
    used to encode the password supplied during user creation or modification. </para>
  <para>When a new user is created, the user password is encoded by using the first valid encoder
    loaded as per the sequence specified in the <code>UserPasswordEncoders</code> property in the
      <filename>ComponentContext.xml</filename> or <filename>nonossComponentContext.xml</filename>
    files. The order of authentication schemes is determined by the <code>UserAuthenticators</code>
    property in the same files. If Non-OSS components, such as VMware environments, are to be
    deployed, modify the <code>UserPasswordEncoders</code> and <code>UserAuthenticators</code> lists
    in the <filename>nonossComponentContext.xml</filename> file, for OSS environments, such as
    XenServer or KVM, modify the <filename>ComponentContext.xml</filename> file. It is recommended
    to make uniform changes across both the files. When a new authenticator or encoder is added, you
    can add them to this list. While doing so, ensure that the new authenticator or encoder is
    specified as a bean in both these files. The administrator can change the ordering of both these
    properties as preferred to change the order of schemes. Modify the following list properties
    available in <filename>client/tomcatconf/nonossComponentContext.xml.in</filename> or
      <filename>client/tomcatconf/componentContext.xml.in</filename> as applicable, to the desired
    order:</para>
  <programlisting>&lt;property name="UserAuthenticators"&gt;
         &lt;list&gt;
            &lt;ref bean="SHA256SaltedUserAuthenticator"/&gt;
            &lt;ref bean="MD5UserAuthenticator"/&gt;
            &lt;ref bean="LDAPUserAuthenticator"/&gt;
            &lt;ref bean="PlainTextUserAuthenticator"/&gt;
        &lt;/list&gt;
    &lt;/property&gt;
    &lt;property name="UserPasswordEncoders"&gt;
        &lt;list&gt;
            &lt;ref bean="SHA256SaltedUserAuthenticator"/&gt;
             &lt;ref bean="MD5UserAuthenticator"/&gt;
             &lt;ref bean="LDAPUserAuthenticator"/&gt;
            &lt;ref bean="PlainTextUserAuthenticator"/&gt;
            &lt;/list&gt;</programlisting>
  <para>In the above default ordering, SHA256Salt is used first for
      <code>UserPasswordEncoders</code>. If the module is found and encoding returns a valid value,
    the encoded password is stored in the user table's password column. If it fails for any reason,
    the MD5UserAuthenticator will be tried next, and the order continues. For
      <code>UserAuthenticators</code>, SHA256Salt authentication is tried first. If it succeeds, the
    user is logged into the Management server. If it fails, md5 is tried next, and attempts
    continues until any of them succeeds and the user logs in . If none of them works, the user is
    returned an invalid credential message. </para>
</section>