From aaf802f321dc6782dd80f2aa91e2ccd0b4d5abc3 Mon Sep 17 00:00:00 2001 From: Xiang Li Date: Tue, 23 Jun 2015 11:08:04 -0700 Subject: [PATCH] doc: update auth_api.md --- Documentation/auth_api.md | 86 ++++++++++++++++++++------------------- 1 file changed, 44 insertions(+), 42 deletions(-) diff --git a/Documentation/auth_api.md b/Documentation/auth_api.md index 8e8728cab50..d95f8669941 100644 --- a/Documentation/auth_api.md +++ b/Documentation/auth_api.md @@ -44,7 +44,7 @@ We only support [Basic Auth](http://en.wikipedia.org/wiki/Basic_access_authentic ### Authorization field for operations Added to requests to /v2/keys, /v2/auth -Add code 403 Forbidden to the set of responses from the v2 API +Add code 401 Unauthorized to the set of responses from the v2 API Authorization: Basic {encoded string} ### Future Work @@ -89,6 +89,7 @@ PUT /v2/auth/enable Possible Status Codes: 200 OK 400 Bad Request (if root user has not been created) + 409 Conflict (already enabled) 200 Body: (empty) **Disable auth** @@ -99,7 +100,8 @@ DELETE /v2/auth/enable Authorization: Basic Possible Status Codes: 200 OK - 403 Forbidden (if not a root user) + 401 Unauthorized (if not a root user) + 409 Conflict (already disabled) 200 Body: (empty) @@ -130,7 +132,7 @@ GET/HEAD /v2/auth/user Authorization: Basic Possible Status Codes: 200 OK - 403 Forbidden + 401 Unauthorized 200 Headers: Content-type: application/json 200 Body: @@ -146,7 +148,7 @@ GET/HEAD /v2/auth/users/alice Authorization: Basic Possible Status Codes: 200 OK - 403 Forbidden + 401 Unauthorized 404 Not Found 200 Headers: Content-type: application/json @@ -170,9 +172,14 @@ PUT /v2/auth/users/charlie * Grant/Revoke/Password filled in when updating (to grant roles, revoke roles, or change the password). Possible Status Codes: 200 OK - 403 Forbidden + 201 Created + 400 Bad Request + 401 Unauthorized 409 Conflict (when granting duplicated roles or revoking non-existing roles) - 200 Body: (empty) + 200 Headers: + Content-type: application/json + 200 Body: + JSON state of the user **Remove A User** @@ -182,7 +189,8 @@ DELETE /v2/auth/users/charlie Authorization: Basic Possible Status Codes: 200 OK - 403 Forbidden + 401 Unauthorized + 403 Forbidden (remove root user when auth is enabled) 404 Not Found 200 Headers: 200 Body: (empty) @@ -201,7 +209,6 @@ A full role structure may look like this. A Permission List structure is used fo } "grant" : {"kv": {...}}, "revoke": {"kv": {...}}, - "members" : ["alice", "bob"] } ``` @@ -213,9 +220,8 @@ GET/HEAD /v2/auth/roles Authorization: Basic Possible Status Codes: 200 OK - 403 Forbidden + 401 Unauthorized 200 Headers: - ETag: "" Content-type: application/json 200 Body: { @@ -230,10 +236,9 @@ GET/HEAD /v2/auth/roles/fleet Authorization: Basic Possible Status Codes: 200 OK - 403 Forbidden + 401 Unauthorized 404 Not Found 200 Headers: - ETag: "roles/fleet:" Content-type: application/json 200 Body: { @@ -248,7 +253,7 @@ GET/HEAD /v2/auth/roles/fleet **Create Or Update A Role** -PUT /v2/auth/roles/rocket +PUT /v2/auth/roles/rkt Sent Headers: Authorization: Basic @@ -257,22 +262,24 @@ PUT /v2/auth/roles/rocket * Starting permission set if creating * Granted/Revoked permission set if updating Possible Status Codes: + 200 OK 201 Created - 403 Forbidden - 404 Not Found - 409 Conflict (if exists) + 400 Bad Request + 401 Unauthorized + 409 Conflict (when granting duplicated permission or revoking non-existing permission) 200 Body: JSON state of the role **Remove A Role** -DELETE /v2/auth/roles/rocket +DELETE /v2/auth/roles/rkt Sent Headers: Authorization: Basic Possible Status Codes: 200 OK - 403 Forbidden + 401 Unauthorized + 403 Forbidden (remove root) 404 Not Found 200 Headers: 200 Body: (empty) @@ -282,44 +289,39 @@ DELETE /v2/auth/roles/rocket Let's walk through an example to show two tenants (applications, in our case) using etcd permissions. -### Enable auth +### Create root role ``` -PUT /v2/auth/enable - Headers: +PUT /v2/auth/users/root Put Body: - {"user" : "root", "password": "root"} + {"user" : "root", "password": "betterRootPW!"} ``` - -### Change root's password +### Enable auth ``` -PUT /v2/auth/users/root - Headers: - Authorization: Basic - Put Body: - {"user" : "root", "password": "betterRootPW!"} +PUT /v2/auth/enable ``` + ### Create Roles for the Applications -Create the rocket role fully specified: +Create the rkt role fully specified: ``` -PUT /v2/auth/roles/rocket +PUT /v2/auth/roles/rkt Headers: Authorization: Basic Body: { - "role" : "rocket", + "role" : "rkt", "permissions" : { "kv": { "read": [ - "/rocket/*" + "/rkt/*" ], "write": [ - "/rocket/*" + "/rkt/*" ] } } @@ -338,10 +340,10 @@ PUT /v2/auth/roles/fleet } ``` -### Optional: Add some permissions to the roles +### Optional: Grant some permissions to the roles Well, we finally figured out where we want fleet to live. Let's fix it. -(Note that we avoided this in the rocket case. So this step is optional.) +(Note that we avoided this in the rkt case. So this step is optional.) ``` @@ -354,7 +356,7 @@ PUT /v2/auth/roles/fleet "grant" : { "kv" : { "read": [ - "/rocket/fleet", + "/rkt/fleet", "/fleet/*" ] } @@ -367,11 +369,11 @@ PUT /v2/auth/roles/fleet Same as before, let's use rocket all at once and fleet separately ``` -PUT /v2/auth/users/rocketuser +PUT /v2/auth/users/rktuser Headers: Authorization: Basic Body: - {"user" : "rocketuser", "password" : "rocketpw", "roles" : ["rocket"]} + {"user" : "rktuser", "password" : "rktpw", "roles" : ["rkt"]} ``` ``` @@ -394,16 +396,16 @@ PUT /v2/auth/users/fleetuser {"user": "fleetuser", "grant": ["fleet"]} ``` -#### Start to use fleetuser and rocketuser +#### Start to use fleetuser and rktuser For example: ``` -PUT /v2/keys/rocket/RocketData +PUT /v2/keys/rocket/RktData Headers: Authorization: Basic ``` -Reads and writes outside the prefixes granted will fail with a 403 Forbidden. +Reads and writes outside the prefixes granted will fail with a 401 Unauthorized.