From 5d20ea22a88db40d0a8f43c6573b2b041973e3d4 Mon Sep 17 00:00:00 2001
From: Fernando Diaz <diazjf@us.ibm.com>
Date: Fri, 29 Jan 2016 11:58:48 -0600
Subject: [PATCH] Add Credential Authentication Usage Documentation

This patch adds documentation on using the new credential
object. It is the last of several patches which will implement the
"Allow different Keystone Auth Support in Castellan" blueprint.

Change-Id: I22608e83f46b4cc77ad6a5e41a95389751b0ecbf
Implements: blueprint remove-keystone-dependency
---
 doc/source/usage.rst | 94 ++++++++++++++++++++++++++++++++++++++------
 1 file changed, 82 insertions(+), 12 deletions(-)

diff --git a/doc/source/usage.rst b/doc/source/usage.rst
index 9ea6a824..979a40a0 100644
--- a/doc/source/usage.rst
+++ b/doc/source/usage.rst
@@ -7,19 +7,77 @@ incorporating this package into your applications, care should be taken to
 consider the key manager behavior you wish to encapsulate and the OpenStack
 deployments on which your application will run.
 
-Basic usage
-~~~~~~~~~~~
+Authentication
+~~~~~~~~~~~~~~
 
-Castellan works on the principle of providing an abstracted key manager based
-on your configuration. In this manner, several different management services
-can be supported through a single interface.
+A fundamental concept to using Castellan is the credential context object.
+Castellan supports the following credentials for authentication:
 
-In addition to the key manager, Castellan also provides primitives for
-various types of secrets (for example, asymmetric keys, simple passphrases,
-and certificates). These primitives are used in conjunction with the key
-manager to create, store, retrieve, and destroy managed secrets.
+* Token
+* Password
+* Keystone Token
+* Keystone Password
 
-Another fundamental concept to using Castellan is the context object, most
+In order to use these credentials, valid configuration parameters must be
+provided.
+
+.. code:: ini
+
+  # token credential
+  # token variable not required, token can be obtained from context
+  [castellan]
+  auth_type = 'token'
+  token = '5b4de0bb77064f289f7cc58e33bea8c7'
+
+  # password credential
+  [castellan]
+  auth_type = 'password'
+  username = 'admin'
+  password = 'passw0rd1'
+
+  # keystone token credential
+  [castellan]
+  auth_type = 'keystone_token'
+  token = '5b4de0bb77064f289f7cc58e33bea8c7'
+  project_id = 'a1e19934af81420d980a5d02b4afe9fb'
+
+  # keystone password credential
+  [castellan]
+  auth_type = 'keystone_password'
+  username = 'admin'
+  password = 'passw0rd1'
+  project_id = '1099302ec608486f9879ba2466c60720'
+  user_domain_name = 'default'
+
+.. note::
+
+  Keystone Token and Password authentication is achieved using
+  keystoneclient.auth.identity.v3 Token and Password auth plugins.
+  There are a variety of different variables which can be set for the
+  keystone credential options.
+
+
+The configuration must be passed to a credential factory which will
+generate the appropriate context.
+
+.. code:: python
+
+  from castellan.common import utils
+
+  CONF = <your_configuration>
+  context = utils.credential_factory(conf=CONF, context=None)
+
+Now you can go ahead and pass the context and use it for authentication.
+
+.. note::
+
+  There is a special case for a token. Since a user may not want to store a
+  token in the configuration, the user can pass a context object containing
+  an 'auth_token' as well as a configuration file with 'token' as the
+  auth type.
+
+
+An oslo context object can also be used for authentication, it is
 frequently inherited from ``oslo.context.RequestContext``. This object
 represents information that is contained in the current request, and is
 usually populated in the WSGI pipeline. The information contained in this
@@ -48,8 +106,20 @@ that is being abstracted.
     ctxt = context.RequestContext(auth_token=keystone_client.auth_token,
                                   tenant=project_list[0].id)
 
-ctxt can then be passed into any key_manager api call which requires
-a RequestContext object.
+ctxt can then be passed into any key_manager api call.
+
+
+Basic usage
+~~~~~~~~~~~
+
+Castellan works on the principle of providing an abstracted key manager based
+on your configuration. In this manner, several different management services
+can be supported through a single interface.
+
+In addition to the key manager, Castellan also provides primitives for
+various types of secrets (for example, asymmetric keys, simple passphrases,
+and certificates). These primitives are used in conjunction with the key
+manager to create, store, retrieve, and destroy managed secrets.
 
 **Example. Creating and storing a key.**