Repository: zookeeper
Updated Branches:
refs/heads/branch-3.5 b2d66fa3d -> 4a3ef8b65
ZOOKEEPER-2709: Clarify documentation around the "auth" ACL scheme
Not sure if I should include the modified files from the result of `ant docs`. Happy to do
so if expected :)
Author: Josh Elser <elserj@apache.org>
Reviewers: Abraham Fine <afine@apache.org>, Michael Han <hanm@apacheorg>
Closes #182 from joshelser/ZOOKEEPER-2709 and squashes the following commits:
4d7b712 [Josh Elser] ZOOKEEPER-2709 Correct usage of "id" and "expression"
057cb18 [Josh Elser] ZOOKEEPER-2709 Clarify documentation around the "auth" ACL scheme
(cherry picked from commit cf4f119516ca3d232fe077477c7a91b2e5825de2)
Signed-off-by: Michael Han <hanm@apache.org>
Project: http://git-wip-us.apache.org/repos/asf/zookeeper/repo
Commit: http://git-wip-us.apache.org/repos/asf/zookeeper/commit/4a3ef8b6
Tree: http://git-wip-us.apache.org/repos/asf/zookeeper/tree/4a3ef8b6
Diff: http://git-wip-us.apache.org/repos/asf/zookeeper/diff/4a3ef8b6
Branch: refs/heads/branch-3.5
Commit: 4a3ef8b65e4b93667db4860e856a54a7372b403e
Parents: b2d66fa
Author: Josh Elser <elserj@apache.org>
Authored: Wed Mar 8 17:48:41 2017 -0800
Committer: Michael Han <hanm@apache.org>
Committed: Wed Mar 8 17:48:51 2017 -0800
----------------------------------------------------------------------
.../content/xdocs/zookeeperProgrammers.xml | 26 ++++++++++++++------
1 file changed, 18 insertions(+), 8 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/zookeeper/blob/4a3ef8b6/src/docs/src/documentation/content/xdocs/zookeeperProgrammers.xml
----------------------------------------------------------------------
diff --git a/src/docs/src/documentation/content/xdocs/zookeeperProgrammers.xml b/src/docs/src/documentation/content/xdocs/zookeeperProgrammers.xml
index b4477bf..8710362 100644
--- a/src/docs/src/documentation/content/xdocs/zookeeperProgrammers.xml
+++ b/src/docs/src/documentation/content/xdocs/zookeeperProgrammers.xml
@@ -820,11 +820,14 @@
recursive.</para>
<para>ZooKeeper supports pluggable authentication schemes. Ids are
- specified using the form <emphasis>scheme:id</emphasis>,
- where <emphasis>scheme</emphasis> is a the authentication scheme
- that the id corresponds to. For
- example, <emphasis>ip:172.16.16.1</emphasis> is an id for a
- host with the address <emphasis>172.16.16.1</emphasis>.</para>
+ specified using the form <emphasis>scheme:expression</emphasis>,
+ where <emphasis>scheme</emphasis> is the authentication scheme
+ that the id corresponds to. The set of valid expressions are defined
+ by the scheme. For example, <emphasis>ip:172.16.16.1</emphasis> is
+ an id for a host with the address <emphasis>172.16.16.1</emphasis>
+ using the <emphasis>ip</emphasis> scheme, whereas <emphasis>digest:bob:password</emphasis>
+ is an id for the user with the name of <emphasis>bob</emphasis> using
+ the <emphasis>digest</emphasis> scheme.</para>
<para>When a client connects to ZooKeeper and authenticates
itself, ZooKeeper associates all the ids that correspond to a
@@ -888,9 +891,16 @@
single id, <emphasis>anyone</emphasis>, that represents
anyone.</para></listitem>
- <listitem><para><emphasis role="bold">auth</emphasis> doesn't
- use any id, represents any authenticated
- user.</para></listitem>
+ <listitem><para><emphasis role="bold">auth</emphasis> is
a special
+ scheme which ignores any provided expression and instead uses the current user,
+ credentials, and scheme. Any expression (whether <emphasis>user</emphasis>
like with SASL
+ authentication or <emphasis>user:password</emphasis> like with DIGEST
authentication) provided is ignored
+ by the ZooKeeper server when persisting the ACL. However, the expression must still
be
+ provided in the ACL because the ACL must match the form <emphasis>scheme:expression:perms</emphasis>.
+ This scheme is provided as a convenience as it is a common use-case for
+ a user to create a znode and then restrict access to that znode to only that user.
+ If there is no authenticated user, setting an ACL with the auth scheme will fail.
+ </para></listitem>
<listitem><para><emphasis role="bold">digest</emphasis> uses
a <emphasis>username:password</emphasis> string to generate
|