Mirroristas/etcd
2
0
Fork 0
mirror of https://github.com/etcd-io/etcd.git synced 2024-09-27 06:25:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: update auth_api.md

Browse Source
This commit is contained in:
Xiang Li 2015-06-23 11:08:04 -07:00
parent ad7124599d
commit aaf802f321
1 changed files with 48 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

94
Documentation/auth_api.md
View File

@ -44,7 +44,7 @@ We only support [Basic Auth](http://en.wikipedia.org/wiki/Basic_access_authentic
### Authorization field for operations ### Authorization field for operations
Added to requests to /v2/keys, /v2/auth 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} Authorization: Basic {encoded string}
### Future Work ### Future Work
@ -89,6 +89,7 @@ PUT /v2/auth/enable
Possible Status Codes: Possible Status Codes:
200 OK 200 OK
400 Bad Request (if root user has not been created) 400 Bad Request (if root user has not been created)
409 Conflict (already enabled)
200 Body: (empty) 200 Body: (empty)
**Disable auth** **Disable auth**
@ -99,7 +100,8 @@ DELETE /v2/auth/enable
Authorization: Basic <RootAuthString> Authorization: Basic <RootAuthString>
Possible Status Codes: Possible Status Codes:
200 OK 200 OK
403 Forbidden (if not a root user) 401 Unauthorized (if not a root user)
409 Conflict (already disabled)
200 Body: (empty) 200 Body: (empty)
@ -130,7 +132,7 @@ GET/HEAD /v2/auth/user
Authorization: Basic <BasicAuthString> Authorization: Basic <BasicAuthString>
Possible Status Codes: Possible Status Codes:
200 OK 200 OK
403 Forbidden 401 Unauthorized
200 Headers: 200 Headers:
Content-type: application/json Content-type: application/json
200 Body: 200 Body:
@ -146,7 +148,7 @@ GET/HEAD /v2/auth/users/alice
Authorization: Basic <BasicAuthString> Authorization: Basic <BasicAuthString>
Possible Status Codes: Possible Status Codes:
200 OK 200 OK
403 Forbidden 401 Unauthorized
404 Not Found 404 Not Found
200 Headers: 200 Headers:
Content-type: application/json 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). * Grant/Revoke/Password filled in when updating (to grant roles, revoke roles, or change the password).
Possible Status Codes: Possible Status Codes:
200 OK 200 OK
403 Forbidden 201 Created
400 Bad Request
401 Unauthorized
409 Conflict (when granting duplicated roles or revoking non-existing roles) 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** **Remove A User**
@ -182,7 +189,8 @@ DELETE /v2/auth/users/charlie
Authorization: Basic <BasicAuthString> Authorization: Basic <BasicAuthString>
Possible Status Codes: Possible Status Codes:
200 OK 200 OK
403 Forbidden 401 Unauthorized
403 Forbidden (remove root user when auth is enabled)
404 Not Found 404 Not Found
200 Headers: 200 Headers:
200 Body: (empty) 200 Body: (empty)
@ -201,7 +209,6 @@ A full role structure may look like this. A Permission List structure is used fo
} }
"grant" : {"kv": {...}}, "grant" : {"kv": {...}},
"revoke": {"kv": {...}}, "revoke": {"kv": {...}},
"members" : ["alice", "bob"]
} }
``` ```
@ -213,9 +220,8 @@ GET/HEAD /v2/auth/roles
Authorization: Basic <BasicAuthString> Authorization: Basic <BasicAuthString>
Possible Status Codes: Possible Status Codes:
200 OK 200 OK
403 Forbidden 401 Unauthorized
200 Headers: 200 Headers:
ETag: "<hash of list of roles>"
Content-type: application/json Content-type: application/json
200 Body: 200 Body:
{ {
@ -230,10 +236,9 @@ GET/HEAD /v2/auth/roles/fleet
Authorization: Basic <BasicAuthString> Authorization: Basic <BasicAuthString>
Possible Status Codes: Possible Status Codes:
200 OK 200 OK
403 Forbidden 401 Unauthorized
404 Not Found 404 Not Found
200 Headers: 200 Headers:
ETag: "roles/fleet:<lastModified>"
Content-type: application/json Content-type: application/json
200 Body: 200 Body:
{ {
@ -248,7 +253,7 @@ GET/HEAD /v2/auth/roles/fleet
**Create Or Update A Role** **Create Or Update A Role**
PUT /v2/auth/roles/rocket PUT /v2/auth/roles/rkt
Sent Headers: Sent Headers:
Authorization: Basic <BasicAuthString> Authorization: Basic <BasicAuthString>
@ -257,22 +262,24 @@ PUT /v2/auth/roles/rocket
* Starting permission set if creating * Starting permission set if creating
* Granted/Revoked permission set if updating * Granted/Revoked permission set if updating
Possible Status Codes: Possible Status Codes:
200 OK
201 Created 201 Created
403 Forbidden 400 Bad Request
404 Not Found 401 Unauthorized
409 Conflict (if exists) 409 Conflict (when granting duplicated permission or revoking non-existing permission)
200 Body: 200 Body:
JSON state of the role JSON state of the role
**Remove A Role** **Remove A Role**
DELETE /v2/auth/roles/rocket DELETE /v2/auth/roles/rkt
Sent Headers: Sent Headers:
Authorization: Basic <BasicAuthString> Authorization: Basic <BasicAuthString>
Possible Status Codes: Possible Status Codes:
200 OK 200 OK
403 Forbidden 401 Unauthorized
403 Forbidden (remove root)
404 Not Found 404 Not Found
200 Headers: 200 Headers:
200 Body: (empty) 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. 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 Body:
{"user" : "root", "password": "root"}
```
### Change root's password
``` ```
PUT /v2/auth/users/root PUT /v2/auth/users/root
Headers:
Authorization: Basic <root:root>
Put Body: Put Body:
{"user" : "root", "password": "betterRootPW!"} {"user" : "root", "password": "betterRootPW!"}
``` ```
### Create Roles for the Applications ### Enable auth
Create the rocket role fully specified:
``` ```
PUT /v2/auth/roles/rocket PUT /v2/auth/enable
```
### Create Roles for the Applications
Create the rkt role fully specified:
```
PUT /v2/auth/roles/rkt
Headers: Headers:
Authorization: Basic <root:betterRootPW!> Authorization: Basic <root:betterRootPW!>
Body: Body:
{ {
"role" : "rocket", "role" : "rkt",
"permissions" : { "permissions" : {
"kv": { "kv": {
"read": [ "read": [
"/rocket/*" "/rkt/*"
], ],
"write": [ "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. 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" : { "grant" : {
"kv" : { "kv" : {
"read": [ "read": [
"/rocket/fleet", "/rkt/fleet",
"/fleet/*" "/fleet/*"
] ]
} }
@ -367,11 +369,11 @@ PUT /v2/auth/roles/fleet
Same as before, let's use rocket all at once and fleet separately Same as before, let's use rocket all at once and fleet separately
``` ```
PUT /v2/auth/users/rocketuser PUT /v2/auth/users/rktuser
Headers: Headers:
Authorization: Basic <root:betterRootPW!> Authorization: Basic <root:betterRootPW!>
Body: 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"]} {"user": "fleetuser", "grant": ["fleet"]}
``` ```
#### Start to use fleetuser and rocketuser #### Start to use fleetuser and rktuser
For example: For example:
``` ```
PUT /v2/keys/rocket/RocketData PUT /v2/keys/rocket/RktData
Headers: Headers:
Authorization: Basic <rocketuser:rocketpw> Authorization: Basic <rocketuser:rocketpw>
``` ```
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.