doc/book/src/java-broker/Java-Broker-Security-Group-Providers.xml

<?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 id="Java-Broker-Security-Group-Providers">
  <title>Group Providers</title>
  <para>
    The Java broker utilises GroupProviders to allow assigning users to groups for use in <link linkend="Java-Broker-Security-ACLs">ACLs</link>.
    Following authentication by a given <link linkend="Java-Broker-Security-Authentication-Providers">Authentication Provider</link>,
    the configured Group Providers are consulted allowing the assignment of GroupPrincipals for a given authenticated user. Any number of
    Group Providers can be added into the Broker. All of them will be checked for the presence of the groups for a given authenticated user.
  </para>
  <para>The <emphasis>Group Provider</emphasis> can be configured using <link linkend="Java-Broker-Configuring-And-Managing-REST-API">
  REST Management interfaces</link> and <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link>.</para>
  <para>The following <emphasis>Group Provider</emphasis> managing operations are available from Web Management Console:
    <itemizedlist>
        <listitem><para>A new Group Provider can be added by clicking onto "Add Group Provider" button on a Broker tab.</para></listitem>
        <listitem><para>An existing providers can be removed by pressing "Delete Group Provider" button
         on Broker tab or Group Provider tab.</para></listitem>
        <listitem><para>On clicking onto provider name in the Group Providers grid or Broker object tree,
         the tab for the Group Provider is displayed.</para></listitem>
        <listitem><para>A new group can be added into the Group Provider by clicking onto "Add Group" button on provider tab.</para></listitem>
        <listitem><para>An existing group can be deleted from the Group Provider by clicking onto "Delete Group" button on provider tab.</para></listitem>
        <listitem><para>On clicking onto group name in the groups grid, the tab with the list of existing
        group members is displayed for the Group.</para></listitem>
        <listitem><para>From the Group tab a new member can be added into a group or existing members can be deleted
        from a group by clicking on "Add Group Member" or "Remove Group Members" accordingly.</para></listitem>
     </itemizedlist>
   </para>

  <section role="h3" id="File-Group-Manager">
    <title>GroupFile Provider</title>
    <para>
      The <emphasis>GroupFile</emphasis> Provider allows specifying group membership in a flat file on disk.
      On adding a new GroupFile Provider the path to the groups file is required to be specified.
      If file does not exist an empty file is created automatically. On deletion of GroupFile Provider
      the groups file is deleted as well. Only one instance of "GroupFile" Provider per groups file location can be created.
      On attempt to create another GroupFile Provider pointing to the same location the error will be displayed and
      the creation will be aborted.
    </para>

    <section role="h4" id="File-Group-Manager-FileFormat">
       <title>File Format</title>
      <para>
            The groups file has the following format:
          </para>
            <programlisting>
    # &lt;GroupName&gt;.users = &lt;comma deliminated user list&gt;
    # For example:

    administrators.users = admin,manager
</programlisting>
          <para>
            Only users can be added to a group currently, not other groups. Usernames can't contain commas.
          </para><para>
            Lines starting with a '#' are treated as comments when opening the file, but these are not preserved when the broker updates the file due to changes made through the management interface.
          </para>
     </section>
  </section>
</section>