diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/source/conf.py | 170 | ||||
| -rw-r--r-- | doc/source/configuration/index.rst | 442 | ||||
| -rw-r--r-- | doc/source/index.rst | 21 | ||||
| -rw-r--r-- | doc/source/install/index.rst | 63 | ||||
| -rw-r--r-- | doc/source/reference/backend.rst | 6 | ||||
| -rw-r--r-- | doc/source/reference/forms.rst | 6 | ||||
| -rw-r--r-- | doc/source/reference/index.rst | 13 | ||||
| -rw-r--r-- | doc/source/reference/user.rst | 6 | ||||
| -rw-r--r-- | doc/source/reference/utils.rst | 6 | ||||
| -rw-r--r-- | doc/source/reference/views.rst | 6 |
10 files changed, 0 insertions, 739 deletions
diff --git a/doc/source/conf.py b/doc/source/conf.py deleted file mode 100644 index 9faa27e..0000000 --- a/doc/source/conf.py +++ /dev/null @@ -1,170 +0,0 @@ -# -*- coding: utf-8 -*- -# -# Django OpenStack Auth documentation build configuration file, created by -# sphinx-quickstart on Sun Jul 8 15:13:36 2012. -# -# This file is execfile()d with the current directory set to its containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -import os - -import django - -os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'openstack_auth.tests.settings') - -django.setup() - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.insert(0, os.path.abspath('.')) - -# -- General configuration ----------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'openstackdocstheme'] - -# openstackdocstheme options -repository_name = 'openstack/django_openstack_auth' -bug_project = 'django-openstack-auth' -bug_tag = '' -html_last_updated_fmt = '%Y-%m-%d %H:%M' - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix of source filenames. -source_suffix = '.rst' - -# The encoding of source files. -#source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'Django OpenStack Auth' -copyright = u'2012, Gabriel Hurley' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -#language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = ['_build'] - -# The reST default role (used for this markup: `text`) to use for all documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# A list of ignored prefixes for module index sorting. -modindex_common_prefix = ['openstack_auth.'] - - -# -- Options for HTML output --------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -html_theme = 'openstackdocs' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -#html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# "<project> v<release> documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -#html_static_path = [] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a <link> tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Output file base name for HTML help builder. -htmlhelp_basename = 'DjangoOpenStackAuthdoc' diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst deleted file mode 100644 index 06c300b..0000000 --- a/doc/source/configuration/index.rst +++ /dev/null @@ -1,442 +0,0 @@ -============= -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. - - -``DEFAULT_SERVICE_REGIONS`` ---------------------------- - -Default: ``{}`` - -The default service region is set on a per-endpoint basis, meaning that once -the user logs into some Keystone endpoint, if a default service region is -defined for it in this setting and exists within Keystone catalog, it will be -set as the initial service region in this endpoint. By default it is an empty -dictionary because upstream can neither predict service region names in a -specific deployment, nor tell whether this behavior is desired. The key of the -dictionary is a full url of a Keystone endpoint with version suffix, the value -is a region name. - -Example:: - - DEFAULT_SERVICE_REGIONS = { - OPENSTACK_KEYSTONE_URL: 'RegionOne' - } - - -``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_DOMAIN_CHOICES`` -------------------------------------- - -.. versionadded:: 12.0.0(Pike) - -Default:: - - ( - ('Default', 'Default'), - ) - -If OPENSTACK_KEYSTONE_DOMAIN_DROPDOWN is enabled, this option can be used to -set the available domains to choose from. This is a list of pairs whose first -value is the domain name and the second is the display name. - -``OPENSTACK_KEYSTONE_DOMAIN_DROPDOWN`` --------------------------------------- - -.. versionadded:: 12.0.0(Pike) - -Default: ``False`` -Set this to True if you want available domains displayed as a dropdown menu on -the login screen. It is strongly advised NOT to enable this for public clouds, -as advertising enabled domains to unauthenticated customers irresponsibly -exposes private information. This should only be used for private clouds where -the dashboard sits behind a corporate firewall. - -``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_DIRS`` ----------------- - -Default: ``{}`` - -Specifies a list of policy directories per service types. The directories -are relative to ``POLICY_FILES_PATH``. Services whose additional policies -are defined here must be defined in ``POLICY_FILES`` too. Otherwise, -additional policies specified in ``POLICY_DIRS`` are not loaded. - -Example:: - - POLICY_DIRS = { - 'identity': 'keystone_policy.d', - 'compute': 'nova_policy.d' - } - -``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 deleted file mode 100644 index d9ba571..0000000 --- a/doc/source/index.rst +++ /dev/null @@ -1,21 +0,0 @@ -===================== -Django OpenStack Auth -===================== - -Django OpenStack Auth is a pluggable Django authentication backend that -works with Django's ``contrib.auth`` framework to authenticate a user against -OpenStack's Keystone Identity API. - -The current version is designed to work with the Keystone V2 or V3 API. - -.. toctree:: - :maxdepth: 2 - - install/index - configuration/index - reference/index - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst deleted file mode 100644 index 866152f..0000000 --- a/doc/source/install/index.rst +++ /dev/null @@ -1,63 +0,0 @@ -=============== -Getting Started -=============== - -Installation -============ - -Installing is quick and easy: - -#. Run ``pip install django_openstack_auth``. - -#. Add ``openstack_auth`` to ``settings.INSTALLED_APPS``. - -#. Add ``'openstack_auth.backend.KeystoneBackend'`` to your - ``settings.AUTHENTICATION_BACKENDS``, e.g.:: - - AUTHENTICATION_BACKENDS = ('openstack_auth.backend.KeystoneBackend',) - -#. Configure your API endpoint(s) in ``settings.py``:: - - OPENSTACK_KEYSTONE_URL = "http://example.com:5000/v3" - -#. Include ``'openstack_auth.urls'`` somewhere in your ``urls.py`` file. - -#. Use it as you would any other Django auth backend. - -Running Tests -============= - -Before running tests, you should have ``tox`` installed and available in your -environment: - -.. code-block:: bash - - $ pip install tox - -.. NOTE:: - - You may need to perform both the above operation and the next inside a - python virtualenv, or prefix the above command with ``sudo``, depending on - your preference. - -To execute the full suite of tests maintained within the project, simply run: - -.. code-block:: bash - - $ tox - -.. NOTE:: - - The first time you run ``tox``, it will take additional time to build - virtualenvs. You can later use the ``-r`` option with ``tox`` to rebuild - your virtualenv in a similar manner. - -To run tests for one or more specific test environments (for example, the most -common configuration of Python 2.7 and PEP-8), list the environments with the -``-e`` option, separated by spaces: - -.. code-block:: bash - - $ tox -e py27,pep8 - -See ``tox.ini`` for the full list of available test environments. diff --git a/doc/source/reference/backend.rst b/doc/source/reference/backend.rst deleted file mode 100644 index 181536f..0000000 --- a/doc/source/reference/backend.rst +++ /dev/null @@ -1,6 +0,0 @@ -================== -The Backend Module -================== - -.. automodule:: openstack_auth.backend - :members: diff --git a/doc/source/reference/forms.rst b/doc/source/reference/forms.rst deleted file mode 100644 index 120c213..0000000 --- a/doc/source/reference/forms.rst +++ /dev/null @@ -1,6 +0,0 @@ -================ -The Forms Module -================ - -.. automodule:: openstack_auth.forms - :members: diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst deleted file mode 100644 index 77a8e11..0000000 --- a/doc/source/reference/index.rst +++ /dev/null @@ -1,13 +0,0 @@ -===================================== - Django OpenStack Auth API Reference -===================================== - -.. toctree:: - :maxdepth: 2 - - user - views - forms - backend - utils - diff --git a/doc/source/reference/user.rst b/doc/source/reference/user.rst deleted file mode 100644 index f54587c..0000000 --- a/doc/source/reference/user.rst +++ /dev/null @@ -1,6 +0,0 @@ -============== -The User Class -============== - -.. automodule:: openstack_auth.user - :members: diff --git a/doc/source/reference/utils.rst b/doc/source/reference/utils.rst deleted file mode 100644 index a89e0a2..0000000 --- a/doc/source/reference/utils.rst +++ /dev/null @@ -1,6 +0,0 @@ -================ -The Utils Module -================ - -.. automodule:: openstack_auth.utils - :members: diff --git a/doc/source/reference/views.rst b/doc/source/reference/views.rst deleted file mode 100644 index e71719e..0000000 --- a/doc/source/reference/views.rst +++ /dev/null @@ -1,6 +0,0 @@ -================ -The Views Module -================ - -.. automodule:: openstack_auth.views - :members: |