Merge "Add Credential Authentication Usage Documentation"
Jenkins authored 8 years ago
Gerrit Code Review committed 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 |