Add s3 extension in keystone.conf sample.

- Document S3 functionality along the way.

Change-Id: I5525cd084aa16a33176c2ed0c3df53e9743072fc

4 files changed, 23 insertions, 5 deletions

diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst
index f6fb0239..d7ddfe89 100644
--- a/doc/source/configuration.rst
+++ b/doc/source/configuration.rst
@@ -56,6 +56,7 @@ values are organized into the following sections:
 * ``[DEFAULT]`` - general configuration
 * ``[sql]`` - optional storage backend configuration
 * ``[ec2]`` - Amazon EC2 authentication driver configuration
+* ``[s3]`` - Amazon S3 authentication driver configuration.
 * ``[identity]`` - identity system driver configuration
 * ``[catalog]`` - service catalog driver configuration
 * ``[token]`` - token driver configuration
diff --git a/doc/source/configuringservices.rst b/doc/source/configuringservices.rst
index 5410ffc7..653b3e66 100644
--- a/doc/source/configuringservices.rst
+++ b/doc/source/configuringservices.rst
@@ -241,9 +241,19 @@ Configuring Swift with S3 emulation to use Keystone
 Keystone supports validating S3 tokens using the same tokens as the
 generated EC2 tokens. When you have generated a pair of EC2 access
 token and secret you can access your swift cluster directly with the
-S3 api.
+S3 API.
 
-1. Configure the paste file for swift-proxy
+1. Ensure you have defined the S3 service in your `keystone.conf`. First, define the filter as follows::
+
+    [filter:s3_extension]
+    paste.filter_factory = keystone.contrib.s3:S3Extension.factory
+
+Then, ensure that the filter is being called by the admin_api pipeline, as follows::
+
+    [pipeline:admin_api]
+    pipeline = token_auth [....] ec2_extension s3_extension [...]
+
+2. Configure the paste file for swift-proxy
    (`/etc/swift/swift-proxy.conf` to use S3token and Swift3
    middleware.
 
@@ -292,7 +302,7 @@ S3 api.
     auth_token = ADMIN
     admin_token = ADMIN
 
-2. You can then access directly your Swift via the S3 API, here's an
+3. You can then access directly your Swift via the S3 API, here's an
    example with the `boto` library::
 
     import boto
diff --git a/etc/keystone.conf.sample b/etc/keystone.conf.sample
index 11961b18..933de95e 100644
--- a/etc/keystone.conf.sample
+++ b/etc/keystone.conf.sample
@@ -131,6 +131,9 @@ paste.filter_factory = keystone.contrib.admin_crud:CrudExtension.factory
 [filter:ec2_extension]
 paste.filter_factory = keystone.contrib.ec2:Ec2Extension.factory
 
+[filter:s3_extension]
+paste.filter_factory = keystone.contrib.s3:S3Extension.factory
+
 [filter:url_normalize]
 paste.filter_factory = keystone.middleware:NormalizingFilter.factory
 
@@ -144,7 +147,7 @@ paste.app_factory = keystone.service:admin_app_factory
 pipeline = url_normalize token_auth admin_token_auth xml_body json_body debug ec2_extension public_service
 
 [pipeline:admin_api]
-pipeline = url_normalize token_auth admin_token_auth xml_body json_body debug ec2_extension crud_extension admin_service
+pipeline = url_normalize token_auth admin_token_auth xml_body json_body debug ec2_extension s3_extension crud_extension admin_service
 
 [app:public_version_service]
 paste.app_factory = keystone.service:public_version_app_factory
diff --git a/keystone/contrib/s3/core.py b/keystone/contrib/s3/core.py
index 4b4b2b6c..0e3e1fe2 100644
--- a/keystone/contrib/s3/core.py
+++ b/keystone/contrib/s3/core.py
@@ -16,7 +16,11 @@
 
 """Main entry point into the S3 Credentials service.
 
-TODO-DOCS
+This service provides S3 token validation for services configured with the
+s3_token middleware to authorize S3 requests.
+
+This service uses the same credentials used by EC2. Refer to the documentation
+for the EC2 module for how to generate the required credentials.
 """
 
 import base64