Browse Source

Merge "doc: Add configuration reference"

Jenkins 1 year ago
parent
commit
50d18d50f1
2 changed files with 377 additions and 0 deletions
  1. 376
    0
      doc/source/configuration/index.rst
  2. 1
    0
      doc/source/index.rst

+ 376
- 0
doc/source/configuration/index.rst View File

@@ -0,0 +1,376 @@
1
+=============
2
+Configuration
3
+=============
4
+
5
+Django OpenStack Auth is configured through Django ``settings.py`` file.
6
+In most cases it is used combined with the OpenStack Dashboard,
7
+so the settings file will be ``local/local_settings.py`` file
8
+in your OpenStack Dashboard deployment.
9
+
10
+This page covers the configuration options referred by Django OpenStack Auth.
11
+
12
+:ref:`Some settings <settings-shared-with-horizon>` are also referred to
13
+by Horizon. Configure them carefully.
14
+
15
+General settings
16
+================
17
+
18
+``AUTHENTICATION_PLUGINS``
19
+--------------------------
20
+
21
+Default: ``['openstack_auth.plugin.password.PasswordPlugin', 'openstack_auth.plugin.token.TokenPlugin']``
22
+
23
+A list of authentication plugins to be used.
24
+In most cases, there is no need to configure this.
25
+
26
+``AVAILABLE_REGIONS``
27
+---------------------
28
+
29
+Default: ``None``
30
+
31
+A list of tuples which define multiple regions. The tuple format is
32
+``('http://{{ keystone_host }}:5000/v2.0', '{{ region_name }}')``. If any regions
33
+are specified the login form will have a dropdown selector for authenticating
34
+to the appropriate region, and there will be a region switcher dropdown in
35
+the site header when logged in.
36
+
37
+You should also define ``OPENSTACK_KEYSTONE_URL`` to indicate which of
38
+the regions is the default one.
39
+
40
+``OPENSTACK_API_VERSIONS``
41
+--------------------------
42
+
43
+Default::
44
+
45
+    {
46
+        "identity": 2.0,
47
+        ...,
48
+    }
49
+
50
+Overrides for OpenStack API versions. Use this setting to force the
51
+OpenStack dashboard to use a specific API version for a given service API.
52
+Django OpenStack Auth refers to only the ``"identity"`` entry.
53
+The current valid values are "2.0" or "3".
54
+
55
+.. note::
56
+
57
+   See `Horizon settings
58
+   <https://docs.openstack.org/developer/horizon/install/settings.html#openstack-api-versions>`__
59
+   for the full description of this setting.
60
+
61
+``OPENSTACK_ENDPOINT_TYPE``
62
+---------------------------
63
+
64
+Default: ``"publicURL"``
65
+
66
+A string which specifies the endpoint type to use for the endpoints in the
67
+Keystone service catalog. The default value for all services except for
68
+identity is ``"publicURL"``. The default value for the identity service is
69
+``"internalURL"``.
70
+
71
+``OPENSTACK_KEYSTONE_ADMIN_ROLES``
72
+----------------------------------
73
+
74
+Default: ``["admin"]``
75
+
76
+The list of roles that have administrator privileges in this OpenStack
77
+installation. This check is very basic and essentially only works with
78
+keystone v2.0 and v3 with the default policy file. The setting assumes there
79
+is a common ``admin`` like role(s) across services. Example uses of this
80
+setting are:
81
+
82
+* to rename the ``admin`` role to ``cloud-admin``
83
+* allowing multiple roles to have administrative privileges, like
84
+  ``["admin", "cloud-admin", "net-op"]``
85
+
86
+``OPENSTACK_KEYSTONE_DEFAULT_DOMAIN``
87
+-------------------------------------
88
+
89
+Default: ``"Default"``
90
+
91
+Overrides the default domain used when running on single-domain model
92
+with Keystone V3. All entities will be created in the default domain.
93
+
94
+.. note::
95
+
96
+   This value must be the name of the default domain, NOT the ID.
97
+   Also, you will most likely have a value in the keystone policy file like
98
+   ``"cloud_admin": "rule:admin_required and domain_id:<your domain id>"``.
99
+   This value must be the name of the domain whose ID is specified there.
100
+
101
+``OPENSTACK_KEYSTONE_MULTIDOMAIN_SUPPORT``
102
+------------------------------------------
103
+
104
+Default: ``False``
105
+
106
+Set this to True if running on multi-domain model. When this is enabled, it
107
+will require user to enter the Domain name in addition to username for login.
108
+
109
+``OPENSTACK_KEYSTONE_URL``
110
+--------------------------
111
+
112
+Default: ``"http://%s:5000/v2.0" % OPENSTACK_HOST``
113
+
114
+The full URL for the Keystone endpoint used for authentication. Unless you
115
+are using HTTPS, running your Keystone server on a nonstandard port, or using
116
+a nonstandard URL scheme you shouldn't need to touch this setting.
117
+
118
+``OPENSTACK_SSL_CACERT``
119
+------------------------
120
+
121
+Default: ``None``
122
+
123
+When unset or set to ``None`` the default CA certificate on the system is used
124
+for SSL verification.
125
+
126
+When set with the path to a custom CA certificate file, this overrides use of
127
+the default system CA certificate. This custom certificate is used to verify all
128
+connections to openstack services when making API calls.
129
+
130
+``OPENSTACK_SSL_NO_VERIFY``
131
+---------------------------
132
+
133
+Default: ``False``
134
+
135
+Disable SSL certificate checks in the OpenStack clients (useful for self-signed
136
+certificates).
137
+
138
+``OPENSTACK_TOKEN_HASH_ALGORITHM``
139
+----------------------------------
140
+
141
+Default: ``"md5"``
142
+
143
+The hash algorithm to use for authentication tokens. This must match the hash
144
+algorithm that the identity (Keystone) server and the auth_token middleware
145
+are using. Allowed values are the algorithms supported by Python's hashlib
146
+library.
147
+
148
+``OPENSTACK_TOKEN_HASH_ENABLED``
149
+--------------------------------
150
+
151
+(Deprecated)
152
+
153
+Default: ``True``
154
+
155
+Hashing tokens from Keystone keeps the Horizon session data smaller, but it
156
+doesn't work in some cases when using PKI tokens.  Uncomment this value and
157
+set it to False if using PKI tokens and there are 401 errors due to token
158
+hashing.
159
+
160
+This option is now marked as "deprecated" and will be removed in Ocata or a
161
+later release. PKI tokens currently work with hashing, and Keystone will soon
162
+deprecate usage of PKI tokens.
163
+
164
+``PASSWORD_EXPIRES_WARNING_THRESHOLD_DAYS``
165
+-------------------------------------------
166
+
167
+Default: ``-1``
168
+
169
+Password will have an expiration date when using keystone v3 and enabling the
170
+feature. This setting allows you to set the number of days that the user will
171
+be alerted prior to the password expiration. Once the password expires keystone
172
+will deny the access and users must contact an admin to change their password.
173
+Setting this value to ``N`` days means the user will be alerted when the
174
+password expires in less than ``N+1`` days. ``-1`` disables the feature.
175
+
176
+``POLICY_FILES``
177
+----------------
178
+
179
+Default: ``{'identity': 'keystone_policy.json', 'compute': 'nova_policy.json'}``
180
+
181
+This should essentially be the mapping of the contents of ``POLICY_FILES_PATH``
182
+to service types.  When policy.json files are added to ``POLICY_FILES_PATH``,
183
+they should be included here too.
184
+
185
+``POLICY_FILES_PATH``
186
+---------------------
187
+
188
+Default:  ``os.path.join(ROOT_PATH, "conf")``
189
+
190
+Specifies where service based policy files are located. These are used to
191
+define the policy rules actions are verified against.
192
+
193
+``SECURE_PROXY_ADDR_HEADER``
194
+----------------------------
195
+
196
+Default: ``False``
197
+
198
+If horizon is behind a proxy server and the proxy is configured, the IP address
199
+from request is passed using header variables inside the request. The header
200
+name depends on a proxy or a load-balancer. This setting specifies the name of
201
+the header with remote IP address. The main use is for authentication log
202
+(success or fail) displaing the IP address of the user.
203
+The commom value for this setting is ``HTTP_X_REAL_IP`` or
204
+``HTTP_X_FORWARDED_FOR``.
205
+If not present, then ``REMOTE_ADDR`` header is used. (``REMOTE_ADDR`` is the
206
+field of Django HttpRequest object which contains IP address of the client.)
207
+
208
+``SESSION_TIMEOUT``
209
+-------------------
210
+
211
+Default: ``"3600"``
212
+
213
+This ``SESSION_TIMEOUT`` is a method to supercede the token timeout with a
214
+shorter horizon session timeout (in seconds).  So if your token expires in
215
+60 minutes, a value of 1800 will log users out after 30 minutes.
216
+
217
+``TOKEN_DELETION_DISABLED``
218
+---------------------------
219
+
220
+Default: ``False``
221
+
222
+This setting allows deployers to control whether a token is deleted on log out.
223
+This can be helpful when there are often long running processes being run
224
+in the Horizon environment.
225
+
226
+``TOKEN_TIMEOUT_MARGIN``
227
+------------------------
228
+
229
+Default: ``0``
230
+
231
+A time margin in seconds to subtract from the real token's validity.
232
+An example usage is that the token can be valid once the middleware
233
+passed, and invalid (timed-out) during a view rendering and this
234
+generates authorization errors during the view rendering.
235
+By setting this value to some smaller seconds, you can avoid token
236
+expiration during a view rendering.
237
+
238
+``WEBROOT``
239
+-----------
240
+
241
+Default: ``"/"``
242
+
243
+Specifies the location where the access to the dashboard is configured in
244
+the web server.
245
+
246
+For example, if you're accessing the Dashboard via
247
+https://<your server>/dashboard, you would set this to ``"/dashboard/"``.
248
+
249
+.. note::
250
+
251
+    Additional settings may be required in the config files of your webserver
252
+    of choice. For example to make ``"/dashboard/"`` the web root in Apache,
253
+    the ``"sites-available/horizon.conf"`` requires a couple of additional
254
+    aliases set::
255
+
256
+        Alias /dashboard/static %HORIZON_DIR%/static
257
+
258
+        Alias /dashboard/media %HORIZON_DIR%/openstack_dashboard/static
259
+
260
+    Apache also requires changing your WSGIScriptAlias to reflect the desired
261
+    path.  For example, you'd replace ``/`` with ``/dashboard`` for the
262
+    alias.
263
+
264
+Web SSO (Single Sign On) settings
265
+=================================
266
+
267
+``WEBSSO_ENABLED``
268
+------------------
269
+
270
+Default: ``False``
271
+
272
+Enables keystone web single-sign-on if set to True. For this feature to work,
273
+make sure that you are using Keystone V3 and Django OpenStack Auth V1.2.0 or
274
+later.
275
+
276
+``WEBSSO_INITIAL_CHOICE``
277
+-------------------------
278
+
279
+Default: ``"credentials"``
280
+
281
+Determines the default authentication mechanism. When user lands on the login
282
+page, this is the first choice they will see.
283
+
284
+``WEBSSO_CHOICES``
285
+------------------
286
+
287
+Default::
288
+
289
+        (
290
+          ("credentials", _("Keystone Credentials")),
291
+          ("oidc", _("OpenID Connect")),
292
+          ("saml2", _("Security Assertion Markup Language"))
293
+        )
294
+
295
+This is the list of authentication mechanisms available to the user. It
296
+includes Keystone federation protocols such as OpenID Connect and SAML, and
297
+also keys that map to specific identity provider and federation protocol
298
+combinations (as defined in ``WEBSSO_IDP_MAPPING``). The list of choices is
299
+completely configurable, so as long as the id remains intact. Do not remove
300
+the credentials mechanism unless you are sure. Once removed, even admins will
301
+have no way to log into the system via the dashboard.
302
+
303
+``WEBSSO_IDP_MAPPING``
304
+----------------------
305
+
306
+Default: ``{}``
307
+
308
+A dictionary of specific identity provider and federation protocol combinations.
309
+From the selected authentication mechanism, the value will be looked up as keys
310
+in the dictionary. If a match is found, it will redirect the user to a identity
311
+provider and federation protocol specific WebSSO endpoint in keystone, otherwise
312
+it will use the value as the protocol_id when redirecting to the WebSSO by
313
+protocol endpoint.
314
+
315
+Example::
316
+
317
+        WEBSSO_CHOICES =  (
318
+            ("credentials", _("Keystone Credentials")),
319
+            ("oidc", _("OpenID Connect")),
320
+            ("saml2", _("Security Assertion Markup Language")),
321
+            ("acme_oidc", "ACME - OpenID Connect"),
322
+            ("acme_saml2", "ACME - SAML2")
323
+        )
324
+
325
+        WEBSSO_IDP_MAPPING = {
326
+            "acme_oidc": ("acme", "oidc"),
327
+            "acme_saml2": ("acme", "saml2")
328
+        }
329
+
330
+.. note::
331
+  The value is expected to be a tuple formatted as: (<idp_id>, <protocol_id>).
332
+
333
+K2K (Keystone to Keystone) Federation settings
334
+==============================================
335
+
336
+``KEYSTONE_PROVIDER_IDP_NAME``
337
+------------------------------
338
+
339
+Default: ``Local Keystone``
340
+
341
+The Keystone Provider drop down uses Keystone to Keystone federation
342
+to switch between Keystone service providers.
343
+This sets display name for Identity Provider (dropdown display name).
344
+
345
+``KEYSTONE_PROVIDER_IDP_ID``
346
+----------------------------
347
+
348
+Default:: ``localkeystone``
349
+
350
+This ID is used for only for comparison with the service provider IDs.
351
+This ID should not match any service provider IDs.
352
+
353
+.. _settings-shared-with-horizon:
354
+
355
+Settings shared with Horizon
356
+============================
357
+
358
+The following settings in Django OpenStack Auth are also used by Horizon.
359
+
360
+* ``AVAILABLE_REGIONS``
361
+* ``OPENSTACK_API_VERSIONS``
362
+* ``OPENSTACK_KEYSTONE_URL``
363
+* ``OPENSTACK_ENDPOINT_TYPE``
364
+* ``OPENSTACK_SSL_CACERT``
365
+* ``OPENSTACK_SSL_NO_VERIFY``
366
+* ``WEBROOT``
367
+
368
+Django OpenStack Auth also refers to the following Django settings.
369
+For more detail, see `Django settings documentation
370
+<https://docs.djangoproject.com/en/1.11/ref/settings/#auth>`__.
371
+They are usually configured as part of Horizon settings.
372
+
373
+* ``LOGIN_REDIRECT_URL``
374
+* ``LOGIN_URL``
375
+* ``SESSION_ENGINE``
376
+* ``USE_TZ``

+ 1
- 0
doc/source/index.rst View File

@@ -12,6 +12,7 @@ The current version is designed to work with the Keystone V2 or V3 API.
12 12
    :maxdepth: 2
13 13
 
14 14
    install/index
15
+   configuration/index
15 16
    reference/index
16 17
 
17 18
 * :ref:`genindex`

Loading…
Cancel
Save