From 2edfd2b951681641d13fceb98179140bc332b141 Mon Sep 17 00:00:00 2001 From: gholt Date: Sun, 5 Sep 2010 20:30:09 -0700 Subject: [PATCH] Doc fixes and updates --- doc/source/auth.rst | 2 +- doc/source/overview_auth.rst | 27 ++++++++++++++++----------- swift/auth/server.py | 14 +++++++++----- swift/common/client.py | 4 ++-- 4 files changed, 28 insertions(+), 19 deletions(-) diff --git a/doc/source/auth.rst b/doc/source/auth.rst index dc5a65ac45..feb3be8a99 100644 --- a/doc/source/auth.rst +++ b/doc/source/auth.rst @@ -4,7 +4,7 @@ Developer's Authorization ************************* -.. _auth-server: +.. _auth_server: Auth Server =========== diff --git a/doc/source/overview_auth.rst b/doc/source/overview_auth.rst index a242280553..364a6928dc 100644 --- a/doc/source/overview_auth.rst +++ b/doc/source/overview_auth.rst @@ -6,9 +6,9 @@ The Auth System Developer Auth -------------- -The auth system for Swift is based on the auth system from the existing -Rackspace architecture -- actually from a few existing auth systems -- -and is therefore a bit disjointed. The distilled points about it are: +The auth system for Swift is loosely based on the auth system from the existing +Rackspace architecture -- actually from a few existing auth systems -- and is +therefore a bit disjointed. The distilled points about it are: * The authentication/authorization part is outside Swift itself * The user of Swift passes in an auth token with each request @@ -23,13 +23,16 @@ of something unique, some use "something else" but the salient point is that the token is a string which can be sent as-is back to the auth system for validation. -An auth call is given the auth token and the Swift account hash. For a valid -token, the auth system responds with a session TTL and overall expiration in -seconds from now. Swift does not honor the session TTL but will cache the -token up to the expiration time. Tokens can be purged through a call to the -auth system. +Swift will make calls to the external auth system, giving the auth token to be +validated. For a valid token, the auth system responds with an overall +expiration in seconds from now. Swift will cache the token up to the expiration +time. The included devauth also has the concept of admin and non-admin users +within an account. Admin users can do anything within the account. Non-admin +users can only perform operations per container based on the container's +X-Container-Read and X-Container-Write ACLs. For more information on ACLs, see +:mod:`swift.common.middleware.acl` -The user starts a session by sending a ReST request to that auth system +The user starts a session by sending a ReST request to the external auth system to receive the auth token and a URL to the Swift system. -------------- @@ -40,8 +43,10 @@ Auth is written as wsgi middleware, so implementing your own auth is as easy as writing new wsgi middleware, and plugging it in to the proxy server. The current middleware is implemented in the DevAuthMiddleware class in -swift/common/auth.py, and should be a good starting place for implemeting -your own auth. +swift/common/middleware/auth.py, and should be a good starting place for +implementing your own auth. + +Also, see :doc:`development_auth`. ------------------ History and Future diff --git a/swift/auth/server.py b/swift/auth/server.py index e047397072..d9007e1e62 100644 --- a/swift/auth/server.py +++ b/swift/auth/server.py @@ -65,11 +65,12 @@ class AuthController(object): the token. * The Swift cluster completes the user's request. - Another use case is creating a new account: + Another use case is creating a new user: - * The developer makes a ReST call to create a new account. - * The auth server makes ReST calls to the Swift cluster's account servers - to create a new account on its end. + * The developer makes a ReST call to create a new user. + * If the account for the user does not yet exist, the auth server makes + ReST calls to the Swift cluster's account servers to create a new account + on its end. * The auth server records the information in its database. A last use case is recreating existing accounts; this is really only useful @@ -261,6 +262,9 @@ class AuthController(object): cluster while still supporting old accounts going to the Swift clusters they were created on. + Currently, updating a user's information (password, admin access) must + be done by directly updating the sqlite database. + :param account: The name for the new account :param user: The name for the new user :param password: The password for the new account @@ -334,7 +338,7 @@ class AuthController(object): def handle_token(self, request): """ - Hanles ReST request from Swift to validate tokens + Handles ReST requests from Swift to validate tokens Valid URL paths: * GET /token/ diff --git a/swift/common/client.py b/swift/common/client.py index 4832452130..0448442526 100644 --- a/swift/common/client.py +++ b/swift/common/client.py @@ -626,12 +626,12 @@ def put_object(url, token, container, name, contents, content_length=None, def post_object(url, token, container, name, headers, http_conn=None): """ - Change object metadata + Update object metadata :param url: storage URL :param token: auth token :param container: container name that the object is in - :param name: object name to change + :param name: name of the object to update :param headers: additional headers to include in the request :param http_conn: HTTP connection object (If None, it will create the conn object)