diff --git a/doc/source/api.rst b/doc/source/api.rst index 0c3ced6..13d174e 100644 --- a/doc/source/api.rst +++ b/doc/source/api.rst @@ -423,15 +423,14 @@ Example Response:: Get Account Groups ------------------ -Individual user group information can be retrived using the _`Get User -Details` API method. +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 +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: diff --git a/doc/source/authtypes.rst b/doc/source/authtypes.rst index e5109ea..a19ee22 100644 --- a/doc/source/authtypes.rst +++ b/doc/source/authtypes.rst @@ -1,4 +1,4 @@ -.. _swauth_middleware_module: +.. _swauth_authtypes_module: swauth.authtypes ================= diff --git a/doc/source/details.rst b/doc/source/details.rst index 8c542f3..3b14ad8 100644 --- a/doc/source/details.rst +++ b/doc/source/details.rst @@ -40,9 +40,7 @@ config file, along with the salt value in the following way:: auth_type = auth_type_salt = -Both fields are optional. auth_type defaults to `plaintext` and auth_type_salt - defaults to "swauthsalt". Additional auth types can be implemented along with -existing ones in the authtypes.py module. +Both fields are optional. auth_type defaults to `plaintext` and auth_type_salt defaults to "swauthsalt". Additional auth types can be implemented along with existing ones in the authtypes.py module. The `` contains at least two groups. The first is a unique group identifying that user and it's name is of the format `:`. The diff --git a/doc/source/index.rst b/doc/source/index.rst index 9f0c40c..a56c0c7 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -20,13 +20,43 @@ Swauth https://code.launchpad.net/~gholt/swift/deswauth/+merge/62392 for the Swift side of things. -Quick Install -------------- +Overview +-------- + +Before discussing how to install Swauth within a Swift system, it might help to understand how Swauth does it work first. + +1. Swauth is middleware installed in the Swift Proxy's WSGI pipeline. + +2. It intercepts requests to ``/auth/`` (by default). + +3. It also uses Swift's `authorize callback `_ and `acl callback `_ features to authorize Swift requests. + +4. Swauth will also make various internal calls to the Swift WSGI pipeline it's installed in to manipulate containers and objects within an ``AUTH_.auth`` (by default) Swift account. These containers and objects are what store account and user information. + +5. Instead of #4, Swauth can be configured to call out to another remote Swauth to perform #4 on its behalf (using the swauth_remote config value). + +6. When managing accounts and users with the various ``swauth-`` command line tools, these tools are actually just performing HTTP requests against the ``/auth/`` end point referenced in #2. You can make your own tools that use the same ``API ``. + +7. In the special case of creating a new account, Swauth will call out to the Swift cluster to create the actual Swift account as well as performing #4 for its own use. + + a. This Swift cluster callout is an account PUT request to the URL defined by the ``swift_default_cluster`` config value. + + b. This callout end point is also saved when the account is created so that it can be given to the users of that account in the future. + + c. Sometimes, due to public/private network routing or firewalling, the URL Swauth should use should be different than the URL Swauth should give the users later. That is why the ``default_swift_cluster`` config value can accept two URLs (first is the one for users, second is the one for Swauth). + + d. Once an account is created, the URL given to users for that account will not change, even if the ``default_swift_cluster`` config value changes. This is so that you can use multiple clusters with the same Swauth system; ``default_swift_cluster`` just points to the one where you want new users to go. + + f. You can change the stored URL for an account if need be with the ``swauth-set-account-service`` command line tool or a POST request (see `API `_). + + +Install +------- 1) Install Swauth with ``sudo python setup.py install`` or ``sudo python setup.py develop`` or via whatever packaging system you may be using. -2) Alter your proxy-server.conf pipeline to have swauth instead of tempauth: +2) Alter your ``proxy-server.conf`` pipeline to have ``swauth`` instead of ``tempauth``: Was:: @@ -38,22 +68,48 @@ Quick Install [pipeline:main] pipeline = catch_errors cache swauth proxy-server -3) Add to your proxy-server.conf the section for the Swauth WSGI filter:: +3) Add to your ``proxy-server.conf`` the section for the Swauth WSGI filter:: [filter:swauth] use = egg:swauth#swauth set log_name = swauth super_admin_key = swauthkey + default_swift_cluster = -4) Restart your proxy server ``swift-init proxy reload`` + The ``default_swift_cluster`` setting can be confusing. -5) Initialize the Swauth backing store in Swift ``swauth-prep -K swauthkey`` + a. If you're using an all-in-one type configuration where everything will be run on the local host, you can omit the ``default_swift_cluster`` completely and it will default to ``local#http://127.0.0.1:/v1``. -6) Add an account/user ``swauth-add-user -A http://127.0.0.1:8080/auth/ -K + b. If you're using a single Swift proxy you can just set the ``default_swift_cluster = cluster_name#https://:/v1`` and that URL will be given to users as well as used by Swauth internally. (Quick note: be sure the ``http`` vs. ``https`` is set right depending on if you're using SSL.) + + c. If you're using multiple Swift proxies behind a load balancer, you'll probably want ``default_swift_cluster = cluster_name#https://:/v1#http://127.0.0.1:/v1`` so that Swauth gives out the first URL but uses the second URL internally. Remember to double-check the ``http`` vs. ``https`` settings for each of the URLs; they might be different if you're terminating SSL at the load balancer. + + Also see the ``proxy-server.conf-sample`` for more config options, such as the ability to have a remote Swauth in a multiple Swift cluster configuration. + +4) Be sure your Swift proxy allows account management in the ``proxy-server.conf``:: + + [app:proxy-server] + ... + allow_account_management = true + + For greater security, you can leave this off any public proxies and just have one or two private proxies with it turned on. + +5) Restart your proxy server ``swift-init proxy reload`` + +6) Initialize the Swauth backing store in Swift ``swauth-prep -K swauthkey`` + +7) Add an account/user ``swauth-add-user -A http[s]://:/auth/ -K swauthkey -a test tester testing`` -7) Ensure it works ``swift -A http://127.0.0.1:8080/auth/v1.0 -U test:tester -K - testing stat -v`` +8) Ensure it works ``swift -A http[s]://:/auth/v1.0 -U test:tester -K testing stat -v`` + + +If anything goes wrong, it's best to start checking the proxy server logs. The client command line utilities often don't get enough information to help. I will often just ``tail -F`` the appropriate proxy log (``/var/log/syslog`` or however you have it configured) and then run the Swauth command to see exactly what requests are happening to try to determine where things fail. + +General note, I find I occasionally just forget to reload the proxies after a config change; so that's the first thing you might try. Or, if you suspect the proxies aren't reloading properly, you might try ``swift-init proxy stop``, ensure all the processes died, then ``swift-init proxy start``. + +Also, it's quite common to get the ``/auth/v1.0`` vs. just ``/auth/`` URL paths confused. Usual rule is: Swauth tools use just ``/auth/`` and Swift tools use ``/auth/v1.0``. + Web Admin Install ----------------- @@ -63,10 +119,11 @@ Web Admin Install with the Lucid packages. If you installed from source, you'll need to cd to the webadmin directory in the source directory. -2) Upload the Web Admin files with ``swift -A http://127.0.0.1:8080/auth/v1.0 +2) Upload the Web Admin files with ``swift -A http[s]://:/auth/v1.0 -U .super_admin:.super_admin -K swauthkey upload .webadmin .`` -3) Open ``http://127.0.0.1:8080/auth/`` in your browser. +3) Open ``http[s]://:/auth/`` in your browser. + Contents -------- @@ -81,6 +138,7 @@ Contents api authtypes + Indices and tables ------------------