| <?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. |
| |
| --> |
| |
| <section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="Java-Broker-Security-Group-Providers"> |
| <title>Group Providers</title> |
| <para> |
| The Apache Qpid Broker-J utilises GroupProviders to allow assigning users to groups for use in <link linkend="Java-Broker-Security-AccessControlProviders">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> |
| |
| <section role="h3" xml: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" xml:id="File-Group-Manager-FileFormat"> |
| <title>File Format</title> |
| <para> |
| The groups file has the following format: |
| </para> |
| <programlisting> |
| # <GroupName>.users = <comma delimited user list> |
| # 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 role="h3" xml:id="Java-Broker-Security-Group-Providers-ManagedGroupProvider"> |
| <title>ManagedGroupProvider</title> |
| <para> |
| The <emphasis>ManagedGroupProvider</emphasis> allows specifying group membership as part of broker configuration. |
| In future version of Brokers GroupFile Provider will be replaced by this one. |
| </para> |
| </section> |
| |
| <section role="h3" xml:id="Java-Broker-Security-Group-Providers-CloudFoundry"> |
| <title>CloudFoundryDashboardManagementGroupProvider</title> |
| <para> |
| The <emphasis>CloudFoundryDashboardManagementGroupProvider</emphasis> |
| allows mapping of service instance ids to qpid management groups. |
| </para> |
| <para> |
| One use case is restricting management capabilities of a OAuth2 authenticated user to certain virtual |
| hosts. For this, one would associate a cloudfoundry service id with each virtual host and have an ACL with a |
| separate management group for each virtual host. Given the correct service instance id to |
| management group mapping the GroupProvider will then associate the user with each management group the user |
| is provisioned to manage the associated service instance in the <link |
| xmlns:xlink="http://www.w3.org/1999/xlink" |
| xlink:href="http://docs.cloudfoundry.org/services/dashboard-sso.html#checking-user-permissions">CloudFoundry dashboard</link>. |
| </para> |
| </section> |
| </section> |