diff options
author | Luis Pabon <lpabon@redhat.com> | 2013-10-10 16:53:28 -0400 |
---|---|---|
committer | Luis Pabon <lpabon@redhat.com> | 2013-10-13 19:36:20 -0700 |
commit | ac1ac5bd2171e61ba4332dcae33d8a433cef7a4f (patch) | |
tree | 9d836201435c83cf59a659124f004a03f488c1f5 /gluster/swift/common/middleware/gswauth/doc/source/api.rst | |
parent | 46cd43fdf401b16f9e1b588e5fc8d2c5dd599b37 (diff) |
GSWauth authentication to be based on SWauth
We are planning on creating a GlusterFS aware authentication
system for gluster-swift based on SWauth.
We forked from SWauth commit
41d36ebe160aa3346f6f45197fff0c80f38fde58
Change-Id: Ia28730d21e04fc8d9ce0cb317fc04d0d97583fca
Signed-off-by: Luis Pabon <lpabon@redhat.com>
Reviewed-on: http://review.gluster.org/6069
Diffstat (limited to 'gluster/swift/common/middleware/gswauth/doc/source/api.rst')
-rw-r--r-- | gluster/swift/common/middleware/gswauth/doc/source/api.rst | 466 |
1 files changed, 466 insertions, 0 deletions
diff --git a/gluster/swift/common/middleware/gswauth/doc/source/api.rst b/gluster/swift/common/middleware/gswauth/doc/source/api.rst new file mode 100644 index 0000000..d2efa0f --- /dev/null +++ b/gluster/swift/common/middleware/gswauth/doc/source/api.rst @@ -0,0 +1,466 @@ +.. _api_top: + +---------- +Swauth API +---------- + +Overview +======== + +Swauth has its own internal versioned REST API for adding, removing, +and editing accounts. This document explains the v2 API. + +Authentication +-------------- + +Each REST request against the swauth API requires the inclusion of a +specific authorization user and key to be passed in a specific HTTP +header. These headers are defined as ``X-Auth-Admin-User`` and +``X-Auth-Admin-Key``. + +Typically, these values are ``.super_admin`` (the site super admin +user) with the key being specified in the swauth middleware +configuration as ``super_admin_key``. + +This could also be a reseller admin with the appropriate rights to +perform actions on reseller accounts. + +Endpoints +--------- + +The swauth API endpoint is presented on the proxy servers, in the +"/auth" namespace. In addition, the API is versioned, and the version +documented is version 2. API versions subdivide the auth namespace by +version, specified as a version identifier like "v2". + +The auth endpoint described herein is therefore located at "/auth/v2/" +as presented by the proxy servers. + +Bear in mind that in order for the auth management API to be +presented, it must be enabled in the proxy server config by setting +``allow_account_managment`` to ``true`` in the ``[app:proxy-server]`` +stanza of your proxy-server.conf. + +Responses +--------- + +Responses from the auth APIs are returned as a JSON structure. +Example return values in this document are edited for readability. + + +Reseller/Admin Services +======================= + +Operations can be performed against the endpoint itself to perform +general administrative operations. Currently, the only operations +that can be performed is a GET operation to get reseller or site admin +information. + +Get Admin Info +-------------- + +A GET request at the swauth endpoint will return reseller information +for the account specified in the ``X-Auth-Admin-User`` header. +Currently, the information returned is limited to a list of accounts +for the reseller or site admin. + +Valid return codes: + * 200: Success + * 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key + * 5xx: Internal error + +Example Request:: + + GET /auth/<api version>/ HTTP/1.1 + X-Auth-Admin-User: .super_admin + X-Auth-Admin-Key: swauthkey + +Example Curl Request:: + + curl -D - https://<endpoint>/auth/v2/ \ + -H "X-Auth-Admin-User: .super_admin" \ + -H "X-Auth-Admin-Key: swauthkey" + +Example Result:: + + HTTP/1.1 200 OK + + { "accounts": + [ + { "name": "account1" }, + { "name": "account2" }, + { "name": "account3" } + ] + } + + +Account Services +================ + +There are API request to get account details, create, and delete +accounts, mapping logically to the REST verbs GET, PUT, and DELETE. +These actions are performed against an account URI, in the following +general request structure:: + + METHOD /auth/<version>/<account> HTTP/1.1 + +The methods that can be used are detailed below. + +Get Account Details +------------------- + +Account details can be retrieved by performing a GET request against +an account URI. On success, a JSON dictionary will be returned +containing the keys `account_id`, `services`, and `users`. The +`account_id` is the value used when creating service accounts. The +`services` value is a dict that represents valid storage cluster +endpoints, and which endpoint is the default. The 'users' value is a +list of dicts, each dict representing a user and currently only +containing the single key 'name'. + +Valid Responses: + * 200: Success + * 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key + * 5xx: Internal error + +Example Request:: + + GET /auth/<api version>/<account> HTTP/1.1 + X-Auth-Admin-User: .super_admin + X-Auth-Admin-Key: swauthkey + +Example Curl Request:: + + curl -D - https://<endpoint>/auth/v2/<account> \ + -H "X-Auth-Admin-User: .super_admin" \ + -H "X-Auth-Admin-Key: swauthkey" + +Example Response:: + + HTTP/1.1 200 OK + + { "services": + { "storage": + { "default": "local", + "local": "https://<storage endpoint>/v1/<account_id>" }, + }, + "account_id": "<account_id>", + "users": [ { "name": "user1" }, + { "name": "user2" } ] + } + +Create Account +-------------- + +An account can be created with a PUT request against a non-existent +account. By default, a newly created UUID4 will be used with the +reseller prefix as the account ID used when creating corresponding +service accounts. However, you can provide an X-Account-Suffix header +to replace the UUDI4 part. + +Valid return codes: + * 200: Success + * 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key + * 5xx: Internal error + +Example Request:: + + GET /auth/<api version>/<new_account> HTTP/1.1 + X-Auth-Admin-User: .super_admin + X-Auth-Admin-Key: swauthkey + +Example Curl Request:: + + curl -D - https://<endpoint>/auth/v2/<new_account> \ + -H "X-Auth-Admin-User: .super_admin" \ + -H "X-Auth-Admin-Key: swauthkey" + +Example Response:: + + HTTP/1.1 201 Created + + +Delete Account +-------------- + +An account can be deleted with a DELETE request against an existing +account. + +Valid Responses: + * 204: Success + * 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key + * 404: Account not found + * 5xx: Internal error + +Example Request:: + + DELETE /auth/<api version>/<account> HTTP/1.1 + X-Auth-Admin-User: .super_admin + X-Auth-Admin-Key: swauthkey + +Example Curl Request:: + + curl -XDELETE -D - https://<endpoint>/auth/v2/<account> \ + -H "X-Auth-Admin-User: .super_admin" \ + -H "X-Auth-Admin-Key: swauthkey" + +Example Response:: + + HTTP/1.1 204 No Content + + +User Services +============= + +Each account in swauth contains zero or more users. These users can +be determined with the 'Get Account Details' API request against an +account. + +Users in an account can be created, modified, and detailed as +described below by apply the appropriate REST verbs to a user URI, in +the following general request structure:: + + METHOD /auth/<version>/<account>/<user> HTTP/1.1 + +The methods that can be used are detailed below. + +Get User Details +---------------- + +User details can be retrieved by performing a GET request against +a user URI. On success, a JSON dictionary will be returned as +described:: + + {"groups": [ # List of groups the user is a member of + {"name": "<act>:<usr>"}, + # The first group is a unique user identifier + {"name": "<account>"}, + # The second group is the auth account name + {"name": "<additional-group>"} + # There may be additional groups, .admin being a + # special group indicating an account admin and + # .reseller_admin indicating a reseller admin. + ], + "auth": "<auth-type>:<key>" + # The auth-type and key for the user; currently only + # plaintext and sha1 are implemented as auth types. + } + +For example:: + + {"groups": [{"name": "test:tester"}, {"name": "test"}, + {"name": ".admin"}], + "auth": "plaintext:testing"} + +Valid Responses: + * 200: Success + * 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key + * 404: Unknown account + * 5xx: Internal error + +Example Request:: + + GET /auth/<api version>/<account>/<user> HTTP/1.1 + X-Auth-Admin-User: .super_admin + X-Auth-Admin-Key: swauthkey + +Example Curl Request:: + + curl -D - https://<endpoint>/auth/v2/<account>/<user> \ + -H "X-Auth-Admin-User: .super_admin" \ + -H "X-Auth-Admin-Key: swauthkey" + +Example Response:: + + HTTP/1.1 200 Ok + + { "groups": [ { "name": "<account>:<user>" }, + { "name": "<user>" }, + { "name": ".admin" } ], + "auth" : "plaintext:password" } + + +Create User +----------- + +A user can be created with a PUT request against a non-existent +user URI. The new user's password must be set using the +``X-Auth-User-Key`` header. The user name MUST NOT start with a +period ('.'). This requirement is enforced by the API, and will +result in a 400 error. + +Optional Headers: + + * ``X-Auth-User-Admin: true``: create the user as an account admin + * ``X-Auth-User-Reseller-Admin: true``: create the user as a reseller + admin + +Reseller admin accounts can only be created by the site admin, while +regular accounts (or account admin accounts) can be created by an +account admin, an appropriate reseller admin, or the site admin. + +Note that PUT requests are idempotent, and the PUT request serves as +both a request and modify action. + +Valid Responses: + * 200: Success + * 400: Invalid request (missing required headers) + * 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key, or insufficient priv + * 404: Unknown account + * 5xx: Internal error + +Example Request:: + + PUT /auth/<api version>/<account>/<user> HTTP/1.1 + X-Auth-Admin-User: .super_admin + X-Auth-Admin-Key: swauthkey + X-Auth-User-Admin: true + X-Auth-User-Key: secret + +Example Curl Request:: + + curl -XPUT -D - https://<endpoint>/auth/v2/<account>/<user> \ + -H "X-Auth-Admin-User: .super_admin" \ + -H "X-Auth-Admin-Key: swauthkey" \ + -H "X-Auth-User-Admin: true" \ + -H "X-Auth-User-Key: secret" + +Example Response:: + + HTTP/1.1 201 Created + +Delete User +----------- + +A user can be deleted by performing a DELETE request against a user +URI. This action can only be performed by an account admin, +appropriate reseller admin, or site admin. + +Valid Responses: + * 200: Success + * 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key, or insufficient priv + * 404: Unknown account or user + * 5xx: Internal error + +Example Request:: + + DELETE /auth/<api version>/<account>/<user> HTTP/1.1 + X-Auth-Admin-User: .super_admin + X-Auth-Admin-Key: swauthkey + +Example Curl Request:: + + curl -XDELETE -D - https://<endpoint>/auth/v2/<account>/<user> \ + -H "X-Auth-Admin-User: .super_admin" \ + -H "X-Auth-Admin-Key: swauthkey" + +Example Response:: + + HTTP/1.1 204 No Content + + +Other Services +============== + +There are several other swauth functions that can be performed, mostly +done via "pseudo-user" accounts. These are well-known user names that +are unable to be actually provisioned. These pseudo-users are +described below. + +.. _api_set_service_endpoints: + +Set Service Endpoints +--------------------- + +Service endpoint information can be retrived using the _`Get Account +Details` API method. + +This function allows setting values within this section for +the <account>, allowing the addition of new service end points +or updating existing ones by performing a POST to the URI +corresponding to the pseudo-user ".services". + +The body of the POST request should contain a JSON dict with +the following format:: + + {"service_name": {"end_point_name": "end_point_value"}} + +There can be multiple services and multiple end points in the +same call. + +Any new services or end points will be added to the existing +set of services and end points. Any existing services with the +same service name will be merged with the new end points. Any +existing end points with the same end point name will have +their values updated. + +The updated services dictionary will be returned on success. + +Valid Responses: + + * 200: Success + * 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key + * 404: Account not found + * 5xx: Internal error + +Example Request:: + + POST /auth/<api version>/<account>/.services HTTP/1.0 + X-Auth-Admin-User: .super_admin + X-Auth-Admin-Key: swauthkey + + {"storage": { "local": "<new endpoint>" }} + +Example Curl Request:: + + curl -XPOST -D - https://<endpoint>/auth/v2/<account>/.services \ + -H "X-Auth-Admin-User: .super_admin" \ + -H "X-Auth-Admin-Key: swauthkey" --data-binary \ + '{ "storage": { "local": "<new endpoint>" }}' + +Example Response:: + + HTTP/1.1 200 OK + + {"storage": {"default": "local", "local": "<new endpoint>" }} + +Get Account Groups +------------------ + +Individual user group information can be retrieved using the `Get User Details`_ API method. + +This function allows retrieving all group information for all users in +an existing account. This can be achieved using a GET action against +a user URI with the pseudo-user ".groups". + +The JSON dictionary returned will be a "groups" dictionary similar to +that documented in the `Get User Details`_ method, but representing +the summary of all groups utilized by all active users in the account. + +Valid Responses: + * 200: Success + * 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key + * 404: Account not found + * 5xx: Internal error + +Example Request:: + + GET /auth/<api version>/<account>/.groups + X-Auth-Admin-User: .super_admin + X-Auth-Admin-Key: swauthkey + +Example Curl Request:: + + curl -D - https://<endpoint>/auth/v2/<account>/.groups \ + -H "X-Auth-Admin-User: .super_admin" \ + -H "X-Auth-Admin-Key: swauthkey" + +Example Response:: + + HTTP/1.1 200 OK + + { "groups": [ { "name": ".admin" }, + { "name": "<account>" }, + { "name": "<account>:user1" }, + { "name": "<account>:user2" } ] } + |