Merge "doc: Add configuration reference"
This commit is contained in:
Jenkins
376
doc/source/configuration/index.rst
Normal file
376
doc/source/configuration/index.rst
Normal file
@@ -0,0 +1,376 @@
|
|||||||
|
=============
|
||||||
|
Configuration
|
||||||
|
=============
|
||||||
|
|
||||||
|
Django OpenStack Auth is configured through Django ``settings.py`` file.
|
||||||
|
In most cases it is used combined with the OpenStack Dashboard,
|
||||||
|
so the settings file will be ``local/local_settings.py`` file
|
||||||
|
in your OpenStack Dashboard deployment.
|
||||||
|
|
||||||
|
This page covers the configuration options referred by Django OpenStack Auth.
|
||||||
|
|
||||||
|
:ref:`Some settings <settings-shared-with-horizon>` are also referred to
|
||||||
|
by Horizon. Configure them carefully.
|
||||||
|
|
||||||
|
General settings
|
||||||
|
================
|
||||||
|
|
||||||
|
``AUTHENTICATION_PLUGINS``
|
||||||
|
--------------------------
|
||||||
|
|
||||||
|
Default: ``['openstack_auth.plugin.password.PasswordPlugin', 'openstack_auth.plugin.token.TokenPlugin']``
|
||||||
|
|
||||||
|
A list of authentication plugins to be used.
|
||||||
|
In most cases, there is no need to configure this.
|
||||||
|
|
||||||
|
``AVAILABLE_REGIONS``
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
Default: ``None``
|
||||||
|
|
||||||
|
A list of tuples which define multiple regions. The tuple format is
|
||||||
|
``('http://{{ keystone_host }}:5000/v2.0', '{{ region_name }}')``. If any regions
|
||||||
|
are specified the login form will have a dropdown selector for authenticating
|
||||||
|
to the appropriate region, and there will be a region switcher dropdown in
|
||||||
|
the site header when logged in.
|
||||||
|
|
||||||
|
You should also define ``OPENSTACK_KEYSTONE_URL`` to indicate which of
|
||||||
|
the regions is the default one.
|
||||||
|
|
||||||
|
``OPENSTACK_API_VERSIONS``
|
||||||
|
--------------------------
|
||||||
|
|
||||||
|
Default::
|
||||||
|
|
||||||
|
{
|
||||||
|
"identity": 2.0,
|
||||||
|
...,
|
||||||
|
}
|
||||||
|
|
||||||
|
Overrides for OpenStack API versions. Use this setting to force the
|
||||||
|
OpenStack dashboard to use a specific API version for a given service API.
|
||||||
|
Django OpenStack Auth refers to only the ``"identity"`` entry.
|
||||||
|
The current valid values are "2.0" or "3".
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
See `Horizon settings
|
||||||
|
<https://docs.openstack.org/developer/horizon/install/settings.html#openstack-api-versions>`__
|
||||||
|
for the full description of this setting.
|
||||||
|
|
||||||
|
``OPENSTACK_ENDPOINT_TYPE``
|
||||||
|
---------------------------
|
||||||
|
|
||||||
|
Default: ``"publicURL"``
|
||||||
|
|
||||||
|
A string which specifies the endpoint type to use for the endpoints in the
|
||||||
|
Keystone service catalog. The default value for all services except for
|
||||||
|
identity is ``"publicURL"``. The default value for the identity service is
|
||||||
|
``"internalURL"``.
|
||||||
|
|
||||||
|
``OPENSTACK_KEYSTONE_ADMIN_ROLES``
|
||||||
|
----------------------------------
|
||||||
|
|
||||||
|
Default: ``["admin"]``
|
||||||
|
|
||||||
|
The list of roles that have administrator privileges in this OpenStack
|
||||||
|
installation. This check is very basic and essentially only works with
|
||||||
|
keystone v2.0 and v3 with the default policy file. The setting assumes there
|
||||||
|
is a common ``admin`` like role(s) across services. Example uses of this
|
||||||
|
setting are:
|
||||||
|
|
||||||
|
* to rename the ``admin`` role to ``cloud-admin``
|
||||||
|
* allowing multiple roles to have administrative privileges, like
|
||||||
|
``["admin", "cloud-admin", "net-op"]``
|
||||||
|
|
||||||
|
``OPENSTACK_KEYSTONE_DEFAULT_DOMAIN``
|
||||||
|
-------------------------------------
|
||||||
|
|
||||||
|
Default: ``"Default"``
|
||||||
|
|
||||||
|
Overrides the default domain used when running on single-domain model
|
||||||
|
with Keystone V3. All entities will be created in the default domain.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
This value must be the name of the default domain, NOT the ID.
|
||||||
|
Also, you will most likely have a value in the keystone policy file like
|
||||||
|
``"cloud_admin": "rule:admin_required and domain_id:<your domain id>"``.
|
||||||
|
This value must be the name of the domain whose ID is specified there.
|
||||||
|
|
||||||
|
``OPENSTACK_KEYSTONE_MULTIDOMAIN_SUPPORT``
|
||||||
|
------------------------------------------
|
||||||
|
|
||||||
|
Default: ``False``
|
||||||
|
|
||||||
|
Set this to True if running on multi-domain model. When this is enabled, it
|
||||||
|
will require user to enter the Domain name in addition to username for login.
|
||||||
|
|
||||||
|
``OPENSTACK_KEYSTONE_URL``
|
||||||
|
--------------------------
|
||||||
|
|
||||||
|
Default: ``"http://%s:5000/v2.0" % OPENSTACK_HOST``
|
||||||
|
|
||||||
|
The full URL for the Keystone endpoint used for authentication. Unless you
|
||||||
|
are using HTTPS, running your Keystone server on a nonstandard port, or using
|
||||||
|
a nonstandard URL scheme you shouldn't need to touch this setting.
|
||||||
|
|
||||||
|
``OPENSTACK_SSL_CACERT``
|
||||||
|
------------------------
|
||||||
|
|
||||||
|
Default: ``None``
|
||||||
|
|
||||||
|
When unset or set to ``None`` the default CA certificate on the system is used
|
||||||
|
for SSL verification.
|
||||||
|
|
||||||
|
When set with the path to a custom CA certificate file, this overrides use of
|
||||||
|
the default system CA certificate. This custom certificate is used to verify all
|
||||||
|
connections to openstack services when making API calls.
|
||||||
|
|
||||||
|
``OPENSTACK_SSL_NO_VERIFY``
|
||||||
|
---------------------------
|
||||||
|
|
||||||
|
Default: ``False``
|
||||||
|
|
||||||
|
Disable SSL certificate checks in the OpenStack clients (useful for self-signed
|
||||||
|
certificates).
|
||||||
|
|
||||||
|
``OPENSTACK_TOKEN_HASH_ALGORITHM``
|
||||||
|
----------------------------------
|
||||||
|
|
||||||
|
Default: ``"md5"``
|
||||||
|
|
||||||
|
The hash algorithm to use for authentication tokens. This must match the hash
|
||||||
|
algorithm that the identity (Keystone) server and the auth_token middleware
|
||||||
|
are using. Allowed values are the algorithms supported by Python's hashlib
|
||||||
|
library.
|
||||||
|
|
||||||
|
``OPENSTACK_TOKEN_HASH_ENABLED``
|
||||||
|
--------------------------------
|
||||||
|
|
||||||
|
(Deprecated)
|
||||||
|
|
||||||
|
Default: ``True``
|
||||||
|
|
||||||
|
Hashing tokens from Keystone keeps the Horizon session data smaller, but it
|
||||||
|
doesn't work in some cases when using PKI tokens. Uncomment this value and
|
||||||
|
set it to False if using PKI tokens and there are 401 errors due to token
|
||||||
|
hashing.
|
||||||
|
|
||||||
|
This option is now marked as "deprecated" and will be removed in Ocata or a
|
||||||
|
later release. PKI tokens currently work with hashing, and Keystone will soon
|
||||||
|
deprecate usage of PKI tokens.
|
||||||
|
|
||||||
|
``PASSWORD_EXPIRES_WARNING_THRESHOLD_DAYS``
|
||||||
|
-------------------------------------------
|
||||||
|
|
||||||
|
Default: ``-1``
|
||||||
|
|
||||||
|
Password will have an expiration date when using keystone v3 and enabling the
|
||||||
|
feature. This setting allows you to set the number of days that the user will
|
||||||
|
be alerted prior to the password expiration. Once the password expires keystone
|
||||||
|
will deny the access and users must contact an admin to change their password.
|
||||||
|
Setting this value to ``N`` days means the user will be alerted when the
|
||||||
|
password expires in less than ``N+1`` days. ``-1`` disables the feature.
|
||||||
|
|
||||||
|
``POLICY_FILES``
|
||||||
|
----------------
|
||||||
|
|
||||||
|
Default: ``{'identity': 'keystone_policy.json', 'compute': 'nova_policy.json'}``
|
||||||
|
|
||||||
|
This should essentially be the mapping of the contents of ``POLICY_FILES_PATH``
|
||||||
|
to service types. When policy.json files are added to ``POLICY_FILES_PATH``,
|
||||||
|
they should be included here too.
|
||||||
|
|
||||||
|
``POLICY_FILES_PATH``
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
Default: ``os.path.join(ROOT_PATH, "conf")``
|
||||||
|
|
||||||
|
Specifies where service based policy files are located. These are used to
|
||||||
|
define the policy rules actions are verified against.
|
||||||
|
|
||||||
|
``SECURE_PROXY_ADDR_HEADER``
|
||||||
|
----------------------------
|
||||||
|
|
||||||
|
Default: ``False``
|
||||||
|
|
||||||
|
If horizon is behind a proxy server and the proxy is configured, the IP address
|
||||||
|
from request is passed using header variables inside the request. The header
|
||||||
|
name depends on a proxy or a load-balancer. This setting specifies the name of
|
||||||
|
the header with remote IP address. The main use is for authentication log
|
||||||
|
(success or fail) displaing the IP address of the user.
|
||||||
|
The commom value for this setting is ``HTTP_X_REAL_IP`` or
|
||||||
|
``HTTP_X_FORWARDED_FOR``.
|
||||||
|
If not present, then ``REMOTE_ADDR`` header is used. (``REMOTE_ADDR`` is the
|
||||||
|
field of Django HttpRequest object which contains IP address of the client.)
|
||||||
|
|
||||||
|
``SESSION_TIMEOUT``
|
||||||
|
-------------------
|
||||||
|
|
||||||
|
Default: ``"3600"``
|
||||||
|
|
||||||
|
This ``SESSION_TIMEOUT`` is a method to supercede the token timeout with a
|
||||||
|
shorter horizon session timeout (in seconds). So if your token expires in
|
||||||
|
60 minutes, a value of 1800 will log users out after 30 minutes.
|
||||||
|
|
||||||
|
``TOKEN_DELETION_DISABLED``
|
||||||
|
---------------------------
|
||||||
|
|
||||||
|
Default: ``False``
|
||||||
|
|
||||||
|
This setting allows deployers to control whether a token is deleted on log out.
|
||||||
|
This can be helpful when there are often long running processes being run
|
||||||
|
in the Horizon environment.
|
||||||
|
|
||||||
|
``TOKEN_TIMEOUT_MARGIN``
|
||||||
|
------------------------
|
||||||
|
|
||||||
|
Default: ``0``
|
||||||
|
|
||||||
|
A time margin in seconds to subtract from the real token's validity.
|
||||||
|
An example usage is that the token can be valid once the middleware
|
||||||
|
passed, and invalid (timed-out) during a view rendering and this
|
||||||
|
generates authorization errors during the view rendering.
|
||||||
|
By setting this value to some smaller seconds, you can avoid token
|
||||||
|
expiration during a view rendering.
|
||||||
|
|
||||||
|
``WEBROOT``
|
||||||
|
-----------
|
||||||
|
|
||||||
|
Default: ``"/"``
|
||||||
|
|
||||||
|
Specifies the location where the access to the dashboard is configured in
|
||||||
|
the web server.
|
||||||
|
|
||||||
|
For example, if you're accessing the Dashboard via
|
||||||
|
https://<your server>/dashboard, you would set this to ``"/dashboard/"``.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
Additional settings may be required in the config files of your webserver
|
||||||
|
of choice. For example to make ``"/dashboard/"`` the web root in Apache,
|
||||||
|
the ``"sites-available/horizon.conf"`` requires a couple of additional
|
||||||
|
aliases set::
|
||||||
|
|
||||||
|
Alias /dashboard/static %HORIZON_DIR%/static
|
||||||
|
|
||||||
|
Alias /dashboard/media %HORIZON_DIR%/openstack_dashboard/static
|
||||||
|
|
||||||
|
Apache also requires changing your WSGIScriptAlias to reflect the desired
|
||||||
|
path. For example, you'd replace ``/`` with ``/dashboard`` for the
|
||||||
|
alias.
|
||||||
|
|
||||||
|
Web SSO (Single Sign On) settings
|
||||||
|
=================================
|
||||||
|
|
||||||
|
``WEBSSO_ENABLED``
|
||||||
|
------------------
|
||||||
|
|
||||||
|
Default: ``False``
|
||||||
|
|
||||||
|
Enables keystone web single-sign-on if set to True. For this feature to work,
|
||||||
|
make sure that you are using Keystone V3 and Django OpenStack Auth V1.2.0 or
|
||||||
|
later.
|
||||||
|
|
||||||
|
``WEBSSO_INITIAL_CHOICE``
|
||||||
|
-------------------------
|
||||||
|
|
||||||
|
Default: ``"credentials"``
|
||||||
|
|
||||||
|
Determines the default authentication mechanism. When user lands on the login
|
||||||
|
page, this is the first choice they will see.
|
||||||
|
|
||||||
|
``WEBSSO_CHOICES``
|
||||||
|
------------------
|
||||||
|
|
||||||
|
Default::
|
||||||
|
|
||||||
|
(
|
||||||
|
("credentials", _("Keystone Credentials")),
|
||||||
|
("oidc", _("OpenID Connect")),
|
||||||
|
("saml2", _("Security Assertion Markup Language"))
|
||||||
|
)
|
||||||
|
|
||||||
|
This is the list of authentication mechanisms available to the user. It
|
||||||
|
includes Keystone federation protocols such as OpenID Connect and SAML, and
|
||||||
|
also keys that map to specific identity provider and federation protocol
|
||||||
|
combinations (as defined in ``WEBSSO_IDP_MAPPING``). The list of choices is
|
||||||
|
completely configurable, so as long as the id remains intact. Do not remove
|
||||||
|
the credentials mechanism unless you are sure. Once removed, even admins will
|
||||||
|
have no way to log into the system via the dashboard.
|
||||||
|
|
||||||
|
``WEBSSO_IDP_MAPPING``
|
||||||
|
----------------------
|
||||||
|
|
||||||
|
Default: ``{}``
|
||||||
|
|
||||||
|
A dictionary of specific identity provider and federation protocol combinations.
|
||||||
|
From the selected authentication mechanism, the value will be looked up as keys
|
||||||
|
in the dictionary. If a match is found, it will redirect the user to a identity
|
||||||
|
provider and federation protocol specific WebSSO endpoint in keystone, otherwise
|
||||||
|
it will use the value as the protocol_id when redirecting to the WebSSO by
|
||||||
|
protocol endpoint.
|
||||||
|
|
||||||
|
Example::
|
||||||
|
|
||||||
|
WEBSSO_CHOICES = (
|
||||||
|
("credentials", _("Keystone Credentials")),
|
||||||
|
("oidc", _("OpenID Connect")),
|
||||||
|
("saml2", _("Security Assertion Markup Language")),
|
||||||
|
("acme_oidc", "ACME - OpenID Connect"),
|
||||||
|
("acme_saml2", "ACME - SAML2")
|
||||||
|
)
|
||||||
|
|
||||||
|
WEBSSO_IDP_MAPPING = {
|
||||||
|
"acme_oidc": ("acme", "oidc"),
|
||||||
|
"acme_saml2": ("acme", "saml2")
|
||||||
|
}
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
The value is expected to be a tuple formatted as: (<idp_id>, <protocol_id>).
|
||||||
|
|
||||||
|
K2K (Keystone to Keystone) Federation settings
|
||||||
|
==============================================
|
||||||
|
|
||||||
|
``KEYSTONE_PROVIDER_IDP_NAME``
|
||||||
|
------------------------------
|
||||||
|
|
||||||
|
Default: ``Local Keystone``
|
||||||
|
|
||||||
|
The Keystone Provider drop down uses Keystone to Keystone federation
|
||||||
|
to switch between Keystone service providers.
|
||||||
|
This sets display name for Identity Provider (dropdown display name).
|
||||||
|
|
||||||
|
``KEYSTONE_PROVIDER_IDP_ID``
|
||||||
|
----------------------------
|
||||||
|
|
||||||
|
Default:: ``localkeystone``
|
||||||
|
|
||||||
|
This ID is used for only for comparison with the service provider IDs.
|
||||||
|
This ID should not match any service provider IDs.
|
||||||
|
|
||||||
|
.. _settings-shared-with-horizon:
|
||||||
|
|
||||||
|
Settings shared with Horizon
|
||||||
|
============================
|
||||||
|
|
||||||
|
The following settings in Django OpenStack Auth are also used by Horizon.
|
||||||
|
|
||||||
|
* ``AVAILABLE_REGIONS``
|
||||||
|
* ``OPENSTACK_API_VERSIONS``
|
||||||
|
* ``OPENSTACK_KEYSTONE_URL``
|
||||||
|
* ``OPENSTACK_ENDPOINT_TYPE``
|
||||||
|
* ``OPENSTACK_SSL_CACERT``
|
||||||
|
* ``OPENSTACK_SSL_NO_VERIFY``
|
||||||
|
* ``WEBROOT``
|
||||||
|
|
||||||
|
Django OpenStack Auth also refers to the following Django settings.
|
||||||
|
For more detail, see `Django settings documentation
|
||||||
|
<https://docs.djangoproject.com/en/1.11/ref/settings/#auth>`__.
|
||||||
|
They are usually configured as part of Horizon settings.
|
||||||
|
|
||||||
|
* ``LOGIN_REDIRECT_URL``
|
||||||
|
* ``LOGIN_URL``
|
||||||
|
* ``SESSION_ENGINE``
|
||||||
|
* ``USE_TZ``
|
||||||
@@ -12,6 +12,7 @@ The current version is designed to work with the Keystone V2 or V3 API.
|
|||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
|
|
||||||
install/index
|
install/index
|
||||||
|
configuration/index
|
||||||
reference/index
|
reference/index
|
||||||
|
|
||||||
* :ref:`genindex`
|
* :ref:`genindex`
|
||||||
|
|||||||
Reference in New Issue
Block a user