Codebase list python-castellan / 5d20ea2
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 Fernando Diaz 8 years ago
1 changed file(s) with 85 addition(s) and 15 deletion(s). Raw diff Collapse all Expand all
+85
-15
doc/source/usage.rst less more
66 consider the key manager behavior you wish to encapsulate and the OpenStack
77 deployments on which your application will run.
88
9 Basic usage
10 ~~~~~~~~~~~
11
12 Castellan works on the principle of providing an abstracted key manager based
13 on your configuration. In this manner, several different management services
14 can be supported through a single interface.
15
16 In addition to the key manager, Castellan also provides primitives for
17 various types of secrets (for example, asymmetric keys, simple passphrases,
18 and certificates). These primitives are used in conjunction with the key
19 manager to create, store, retrieve, and destroy managed secrets.
20
21 Another fundamental concept to using Castellan is the context object, most
9 Authentication
10 ~~~~~~~~~~~~~~
11
12 A fundamental concept to using Castellan is the credential context object.
13 Castellan supports the following credentials for authentication:
14
15 * Token
16 * Password
17 * Keystone Token
18 * Keystone Password
19
20 In order to use these credentials, valid configuration parameters must be
21 provided.
22
23 .. code:: ini
24
25 # token credential
26 # token variable not required, token can be obtained from context
27 [castellan]
28 auth_type = 'token'
29 token = '5b4de0bb77064f289f7cc58e33bea8c7'
30
31 # password credential
32 [castellan]
33 auth_type = 'password'
34 username = 'admin'
35 password = 'passw0rd1'
36
37 # keystone token credential
38 [castellan]
39 auth_type = 'keystone_token'
40 token = '5b4de0bb77064f289f7cc58e33bea8c7'
41 project_id = 'a1e19934af81420d980a5d02b4afe9fb'
42
43 # keystone password credential
44 [castellan]
45 auth_type = 'keystone_password'
46 username = 'admin'
47 password = 'passw0rd1'
48 project_id = '1099302ec608486f9879ba2466c60720'
49 user_domain_name = 'default'
50
51 .. note::
52
53 Keystone Token and Password authentication is achieved using
54 keystoneclient.auth.identity.v3 Token and Password auth plugins.
55 There are a variety of different variables which can be set for the
56 keystone credential options.
57
58
59 The configuration must be passed to a credential factory which will
60 generate the appropriate context.
61
62 .. code:: python
63
64 from castellan.common import utils
65
66 CONF = <your_configuration>
67 context = utils.credential_factory(conf=CONF, context=None)
68
69 Now you can go ahead and pass the context and use it for authentication.
70
71 .. note::
72
73 There is a special case for a token. Since a user may not want to store a
74 token in the configuration, the user can pass a context object containing
75 an 'auth_token' as well as a configuration file with 'token' as the
76 auth type.
77
78
79 An oslo context object can also be used for authentication, it is
2280 frequently inherited from ``oslo.context.RequestContext``. This object
2381 represents information that is contained in the current request, and is
2482 usually populated in the WSGI pipeline. The information contained in this
47105 ctxt = context.RequestContext(auth_token=keystone_client.auth_token,
48106 tenant=project_list[0].id)
49107
50 ctxt can then be passed into any key_manager api call which requires
51 a RequestContext object.
108 ctxt can then be passed into any key_manager api call.
109
110
111 Basic usage
112 ~~~~~~~~~~~
113
114 Castellan works on the principle of providing an abstracted key manager based
115 on your configuration. In this manner, several different management services
116 can be supported through a single interface.
117
118 In addition to the key manager, Castellan also provides primitives for
119 various types of secrets (for example, asymmetric keys, simple passphrases,
120 and certificates). These primitives are used in conjunction with the key
121 manager to create, store, retrieve, and destroy managed secrets.
52122
53123 **Example. Creating and storing a key.**
54124