summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorPrashanth Pai <ppai@redhat.com>2013-09-23 11:47:21 +0530
committerPrashanth Pai <ppai@redhat.com>2013-09-23 11:57:31 +0530
commitaf2cbe8a5bec2b7971de137416d6e62ac1b96498 (patch)
tree42de6bfc2b380f27512956a7c0392ede9e0889e1 /doc
parent728157e52fe3212d50edfc17fcd72e1aaf9a6e76 (diff)
Minor swiftkerbauth changes
* Replaced python-webob with swift.common.swob * Use swift memcached instead of python memcached * Added optional debugging headers to swift-auth script * Swiftkerbauth and Apachekerbauth are now a single RPM * Updates to httpd conf file to specify Kerberos principal * Added setupy.py, makerpm.sh, .gitignore and MANIFEST.in * RPM is now generated by bdist_rpm using setup.py and not from spec files TODO -> Documentation changes in doc/ * Steps to setup kerberos environment * Swiftkerbauth usage and examples -> Testing swiftkerbauth * Investigate borrowing tests from tempauth.py and its dependencies * Write a python client script to test swiftkerbauth Signed-off-by: Prashanth Pai <ppai@redhat.com>
Diffstat (limited to 'doc')
-rw-r--r--doc/DOCUMENTATION299
1 files changed, 299 insertions, 0 deletions
diff --git a/doc/DOCUMENTATION b/doc/DOCUMENTATION
new file mode 100644
index 0000000..5b36b24
--- /dev/null
+++ b/doc/DOCUMENTATION
@@ -0,0 +1,299 @@
+Kerberos Authentication Filter for Red Hat Storage and OpenStack Swift
+----------------------------------------------------------------------
+
+Red Hat Storage not only provides file system access to its data, but
+also object-level access. The latter is implemented with OpenStack
+Swift, and allows containers and objects to be stored and retrieved
+with an HTTP-based API.
+
+Red Hat Storage 2.0 comes with a simple authentication filter that
+defines user accounts as a static list in the Swift configuration
+file. For this project, we implemented a new authentication filter
+that uses Kerberos tickets for single sign on authentication, and
+grants administrator permissions based on the user's group membership
+in a directory service like Red Hat Enterprise Linux Identity
+Management or Microsoft Active Directory.
+
+* Building
+
+To build the swiftkerbauth and apachekerbauth RPM packages, change
+into the respective directory and run
+
+ ./build.sh
+
+* Installation
+
+** Swift Server
+
+Install the swiftkerbauth RPM on all Red Hat Storage nodes that will
+provide object-level access via Swift.
+
+To active the Kerberos authentication filter, add "kerbauth" in the
+/etc/swift/proxy-server.conf pipeline parameter:
+
+ [pipeline:main]
+ pipeline = healthcheck cache kerbauth proxy-server
+
+Set the URL of the Apache server that will be used for authentication
+with the ext_authentication_url parameter in the same file:
+
+ [filter:kerbauth]
+ paste.filter_factory = swiftkerbauth:filter_factory
+ ext_authentication_url = http://AUTHENTICATION_SERVER/cgi-bin/swift-auth
+
+If the Swift server is not one of your Gluster nodes, edit
+/etc/swift/fs.conf and change the following lines in the DEFAULT
+section:
+
+ mount_ip = RHS_NODE_HOSTNAME
+ remote_cluster = yes
+
+Activate the changes by running
+
+ swift-init main restart
+
+For troubleshooting, check /var/log/messages.
+
+** Authentication Server
+
+On the authentication server, install the apachekerbauth package.
+
+Edit /etc/httpd/conf.d/swift-auth.conf and set the KrbAuthRealms and
+Krb5KeyTab parameters.
+
+The keytab must contain a HTTP/$HOSTNAME principal. Usually, you will
+have to create the Kerberos principal on the KDC, export it, and copy
+it to a keytab file on the Apache server.
+
+If SELinux is enabled, allow Apache to connect to memcache and
+activate the changes by running
+
+ setsebool -P httpd_can_network_connect 1
+ setsebool -P httpd_can_network_memcache 1
+
+ service httpd reload
+
+For troubleshooting, see /var/log/httpd/error_log.
+
+* Testing
+
+The tests were done with curl on a machine set up as an IDM client,
+using the Gluster volume rhs_ufo1.
+
+In IDM, we created the following user groups:
+
+- auth_reseller_admin
+ Users in this group get full access to all Swift accounts.
+
+- auth_rhs_ufo1
+ Users in this group get full access to the rhs_ufo1 Swift account.
+
+Next, we created the following users in IDM:
+
+- auth_admin
+ Member of the auth_reseller_admin group
+
+- rhs_ufo1_admin
+ Member of the auth_rhs_ufo1 group
+
+- jsmith
+ No relevant group membership
+
+The authentication tokens were then retrieved with the following
+commands:
+
+ kinit auth_admin
+ curl -v -u : --negotiate --location-trusted \
+ http://rhs1.example.com:8080/auth/v1.0
+
+ kinit rhs_ufo1_admin
+ curl -v -u : --negotiate --location-trusted \
+ http://rhs1.example.com:8080/auth/v1.0
+
+ kinit jsmith
+ curl -v -u : --negotiate --location-trusted \
+ http://rhs1.example.com:8080/auth/v1.0
+
+Each of these commands should output the following two lines:
+
+< X-Auth-Token: AUTH_tk4097146ed3814e026209556eeb121fe0
+...
+<pre>1365195860 / auth_admin,auth_reseller_admin</pre>
+
+The first line contains the authentication token that is used in
+subsequent requests.
+
+The second line is printed by the swift-auth CGI script for debugging
+- it lists the token expiration (in seconds since January 1, 1970) and
+the user's groups.
+
+Next, we try to get information about the Swift account, replacing the
+AUTH_tk* with one of the tokens we got with the commands above. This
+should display statistics, and the list of container names when used
+with the the admin users. For jsmith, you should get a 403 Forbidden
+error.
+
+ curl -v -X GET \
+ -H 'X-Auth-Token: AUTH_tk4097146ed3814e026209556eeb121fe0' \
+ http://rhs1.example.com:8080/v1/AUTH_rhs_ufo1
+
+With one of the admin accounts, create a new container and a new
+object in that container:
+
+ curl -v -X PUT \
+ -H 'X-Auth-Token: AUTH_tk4097146ed3814e026209556eeb121fe0' \
+ http://rhs1.example.com:8080/v1/AUTH_rhs_ufo1/pictures
+
+ curl -v -X PUT \
+ -H 'X-Auth-Token: AUTH_tk4097146ed3814e026209556eeb121fe0' \
+ -H 'Content-Length: 0' \
+ http://rhs1.example.com:8080/v1/AUTH_rhs_ufo1/pictures/pic1.png
+
+Grant permission for jsmith to list and download objects from the
+pictures container:
+
+ curl -v -X POST \
+ -H 'X-Auth-Token: AUTH_tkdbf7725c1e4ad1ebe9ab0d7098d425f2' \
+ -H 'X-Container-Read: jsmith' \
+ http://rhs1.example.com:8080/v1/AUTH_rhs_ufo1/pictures
+
+List the container contents using the authentication token for jsmith:
+
+ curl -v -X GET \
+ -H 'X-Auth-Token: AUTH_tkef8b417ac0c2a73a80ab3b8db85254e2' \
+ http://rhs1.example.com:8080/v1/AUTH_rhs_ufo1/pictures
+
+Try to access a resource without an authentication token. This will
+return a 303 redirect:
+
+ curl -v -X GET \
+ http://rhs1.example.com:8080/v1/AUTH_rhs_ufo1/pictures/pic1.png
+
+For curl to follow the redirect, you need to specify additional
+options. With these, and with a current Kerberos ticket, you should
+get the Kerberos user's cached authentication token, or a new one if
+the previous token has expired.
+
+ curl -v -u : --negotiate --location-trusted -X GET \
+ http://rhs1.example.com:8080/v1/AUTH_rhs_ufo1/pictures/pic1.png
+
+* Implementation Details
+
+** Architecture
+
+The Swift API is HTTP-based. As described in the Swift documentation
+[1], clients first make a request to an authentication URL, providing
+a username and password. The reply contains a token which is used in
+all subsequent requests.
+
+Swift has a chain of filters through which all client requests go. The
+filters to use are configured with the pipeline parameter in
+/etc/swift/proxy-server.conf:
+
+ [pipeline:main]
+ pipeline = healthcheck cache tempauth proxy-server
+
+For the single sign authentication, we added a new filter called
+"kerbauth" and put it into the filter pipeline in place of tempauth.
+
+The filter checks the URL for each client request. If it matches the
+authentication URL, the client is redirected to a URL on a different
+server. The URL is handled by a CGI script, which is set up to
+authenticate the client with Kerberos negotiation, retrieve the user's
+system groups [2], store them in a memcache ring shared with the Swift
+server, and return the authentication token to the client.
+
+When the client provides the token as part of a resource request, the
+kerbauth filter checks it against its memcache, grants administrator
+rights based on the group membership retrieved from memcache, and
+either grants or denies the resource access.
+
+[1] http://docs.openstack.org/api/openstack-object-storage/1.0/content/authentication-object-dev-guide.html
+
+[2] The user data and system groups are usually provided by Red Hat
+ Enterprise Linux identity Management or Microsoft Active
+ Directory. The script relies on the system configuration to be set
+ accordingly (/etc/nsswitch.conf).
+
+** swiftkerbauth.py
+
+The script /usr/lib/python2.6/site-packages/swiftkerbauth.py began as
+a copy of the tempauth.py script from
+/usr/lib/python2.6/site-packages/swift/common/middleware. It contains
+the following modifications, among others:
+
+In the __init__ method, we read the ext_authentication_url parameter
+from /etc/swift/proxy-server.conf. This is the URL that clients are
+redirected to when they access either the Swift authentication URL, or
+when they request a resource without a valid authentication token.
+
+The configuration in proxy-server.conf looks like this:
+
+ [filter:kerbauth]
+ paste.filter_factory = swiftkerbauth:filter_factory
+ ext_authentication_url = http://rhel6-4.localdomain/cgi-bin/swift-auth
+
+The authorize method was changed so that global administrator rights
+are granted if the user is a member of the auth_reseller_admin
+group. Administrator rights for a specific account like vol1 are
+granted if the user is a member of the auth_vol1 group. [3]
+
+The denied_response method was changed to return a HTTP redirect to
+the external authentication URL if no valid token was provided by the
+client.
+
+Most of the handle_get_token method was moved to the external
+authentication script. This method now returns a HTTP redirect.
+
+In the __call__ and get_groups method, we removed support for the
+HTTP_AUTHORIZATION header, which is only needed when Amazon S3 is
+used.
+
+Like tempauth.py, swiftkerbauth.py uses a Swift wrapper to access
+memcache. This wrapper converts the key to an MD5 hash and uses the
+hash value to determine on which of a pre-defined list of servers to
+store the data.
+
+[3] "auth" is the default reseller prefix, and would be different if
+ the reseller_prefix parameter in proxy-server.conf was set.
+
+** swift-auth CGI Script
+
+swift-auth resides on an Apache server and assumes that Apache is
+configured to authenticate the user before this script is
+executed. The script retrieves the username from the REMOTE_USER
+environment variable, and checks if there already is a token for this
+user in the memcache ring. If not, it generates a new one, retrieves
+the user's system groups with "id -Gn USERNAME", stores this
+information in the memcache ring, and returns the token to the client.
+
+For the Swift filter to be able to find the information, it was
+important to use the Swift memcached module. Because we don't want to
+require a full Swift installation on the authentication server,
+/usr/lib/python2.6/site-packages/swift/common/memcached.py from the
+Swift server was copied to /var/www/cgi-bin on the Apache server.
+
+To allow the CGI script to connect to memcache, the SELinux booleans
+httpd_can_network_connect and httpd_can_network_memcache had to be
+set.
+
+The tempauth filter uses the uuid module to generate token
+strings. This module creates and runs temporary files, which leads to
+AVC denial messages in /var/log/audit/audit.log when used from an
+Apache CGI script. While the module still works, the audit log would
+grow quickly. Instead of writing an SELinux policy module to allow or
+to silently ignore these accesses, the swift-auth script uses the
+"random" module for generating token strings.
+
+Red Hat Enterprise Linux 6 comes with Python 2.6 which only provides
+method to list the locally defined user groups. To include groups from
+Red Hat Enterprise Linux Identity Management and in the future from
+Active Directory, the "id" command is run in a subprocess.
+
+* Reference Material
+
+Red Hat Storage Administration Guide:
+https://access.redhat.com/knowledge/docs/Red_Hat_Storage/
+
+Swift Documentation:
+http://docs.openstack.org/developer/swift/