From 15d69563d7bf419ccc0535cd691b4520229f918b Mon Sep 17 00:00:00 2001
From: Brant Knudson <bknudson@us.ibm.com>
Date: Sun, 15 Sep 2013 19:16:34 -0500
Subject: [PATCH] Add Groups to Identity

This adds documentation for the Groups feature introduced in
Grizzly (Identity API v3).

Change-Id: If59a12b7c790cbe00b8c81c73e16bbe8e061f580
Closes-bug: #1090655
---
 doc/common/section_keystone-concepts.xml | 48 ++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/doc/common/section_keystone-concepts.xml b/doc/common/section_keystone-concepts.xml
index 6f149fc39f..3fe0f330dd 100644
--- a/doc/common/section_keystone-concepts.xml
+++ b/doc/common/section_keystone-concepts.xml
@@ -370,4 +370,52 @@
         <para>The commands for creating services and endpoints are
             described in a later section.</para>
     </section>
+
+    <section xml:id="identity-groups">
+        <title>Groups</title>
+        <para>
+A group is a collection of users.
+Administrators can create groups and add users to them.
+Then, rather than assign a role to each user individually,
+assign a role to the group.
+        </para>
+        <para>
+Every group is in a domain. Groups were introduced with version 3 of the
+Identity API (the Grizzly release of Keystone).
+        </para>
+        <para>
+Identity API V3 provides the following group-related operations:
+        </para>
+        <itemizedlist>
+            <listitem><para>Create a group</para></listitem>
+            <listitem><para>Delete a group</para></listitem>
+            <listitem><para>Update a group (change its name or description)</para></listitem>
+            <listitem><para>Add a user to a group</para></listitem>
+            <listitem><para>Remove a user from a group</para></listitem>
+            <listitem><para>List group members</para></listitem>
+            <listitem><para>List groups for a user</para></listitem>
+            <listitem><para>Assign a role on a tenant to a group</para></listitem>
+            <listitem><para>Assign a role on a domain to a group</para></listitem>
+            <listitem><para>Query role assignments to groups</para></listitem>
+        </itemizedlist>
+        <note>
+            <para>
+Not all of these operations may be allowed by the Identity server.
+For example, if using the Keystone server with the LDAP Identity backend and
+group updates are disabled, then a request to create, delete, or update a group
+will fail.
+            </para>
+        </note>
+        <para>
+Here's a couple examples:
+        </para><para>
+Group A is granted Role A on Tenant A. If User A is a member of Group A,
+then when User A gets a token scoped to Tenant A then the token will also
+include Role A.
+        </para><para>
+Group B is granted Role B on Domain B. If User B is a member of Domain B,
+then if User B gets a token scoped to Domain B then the token will also
+include Role B.
+        </para>
+    </section>
 </section>