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