Merge "doc: Add configuration reference"

2 files changed, 377 insertions, 0 deletions

diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst
new file mode 100644
index 0000000..b442a3f
--- /dev/null
+++ b/doc/source/configuration/index.rst
@@ -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``
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 9f93215..d9ba571 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -12,6 +12,7 @@ The current version is designed to work with the Keystone V2 or V3 API.
    :maxdepth: 2
 
    install/index
+   configuration/index
    reference/index
 
 * :ref:`genindex`