From 74c1d5aa3487b297cea218870ddcc7273515056e Mon Sep 17 00:00:00 2001 From: Colleen Murphy Date: Thu, 13 Dec 2018 13:12:15 +0100 Subject: [PATCH] Reorganize admin guide Now that most of the operator docs are consolidated into the admin guide, it is huge and hard to find things. This patch breaks the guide into groups to make it a little easier to navigate: 1. Getting started: basics of keystone and initializing a deployment. 2. Configuration: not a replacement for the main config docs but a grouping of all discussions on the various config options. 3. Operations: maintenance workflows like upgrading and cleanups 4. Tokens: an important part of keystone 5. RBAC: gets a section to itself 6. Advanced keystone features: grouping of lesser-known/lesser-used, not-required features. 7. Authentication mechanisms: various auth methods besides password, including the federation guide Change-Id: I9039b7023d843349154d28ee0ee2c7b9a9eb97ab --- .../admin/authentication-mechanisms.rst | 15 +++ doc/source/admin/caching-layer.rst | 2 +- doc/source/admin/configuration.rst | 36 +++++++ doc/source/admin/domain-specific-config.rst | 1 - doc/source/admin/getting-started.rst | 14 +++ doc/source/admin/index.rst | 51 ++------- doc/source/admin/integrate-with-ldap.rst | 19 ++-- doc/source/admin/keystone-features.rst | 14 +++ doc/source/admin/logging.rst | 2 +- doc/source/admin/operations.rst | 13 +++ doc/source/admin/performance.rst | 5 +- doc/source/admin/security-compliance.rst | 3 - doc/source/admin/tokens-overview.rst | 96 +++++++++++++++++ doc/source/admin/tokens.rst | 102 ++---------------- doc/source/admin/troubleshoot.rst | 1 - doc/source/admin/url-safe-naming.rst | 1 - doc/source/index.rst | 2 +- 17 files changed, 217 insertions(+), 160 deletions(-) create mode 100644 doc/source/admin/authentication-mechanisms.rst create mode 100644 doc/source/admin/configuration.rst create mode 100644 doc/source/admin/getting-started.rst create mode 100644 doc/source/admin/keystone-features.rst create mode 100644 doc/source/admin/operations.rst create mode 100644 doc/source/admin/tokens-overview.rst diff --git a/doc/source/admin/authentication-mechanisms.rst b/doc/source/admin/authentication-mechanisms.rst new file mode 100644 index 0000000000..83b36a39c0 --- /dev/null +++ b/doc/source/admin/authentication-mechanisms.rst @@ -0,0 +1,15 @@ +========================= +Authentication Mechanisms +========================= + +Keystone supports various methods of authentication beyond the standard local +user and password method. + +.. toctree:: + :maxdepth: 2 + + auth-totp + federation/federated_identity + external-authentication + configure_tokenless_x509 + oauth1 diff --git a/doc/source/admin/caching-layer.rst b/doc/source/admin/caching-layer.rst index a9b9d537c4..e54ebceeea 100644 --- a/doc/source/admin/caching-layer.rst +++ b/doc/source/admin/caching-layer.rst @@ -1,5 +1,5 @@ Caching layer -~~~~~~~~~~~~~ +============= OpenStack Identity supports a caching layer that is above the configurable subsystems (for example, token). This gives you the flexibility to setup diff --git a/doc/source/admin/configuration.rst b/doc/source/admin/configuration.rst new file mode 100644 index 0000000000..660d5fa532 --- /dev/null +++ b/doc/source/admin/configuration.rst @@ -0,0 +1,36 @@ +====================== +Keystone Configuration +====================== + +Information and recommendations for general configuration of keystone for +keystone administrators. See the main `Configuration`_ section for +complete keystone configuration documentation and sample config files. + +.. _Configuration: ../configuration/index.html + +.. toctree:: + :maxdepth: 1 + + troubleshoot + logging + domain-specific-config + integrate-with-ldap + caching-layer + security-compliance + performance + url-safe-naming + limit-list-size + endpoint-filtering + endpoint-policy + +.. include:: troubleshoot.rst +.. include:: logging.rst +.. include:: domain-specific-config.rst +.. include:: integrate-with-ldap.rst +.. include:: caching-layer.rst +.. include:: security-compliance.rst +.. include:: performance.rst +.. include:: url-safe-naming.rst +.. include:: limit-list-size.rst +.. include:: endpoint-filtering.rst +.. include:: endpoint-policy.rst diff --git a/doc/source/admin/domain-specific-config.rst b/doc/source/admin/domain-specific-config.rst index 1f01a33640..aa6da27edf 100644 --- a/doc/source/admin/domain-specific-config.rst +++ b/doc/source/admin/domain-specific-config.rst @@ -1,4 +1,3 @@ -============================= Domain-specific configuration ============================= diff --git a/doc/source/admin/getting-started.rst b/doc/source/admin/getting-started.rst new file mode 100644 index 0000000000..09055055bc --- /dev/null +++ b/doc/source/admin/getting-started.rst @@ -0,0 +1,14 @@ +=============== +Getting Started +=============== + +Everything you need to get started administering a keystone deployment. + +.. toctree:: + :maxdepth: 1 + + identity-concepts + identity-sources + bootstrap + cli-manage-projects-users-and-roles + manage-services diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index 3f6c548e88..e2293d2682 100644 --- a/doc/source/admin/index.rst +++ b/doc/source/admin/index.rst @@ -5,49 +5,16 @@ Administrator Guides ==================== OpenStack Identity, code-named keystone, is the default Identity -management system for OpenStack. After you install Identity, you -configure it through the ``/etc/keystone/keystone.conf`` -configuration file and, possibly, a separate logging configuration -file. You initialize data into Identity by using the ``keystone`` -command-line client. - -.. toctree:: - :maxdepth: 1 - - identity-concepts.rst - identity-sources.rst - bootstrap.rst - cli-manage-projects-users-and-roles.rst - manage-services.rst - domain-specific-config.rst - url-safe-naming.rst - case-insensitive.rst - integrate-with-ldap.rst - upgrading.rst - tokens.rst - fernet-token-faq.rst - manage-trusts.rst - caching-layer.rst - security-compliance.rst - resource-options.rst - performance.rst - service-api-protection.rst - troubleshoot.rst - unified-limits.rst - token-provider.rst - credential-encryption.rst - endpoint-filtering.rst - health-check-middleware.rst - oauth1.rst - endpoint-policy.rst - event_notifications.rst - auth-totp.rst - external-authentication.rst - configure_tokenless_x509.rst - limit-list-size.rst - logging.rst +management system for OpenStack. This section contains guides for keystone +operators to help with administering a keystone deployment. .. toctree:: :maxdepth: 2 - federation/federated_identity.rst + getting-started + configuration + operations + tokens + service-api-protection + keystone-features + authentication-mechanisms diff --git a/doc/source/admin/integrate-with-ldap.rst b/doc/source/admin/integrate-with-ldap.rst index b6d438740e..029af8e314 100644 --- a/doc/source/admin/integrate-with-ldap.rst +++ b/doc/source/admin/integrate-with-ldap.rst @@ -1,6 +1,3 @@ -.. _integrate-identity-with-ldap: - -============================ Integrate Identity with LDAP ============================ @@ -31,10 +28,8 @@ providing user authentication through the LDAP directory. back ends are integrated with LDAP, the identity back end must also be integrated with LDAP. -.. _identity_ldap_server_setup: - Identity LDAP server set up -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------- .. important:: @@ -52,8 +47,8 @@ Identity LDAP server set up The Identity configuration is split into two separate back ends; identity (back end for users and groups), and assignments (back end for domains, projects, roles, role assignments). To configure Identity, set options -in the ``/etc/keystone/keystone.conf`` file. See -:ref:`integrate-identity-backend-ldap` for Identity back end configuration +in the ``/etc/keystone/keystone.conf`` file. See `Integrate Identity back end +with LDAP`_ for Identity back end configuration examples. Modify these examples as needed. **To define the destination LDAP server** @@ -175,10 +170,8 @@ service. During the service restart, authentication and authorization are unavailable. -.. _integrate-identity-backend-ldap: - Integrate Identity back end with LDAP -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------------- The Identity back end contains information for users, groups, and group member lists. Integrating the Identity back end with LDAP allows @@ -189,7 +182,7 @@ administrators to use users and groups in LDAP. For OpenStack Identity service to access LDAP servers, you must define the destination LDAP server in the ``/etc/keystone/keystone.conf`` file. For more information, - see :ref:`identity_ldap_server_setup`. + see `Identity LDAP server set up`_. **To integrate one Identity back end with LDAP** @@ -428,7 +421,7 @@ service. unavailable. Secure the OpenStack Identity service connection to an LDAP back end -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +-------------------------------------------------------------------- We recommend securing all connections between OpenStack Identity and LDAP. The Identity service supports the use of TLS to encrypt LDAP traffic. Before diff --git a/doc/source/admin/keystone-features.rst b/doc/source/admin/keystone-features.rst new file mode 100644 index 0000000000..2ae50b0820 --- /dev/null +++ b/doc/source/admin/keystone-features.rst @@ -0,0 +1,14 @@ +========================== +Advanced Keystone Features +========================== + +Guides to lesser-known features of keystone. + +.. toctree:: + :maxdepth: 2 + + unified-limits + resource-options + credential-encryption + health-check-middleware + event_notifications diff --git a/doc/source/admin/logging.rst b/doc/source/admin/logging.rst index c8a126e957..901e9ac911 100644 --- a/doc/source/admin/logging.rst +++ b/doc/source/admin/logging.rst @@ -1,5 +1,5 @@ Logging -------- +======= You configure logging externally to the rest of Identity. The name of the file specifying the logging configuration is set using the diff --git a/doc/source/admin/operations.rst b/doc/source/admin/operations.rst new file mode 100644 index 0000000000..6b41de9755 --- /dev/null +++ b/doc/source/admin/operations.rst @@ -0,0 +1,13 @@ +=================== +Keystone Operations +=================== + +Guides for managing day-to-day operations of keystone and understanding your +deployment. + +.. toctree:: + :maxdepth: 1 + + upgrading + case-insensitive + manage-trusts diff --git a/doc/source/admin/performance.rst b/doc/source/admin/performance.rst index a9d97ffd02..0a4532c9b2 100644 --- a/doc/source/admin/performance.rst +++ b/doc/source/admin/performance.rst @@ -11,7 +11,6 @@ License for the specific language governing permissions and limitations under the License. -======================= Performance and scaling ======================= @@ -26,7 +25,7 @@ Keystone, many of which are actually trade-offs between performance and security that you need to judge for yourself, and tune accordingly. Keystone configuration options that affect performance -====================================================== +------------------------------------------------------ These are all of the options in ``keystone.conf`` that have a direct impact on performance. See the help descriptions for these options for more specific @@ -55,7 +54,7 @@ details on how and why you might want to tune these options for yourself. key rotation strategies. Keystonemiddleware configuration options that affect performance -================================================================ +---------------------------------------------------------------- This configuration actually lives in the Paste pipelines of services consuming token validation from keystone (i.e.: nova, cinder, swift, etc.). diff --git a/doc/source/admin/security-compliance.rst b/doc/source/admin/security-compliance.rst index f527368fe3..7f9ddb8201 100644 --- a/doc/source/admin/security-compliance.rst +++ b/doc/source/admin/security-compliance.rst @@ -1,6 +1,3 @@ -.. _identity_security_compliance: - -=============================== Security compliance and PCI-DSS =============================== diff --git a/doc/source/admin/tokens-overview.rst b/doc/source/admin/tokens-overview.rst new file mode 100644 index 0000000000..00efbf9a64 --- /dev/null +++ b/doc/source/admin/tokens-overview.rst @@ -0,0 +1,96 @@ +=============== +Keystone tokens +=============== + +Tokens are used to authenticate and authorize your interactions with the +various OpenStack APIs. Tokens come in many scopes, representing various +authorization and sources of identity. + +Authorization scopes +-------------------- + +Tokens are used to relay information about your user's role assignments. It's +not uncommon for a user to have multiple role assignments, sometimes spanning +projects, domains, or the entire system. These are referred to as authorization +scopes, where a token has a single scope of operation. For example, a token +scoped to a project can't be reused to do something else in a different +project. + +Each level of authorization scope is useful for certain types of operations in +certain OpenStack services, and are not interchangeable. + +Unscoped tokens +~~~~~~~~~~~~~~~ + +An unscoped token contains neither a service catalog, any roles, a project +scope, nor a domain scope. Their primary use case is simply to prove your +identity to keystone at a later time (usually to generate scoped tokens), +without repeatedly presenting your original credentials. + +The following conditions must be met to receive an unscoped token: + +* You must not specify an authorization scope in your authentication request + (for example, on the command line with arguments such as + ``--os-project-name`` or ``--os-domain-id``), + +* Your identity must not have a "default project" associated with it that you + also have role assignments, and thus authorization, upon. + +Project-scoped tokens +~~~~~~~~~~~~~~~~~~~~~ + +Project-scoped tokens express your authorization to operate in a specific +tenancy of the cloud and are useful to authenticate yourself when working with +most other services. + +They contain a service catalog, a set of roles, and details of the project upon +which you have authorization. + +Domain-scoped tokens +~~~~~~~~~~~~~~~~~~~~ + +Domain-scoped tokens have limited use cases in OpenStack. They express your +authorization to operate a domain-level, above that of the user and projects +contained therein (typically as a domain-level administrator). Depending on +Keystone's configuration, they are useful for working with a single domain in +Keystone. + +They contain a limited service catalog (only those services which do not +explicitly require per-project endpoints), a set of roles, and details of the +project upon which you have authorization. + +They can also be used to work with domain-level concerns in other services, +such as to configure domain-wide quotas that apply to all users or projects in +a specific domain. + +System-scoped tokens +~~~~~~~~~~~~~~~~~~~~ + +There are APIs across OpenStack that fit nicely within the concept of a project +or domain, but there are also APIs that affect the entire deployment system +(e.g. modifying endpoints, service management, or listing information about +hypervisors). These operations require the use of a system-scoped token, which +represents the role assignments a user has to operate on the deployment as a +whole. + +Token providers +--------------- + +The token type issued by keystone is configurable through the +``/etc/keystone/keystone.conf`` file. Currently, the only supported token +provider is ``fernet``. + +Fernet tokens +~~~~~~~~~~~~~ + +The fernet token format was introduced in the OpenStack Kilo release and now +is the default token provider in Keystone. Unlike the other token types +mentioned in this document, fernet tokens do not need to be persisted in a back +end. ``AES256`` encryption is used to protect the information stored in the +token and integrity is verified with a ``SHA256 HMAC`` signature. Only the +Identity service should have access to the keys used to encrypt and decrypt +fernet tokens. Like UUID tokens, fernet tokens must be passed back to the +Identity service in order to validate them. For more information on the fernet +token type, see the :doc:`fernet-token-faq`. + +.. support_matrix:: token-support-matrix.ini diff --git a/doc/source/admin/tokens.rst b/doc/source/admin/tokens.rst index 00efbf9a64..7bb0579c6f 100644 --- a/doc/source/admin/tokens.rst +++ b/doc/source/admin/tokens.rst @@ -1,96 +1,12 @@ -=============== -Keystone tokens -=============== +========================= +All about keystone tokens +========================= -Tokens are used to authenticate and authorize your interactions with the -various OpenStack APIs. Tokens come in many scopes, representing various -authorization and sources of identity. +Everything you need to know about keystone tokens. -Authorization scopes --------------------- +.. toctree:: + :maxdepth: 2 -Tokens are used to relay information about your user's role assignments. It's -not uncommon for a user to have multiple role assignments, sometimes spanning -projects, domains, or the entire system. These are referred to as authorization -scopes, where a token has a single scope of operation. For example, a token -scoped to a project can't be reused to do something else in a different -project. - -Each level of authorization scope is useful for certain types of operations in -certain OpenStack services, and are not interchangeable. - -Unscoped tokens -~~~~~~~~~~~~~~~ - -An unscoped token contains neither a service catalog, any roles, a project -scope, nor a domain scope. Their primary use case is simply to prove your -identity to keystone at a later time (usually to generate scoped tokens), -without repeatedly presenting your original credentials. - -The following conditions must be met to receive an unscoped token: - -* You must not specify an authorization scope in your authentication request - (for example, on the command line with arguments such as - ``--os-project-name`` or ``--os-domain-id``), - -* Your identity must not have a "default project" associated with it that you - also have role assignments, and thus authorization, upon. - -Project-scoped tokens -~~~~~~~~~~~~~~~~~~~~~ - -Project-scoped tokens express your authorization to operate in a specific -tenancy of the cloud and are useful to authenticate yourself when working with -most other services. - -They contain a service catalog, a set of roles, and details of the project upon -which you have authorization. - -Domain-scoped tokens -~~~~~~~~~~~~~~~~~~~~ - -Domain-scoped tokens have limited use cases in OpenStack. They express your -authorization to operate a domain-level, above that of the user and projects -contained therein (typically as a domain-level administrator). Depending on -Keystone's configuration, they are useful for working with a single domain in -Keystone. - -They contain a limited service catalog (only those services which do not -explicitly require per-project endpoints), a set of roles, and details of the -project upon which you have authorization. - -They can also be used to work with domain-level concerns in other services, -such as to configure domain-wide quotas that apply to all users or projects in -a specific domain. - -System-scoped tokens -~~~~~~~~~~~~~~~~~~~~ - -There are APIs across OpenStack that fit nicely within the concept of a project -or domain, but there are also APIs that affect the entire deployment system -(e.g. modifying endpoints, service management, or listing information about -hypervisors). These operations require the use of a system-scoped token, which -represents the role assignments a user has to operate on the deployment as a -whole. - -Token providers ---------------- - -The token type issued by keystone is configurable through the -``/etc/keystone/keystone.conf`` file. Currently, the only supported token -provider is ``fernet``. - -Fernet tokens -~~~~~~~~~~~~~ - -The fernet token format was introduced in the OpenStack Kilo release and now -is the default token provider in Keystone. Unlike the other token types -mentioned in this document, fernet tokens do not need to be persisted in a back -end. ``AES256`` encryption is used to protect the information stored in the -token and integrity is verified with a ``SHA256 HMAC`` signature. Only the -Identity service should have access to the keys used to encrypt and decrypt -fernet tokens. Like UUID tokens, fernet tokens must be passed back to the -Identity service in order to validate them. For more information on the fernet -token type, see the :doc:`fernet-token-faq`. - -.. support_matrix:: token-support-matrix.ini + tokens-overview + fernet-token-faq + token-provider diff --git a/doc/source/admin/troubleshoot.rst b/doc/source/admin/troubleshoot.rst index 8206398631..58d9f93860 100644 --- a/doc/source/admin/troubleshoot.rst +++ b/doc/source/admin/troubleshoot.rst @@ -1,4 +1,3 @@ -================================= Troubleshoot the Identity service ================================= diff --git a/doc/source/admin/url-safe-naming.rst b/doc/source/admin/url-safe-naming.rst index 4c0c8d288c..4c02e435ea 100644 --- a/doc/source/admin/url-safe-naming.rst +++ b/doc/source/admin/url-safe-naming.rst @@ -1,4 +1,3 @@ -======================================= URL safe naming of projects and domains ======================================= diff --git a/doc/source/index.rst b/doc/source/index.rst index 5efbf341e4..18c692b70d 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -99,7 +99,7 @@ Administrator Guides ~~~~~~~~~~~~~~~~~~~~ .. toctree:: - :maxdepth: 2 + :maxdepth: 3 admin/index.rst