Incorporated Swauth into Swift as an optional DevAuth replacement.

1 files changed, 125 insertions, 5 deletions

diff --git a/doc/source/overview_auth.rst b/doc/source/overview_auth.rst
index 364a6928d..604aed266 100644
--- a/doc/source/overview_auth.rst
+++ b/doc/source/overview_auth.rst
@@ -48,9 +48,129 @@ implementing your own auth.
 
 Also, see :doc:`development_auth`.
 
-------------------
-History and Future
-------------------
 
-What's established in Swift for authentication/authorization has history from
-before Swift, so that won't be recorded here.
+------
+Swauth
+------
+
+The Swauth system is an optional DevAuth replacement included at
+swift/common/middleware/swauth.py is a scalable authentication and
+authorization system that uses Swift itself as its backing store. This section
+will describe how it stores its data.
+
+At the topmost level, the auth system has its own Swift account it stores its
+own account information within. This Swift account is known as
+self.auth_account in the code and its name is in the format
+self.reseller_prefix + ".auth". In this text, we'll refer to this account as
+<auth_account>.
+
+The containers whose names do not begin with a period represent the accounts
+within the auth service. For example, the <auth_account>/test container would
+represent the "test" account.
+
+The objects within each container represent the users for that auth service
+account. For example, the <auth_account>/test/bob object would represent the
+user "bob" within the auth service account of "test". Each of these user
+objects contain a JSON dictionary of the format::
+
+    {"auth": "<auth_type>:<auth_value>", "groups": <groups_array>}
+
+The `<auth_type>` can only be `plaintext` at this time, and the `<auth_value>`
+is the plain text password itself.
+
+The `<groups_array>` contains at least two group names. The first is a unique
+group name identifying that user and is of the format `<user>:<account>`. The
+second group is the `<account>` itself. Additional groups of `.admin` for
+account administrators and `.reseller_admin` for reseller administrators may
+exist. Here's an example user JSON dictionary::
+
+    {"auth": "plaintext:testing", "groups": ["test:tester", "test", ".admin"]}
+
+To map an auth service account to a Swift storage account, the Service Account
+Id string is stored in the `X-Container-Meta-Account-Id` header for the
+<auth_account>/<account> container. To map back the other way, an
+<auth_account>/.account_id/<account_id> object is created with the contents of
+the corresponding auth service's account name.
+
+Also, to support a future where the auth service will support multiple Swift
+clusters for the same auth service account, an
+<auth_account>/<account>/.clusters object is created with its contents having a
+JSON dictionary of the format::
+
+    {"storage": {"default": "local", "local": <url>}}
+
+The "default" is always "local" right now, and "local" is always the single
+Swift cluster URL; but in the future there can be more than one cluster with
+various names instead of just "local", and the "default" key's value will
+contain the primary cluster to use for that account. Also, there may be more
+services in addition to the current "storage" service right now.
+
+Here's an example .clusters dictionary at the moment::
+
+    {"storage":
+        {"default": "local",
+         "local": "http://127.0.0.1:8080/v1/AUTH_8980f74b1cda41e483cbe0a925f448a9"}}
+
+But, here's an example of what the dictionary may look like in the future::
+
+    {"storage":
+        {"default": "dfw",
+         "dfw": "http://dfw.storage.com:8080/v1/AUTH_8980f74b1cda41e483cbe0a925f448a9",
+         "ord": "http://ord.storage.com:8080/v1/AUTH_8980f74b1cda41e483cbe0a925f448a9",
+         "sat": "http://ord.storage.com:8080/v1/AUTH_8980f74b1cda41e483cbe0a925f448a9"},
+     "servers":
+        {"default": "dfw",
+         "dfw": "http://dfw.servers.com:8080/v1/AUTH_8980f74b1cda41e483cbe0a925f448a9",
+         "ord": "http://ord.servers.com:8080/v1/AUTH_8980f74b1cda41e483cbe0a925f448a9",
+         "sat": "http://ord.servers.com:8080/v1/AUTH_8980f74b1cda41e483cbe0a925f448a9"}}
+
+Lastly, the tokens themselves are stored as objects in the
+<auth_account>/.token container. The names of the objects are the token strings
+themselves, such as `AUTH_tked86bbd01864458aa2bd746879438d5a`. The contents of
+the token objects are JSON dictionaries of the format::
+
+    {"account": <account>,
+     "user": <user>,
+     "account_id": <account_id>,
+     "groups": <groups_array>,
+     "expires": <time.time() value>}
+
+The `<account>` is the auth service account's name for that token. The `<user>`
+is the user within the account for that token. The `<account_id>` is the
+same as the `X-Container-Meta-Account-Id` for the auth service's account,
+as described above. The `<groups_array>` is the user's groups, as described
+above with the user object. The "expires" value indicates when the token is no
+longer valid, as compared to Python's time.time() value.
+
+Here's an example token object's JSON dictionary::
+
+    {"account": "test",
+     "user": "tester",
+     "account_id": "AUTH_8980f74b1cda41e483cbe0a925f448a9",
+     "groups": ["test:tester", "test", ".admin"],
+     "expires": 1291273147.1624689}
+
+To easily map a user to an already issued token, the token name is stored in
+the user object's `X-Object-Meta-Auth-Token` header.
+
+Here is an example full listing of an <auth_account>::
+
+    .account_id
+        AUTH_4a4e6655-4c8e-4bcb-b73e-0ff1104c4fef
+        AUTH_5162ec51-f792-4db3-8a35-b3439a1bf6fd
+        AUTH_8efbea51-9339-42f8-8ac5-f26e1da67eed
+    .token
+        AUTH_tk03d8571f735a4ec9abccc704df941c6e
+        AUTH_tk27cf3f2029b64ec8b56c5d638807b3de
+        AUTH_tk7594203449754c22a34ac7d910521c2e
+        AUTH_tk8f2ee54605dd42a8913d244de544d19e
+    reseller
+        .clusters
+        reseller
+    test
+        .clusters
+        tester
+        tester3
+    test2
+        .clusters
+        tester2