Repository: zookeeper Updated Branches: refs/heads/master 5fe68506f -> cf4f11951
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 <[email protected]> Reviewers: Abraham Fine <[email protected]>, 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 Project: http://git-wip-us.apache.org/repos/asf/zookeeper/repo Commit: http://git-wip-us.apache.org/repos/asf/zookeeper/commit/cf4f1195 Tree: http://git-wip-us.apache.org/repos/asf/zookeeper/tree/cf4f1195 Diff: http://git-wip-us.apache.org/repos/asf/zookeeper/diff/cf4f1195 Branch: refs/heads/master Commit: cf4f119516ca3d232fe077477c7a91b2e5825de2 Parents: 5fe6850 Author: Josh Elser <[email protected]> Authored: Wed Mar 8 17:48:41 2017 -0800 Committer: Michael Han <[email protected]> Committed: Wed Mar 8 17:48:41 2017 -0800 ---------------------------------------------------------------------- .../content/xdocs/zookeeperProgrammers.xml | 26 ++++++++++++++------ 1 file changed, 18 insertions(+), 8 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/zookeeper/blob/cf4f1195/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 c208079..27f2124 100644 --- a/src/docs/src/documentation/content/xdocs/zookeeperProgrammers.xml +++ b/src/docs/src/documentation/content/xdocs/zookeeperProgrammers.xml @@ -831,11 +831,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 @@ -899,9 +902,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
