diff options
Diffstat (limited to 'qpid/doc/book/src/Add-New-Users.xml')
| -rw-r--r-- | qpid/doc/book/src/Add-New-Users.xml | 237 |
1 files changed, 237 insertions, 0 deletions
diff --git a/qpid/doc/book/src/Add-New-Users.xml b/qpid/doc/book/src/Add-New-Users.xml new file mode 100644 index 0000000000..dc34bcc5c9 --- /dev/null +++ b/qpid/doc/book/src/Add-New-Users.xml @@ -0,0 +1,237 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + 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><title> + Add New Users + </title><para> + The Qpid Java Broker has a single reference source (<xref linkend="qpid_PrincipalDatabase"/>) that + defines all the users in the system. + </para><para> + To add a new user to the broker the password file must be + updated. The details about adding entries and when these updates + take effect are dependent on the file format each of which are + described below. + </para> + + <section role="h2" id="AddNewUsers-AvailablePasswordfileformats"><title> + Available + Password file formats + </title> + <para> + There are currently two different file formats available for use + depending on the PrincipalDatabase that is desired. In all cases + the clients need not be aware of the type of PrincipalDatabase in + use they only need support the SASL mechanisms they provide. + </para><itemizedlist> + <listitem><para> + <xref linkend="AddNewUsers-Plain"/> + </para></listitem> + <listitem><para> + <xref linkend="AddNewUsers-Base64MD5PasswordFileFormat"/> + </para></listitem> + </itemizedlist><para> + + </para> + + <section role="h3" id="AddNewUsers-Plain"><title> + Plain + </title> + <para> + The plain file has the following format: + </para> + <programlisting> +# Plain password authentication file. +# default name : passwd +# Format <username>:<password> +#e.g. +martin:password +</programlisting> + <para> + As the contents of the file are plain text and the password is + taken to be everything to the right of the ':'(colon). The + password, therefore, cannot contain a ':' colon, but this can be + used to delimit the password. + </para><para> + Lines starting with a '#' are treated as comments. + </para> +<!--h3--></section> + + <section role="h3" id="AddNewUsers-Whereisthepasswordfileformybroker-3F"><title> + Where is + the password file for my broker ? + </title> + <para> + The location of the password file in use for your broker is as + configured in your config.xml file. + </para> + <programlisting> +<principal-databases> + <principal-database> + <name>passwordfile</name> + <class>org.apache.qpid.server.security.auth.database.PlainPasswordFilePrincipalDatabase</class> + <attributes> + <attribute> + <name>passwordFile</name> + <value>${conf}/passwd</value> + </attribute> + </attributes> + </principal-database> + </principal-databases> +</programlisting> + <para> + So in the example config.xml file this password file lives in the + directory specified as the conf directory (at the top of your + config.xml file). + </para><para> + If you wish to use Base64 encoding for your password file, then + in the <class> element above you should specify + org.apache.qpid.server.security.auth.database.Base64MD5PasswordFilePrincipalDatabase + </para><para> + The default is: + </para> + <programlisting> + <conf>${prefix}/etc</conf> +</programlisting> +<!--h3--></section> + + + <section role="h3" id="AddNewUsers-Base64MD5PasswordFileFormat"><title> + Base64MD5 + Password File Format + </title> + <para> + This format can be used to ensure that SAs cannot read the plain + text password values from your password file on disk. + </para><para> + The Base64MD5 file uses the following format: + </para> + <programlisting> +# Base64MD5 password authentication file +# default name : qpid.passwd +# Format <username>:<Base64 Encoded MD5 hash of the users password> +#e.g. +martin:X03MO1qnZdYdgyfeuILPmQ== +</programlisting> + <para> + As with the Plain format the line is delimited by a ':'(colon). + The password field contains the MD5 Hash of the users password + encoded in Base64. + </para><para> + This file is read on broker start-up and is not re-read. + </para> +<!--h3--></section> + + <section role="h3" id="AddNewUsers-HowcanIupdateaBase64MD5passwordfile-3F"><title> + How can + I update a Base64MD5 password file ? + </title> + <para> + To update the file there are two options: + </para><orderedlist> + <listitem><para>Edit the file by hand using the <emphasis>qpid-passwd</emphasis> tool + that will generate the required lines. The output from the tool + is the text that needs to be copied in to your active password + file. This tool is located in the broker bin directory. + Eventually it is planned for this tool to emulate the + functionality of <xref linkend="qpid_htpasswd"/> + for qpid passwd files. + <emphasis>NOTE:</emphasis> For the changes to be seen by the broker you must + either restart the broker or reload the data with the + management tools (see <xref linkend="Qpid-JMX-Management-Console-User-Guide"/>) + </para></listitem> + <listitem><para>Use the management tools to create a new user. The changes + will be made by the broker to the password file and the new user + will be immediately available to the system (see <xref linkend="Qpid-JMX-Management-Console-User-Guide"/>). + </para></listitem> + </orderedlist> +<!--h3--></section> +<!--h2--></section> + + + <section role="h2" id="AddNewUsers-Dynamicchangestopasswordfiles."><title> + Dynamic + changes to password files. + </title> + <para> + The Plain password file and the Base64MD5 format file are both + only read once on start up. + </para><para> + To make changes dynamically there are two options, both require + administrator access via the Management Console (see <xref linkend="Qpid-JMX-Management-Console-User-Guide"/>) + </para><orderedlist> + <listitem><para>You can replace the file and use the console to reload its + contents. + </para></listitem> + <listitem><para>The management console provides an interface to create, + delete and amend the users. These changes are written back to the + active password file. + </para></listitem> + </orderedlist> +<!--h2--></section> + + <section role="h2" id="AddNewUsers-HowpasswordfilesandPrincipalDatabasesrelatetoauthenticationmechanisms"><title> + How password files and PrincipalDatabases relate to + authentication mechanisms + </title> + <para> + For each type of password file a PrincipalDatabase exists that + parses the contents. These PrincipalDatabases load various SASL + mechanism based on their supportability. e.g. the Base64MD5 file + format can't support Plain authentication as the plain password + is not available. Any client connecting need only be concerned + about the SASL module they support and not the type of + PrincipalDatabase. So I client that understands CRAM-MD5 will + work correctly with a Plain and Base64MD5 PrincipalDatabase. + </para><table> + <title>File Format and Principal Database</title><tgroup cols="2"> + <tbody> + <row> + <entry> + FileFormat/PrincipalDatabase + </entry> + <entry> + SASL + </entry> + </row> + <row> + <entry> + Plain + </entry> + <entry> + AMQPLAIN PLAIN CRAM-MD5 + </entry> + </row> + <row> + <entry> + Base64MD5 + </entry> + <entry> + CRAM-MD5 CRAM-MD5-HASHED + </entry> + </row> + </tbody> + </tgroup></table><para> + For details of SASL support see <xref linkend="qpid_Qpid-Interoperability-Documentation"/> + </para> +<!--h2--></section> + +</section> |