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
6 | 6 | consider the key manager behavior you wish to encapsulate and the OpenStack |
7 | 7 | deployments on which your application will run. |
8 | 8 | |
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 | |
22 | 80 | frequently inherited from ``oslo.context.RequestContext``. This object |
23 | 81 | represents information that is contained in the current request, and is |
24 | 82 | usually populated in the WSGI pipeline. The information contained in this |
47 | 105 | ctxt = context.RequestContext(auth_token=keystone_client.auth_token, |
48 | 106 | tenant=project_list[0].id) |
49 | 107 | |
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. | |
52 | 122 | |
53 | 123 | **Example. Creating and storing a key.** |
54 | 124 |