Docs: Make robust with using real links

Our tools noticed that keystone links to
https://docs.openstack.org/keystone/latest/admin/identity-domain-specific-config.html
which does not exist anymore.

The page was removed but the link to it was not changed. Replace this
and similar links with internal links that will work even if files are
moved - and can be verified, thus sphinx will error in case of broken
targets.

These changes include a few other fixes for broken keystone links, e.g.
to renamed anchors.

For the include files in admin/configuration.rst and
admin/federation/configure_federation.rst: Rename them to *inc.
The files were
published twice (as separate files and on this page) and thus
referencing failed. Renaming avoids this.

Also, put doctree outside of html tree so that it does not get
published.

Change-Id: I3d07637b0046cc88a66bcb51a0a4fe7c146c1549
This commit is contained in:
Andreas Jaeger 2019-08-09 16:18:51 +02:00
parent f850095710
commit f10f95b455
39 changed files with 145 additions and 103 deletions

View File

@ -1,3 +1,5 @@
.. -*- rst -*-
Caching layer
=============

View File

@ -3,19 +3,18 @@ Keystone Configuration
======================
Information and recommendations for general configuration of keystone for
keystone administrators. See the main `Configuration`_ section for
keystone administrators. See the main :ref:`Configuration
<keystone_configuration_options>` section for
complete keystone configuration documentation and sample config files.
.. _Configuration: ../configuration/index.html
.. 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
.. include:: troubleshoot.inc
.. include:: logging.inc
.. include:: domain-specific-config.inc
.. include:: integrate-with-ldap.inc
.. include:: caching-layer.inc
.. include:: security-compliance.inc
.. include:: performance.inc
.. include:: url-safe-naming.inc
.. include:: limit-list-size.inc
.. include:: endpoint-filtering.inc
.. include:: endpoint-policy.inc

View File

@ -1,3 +1,7 @@
.. -*- rst -*-
.. _domain_specific_configuration:
Domain-specific configuration
=============================

View File

@ -1,3 +1,5 @@
.. -*- rst -*-
Endpoint Filtering
==================

View File

@ -1,3 +1,5 @@
.. -*- rst -*-
Endpoint Policy
===============

View File

@ -158,7 +158,7 @@ The reason object will contain the following keys:
* ``reasonCode``: HTTP response code for the event
For more information, see
:doc:`../admin/security-compliance`
:ref:`security_compliance`
for configuring PCI-DSS in keystone.
Supported Events

View File

@ -26,7 +26,7 @@ Prerequisites
-------------
If you are not familiar with the idea of federated identity, see the
`introduction`_ first.
:ref:`federation_introduction` first.
In this section, we will configure keystone as a Service Provider, consuming
identity properties issued by an external Identity Provider, such as SAML
@ -42,15 +42,18 @@ Ubuntu 16.04 and Apache 2.4.18.
To enable federation, you'll need to run keystone behind a web server such as
Apache rather than running the WSGI application directly with uWSGI or Gunicorn.
See the installation guide for `SUSE`_, `RedHat`_ or `Ubuntu`_ to configure
the Apache web server for keystone.
See the installation guide for :ref:`SUSE <suse_configure_apache>`,
:ref:`RedHat <redhat_configure_apache>` or :ref:`Ubuntu
<ubuntu_configure_apache>` to configure the Apache web server for
keystone.
Throughout the rest of the guide, you will need to decide on three pieces of
information and use them consistently throughout your configuration:
1. The protocol name. This must be a valid keystone auth method and must match
one of: ``saml2``, ``openid``, ``mapped`` or a `custom auth method`_ for which
you must `register as an external driver`_.
one of: ``saml2``, ``openid``, ``mapped`` or a :ref:`custom auth
method <auth_plugins>` for which
you must :ref:`register as an external driver <developing_drivers>`.
2. The identity provider name. This can be arbitrary.
@ -71,13 +74,8 @@ Provider.
``/identity`` (for example), take this into account in your own
configuration.
.. _introduction: introduction
.. _samltest.id: https://samltest.id
.. _SUSE: ../../install/keystone-install-obs.html#configure-the-apache-http-server
.. _RedHat: ../../install/keystone-install-rdo.html#configure-the-apache-http-server
.. _Ubuntu: ../../install/keystone-install-ubuntu.html#configure-the-apache-http-server
.. _custom auth method: ../../contributor/auth-plugins
.. _register as an external driver: ../../contributor/developing-drivers
Creating federation resources in keystone
-----------------------------------------
@ -133,6 +131,8 @@ See also the `API reference on identity providers`_.
.. _API reference on identity providers: https://docs.openstack.org/api-ref/identity/v3-ext/#identity-providers
.. _create_a_mapping:
Create a Mapping
~~~~~~~~~~~~~~~~
@ -236,12 +236,9 @@ Configuring an HTTPD auth module
This guide currently only includes examples for the Apache web server, but it
possible to use SAML, OpenIDC, and other auth modules in other web servers. See
the installation guides for running keystone behind Apache for `SUSE`_,
`RedHat`_ or `Ubuntu`_.
.. _`SUSE`: ../../install/keystone-install-obs.html#configure-the-apache-http-server
.. _`RedHat`: ../../install/keystone-install-rdo.html#configure-the-apache-http-server
.. _`Ubuntu`: ../../install/keystone-install-ubuntu.html#configure-the-apache-http-server
the installation guides for running keystone behind Apache for
:ref:`SUSE <suse_configure_apache>`, :ref:`RedHat
<redhat_configure_apache>` or :ref:`Ubuntu <ubuntu_configure_apache>`.
Configure protected endpoints
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -333,15 +330,13 @@ This guide contains examples for two major federation protocols:
* SAML2.0 - see guides for the following implementations:
* `Set up mod_shib`_.
* `Set up mod_auth_mellon`_.
* :ref:`Set up mod_shib <shibboleth>`.
* :ref:`Set up mod_auth_mellon <mellon>`.
* OpenID Connect: `Set up mod_auth_openidc`_.
* OpenID Connect: :ref:`Set up mod_auth_openidc <federation_openidc>`.
.. _`Set up mod_shib`: shibboleth.html
.. _`Set up mod_auth_openidc`: openidc.html
.. _`Set up mod_auth_mellon`: mellon.html
.. _federation_configuring_keystone:
Configuring Keystone
--------------------
@ -584,6 +579,8 @@ from the menu to be redirected to your Identity Provider for authentication.
:height: 400px
:alt: Horizon login screen using external authentication
.. _keystone_as_idp:
--------------------------------------
Keystone as an Identity Provider (IdP)
--------------------------------------
@ -596,7 +593,7 @@ When keystone is configured as an Identity Provider, it is often referred to as
clouds using the SAML2.0 protocol.
If you are not familiar with the idea of federated identity, see the
`introduction`_ first.
:ref:`introduction <federation_introduction>` first.
When setting up `Keystone to Keystone`, it is easiest to
:ref:`configure a keystone Service Provider <keystone-as-sp>` first
@ -758,6 +755,7 @@ to another cloud.
:height: 175px
:alt: Horizon dropdown menu for switching between keystone providers
.. include:: openidc.rst
.. include:: mellon.rst
.. include:: shibboleth.rst
.. include:: openidc.inc
.. include:: mellon.inc
.. include:: shibboleth.inc

View File

@ -14,6 +14,8 @@
License for the specific language governing permissions and limitations
under the License.
.. _federation_introduction:
Introduction to Keystone Federation
===================================
@ -28,32 +30,31 @@ identity source and then provides keystone with a set of user attributes. This
is useful if your organization already has a primary identity source since it
means users don't need a separate set of credentials for the cloud. It is also
useful for connecting multiple clouds together, as we can use a keystone in
another cloud as an identity source. Using `LDAP as an identity backend`_ is
another cloud as an identity source. Using :ref:`LDAP as an identity
backend <integrate_with_ldap>` is
another way for keystone to obtain identity information from an external source,
but it requires keystone to handle passwords directly rather than offloading
authentication to the external source.
Keystone supports two configuration models for federated identity. The most
common configuration is with `keystone as a Service Provider (SP)`_, using an
common configuration is with `keystone as a Service Provider (SP)
<keystone-as-sp>`, using an
external Identity Provider, such as a Keycloak or Google, as the identity source
and authentication method. The second type of configuration is "`Keystone to
Keystone`_", where two keystones are linked with one acting as the identity
source.
and authentication method. The second type of configuration is
":ref:`Keystone to Keystone <keystone_as_idp>`", where two keystones
are linked with one acting as the identity source.
This document discusses identity federation involving a secondary identity
management that acts as the source of truth concerning the users it contains,
specifically covering the SAML2.0 and OpenID Connect protocols, although
keystone can work with other protocols. A similar concept is `external
authentication`_ whereby keystone is still the source of truth about its users
keystone can work with other protocols. A similar concept is :doc:`external
authentication </admin/external-authentication>` whereby keystone is
still the source of truth about its users
but authentication is handled externally. Yet another closely related topic is
`tokenless authentication`_ which uses some of the same constructs as described
:doc:`tokenless authentication </admin/configure_tokenless_x509>`
which uses some of the same constructs as described
here but allows services to validate users without using keystone tokens.
.. _LDAP as an identity backend: ../../admin/identity-integrate-with-ldap.html
.. _keystone as a Service Provider (SP): configure_federation.html#keystone-as-a-service-provider-sp
.. _Keystone to Keystone: configure_federation.html#keystone-as-an-identity-provider-idp
.. _external authentication: ../external-authentication.html
.. _tokenless authentication: ../configure_tokenless_x509.html
--------
Glossary

View File

@ -1,3 +1,5 @@
.. -*- rst -*-
..
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
@ -11,6 +13,8 @@
License for the specific language governing permissions and limitations
under the License.
.. _mellon:
-----------------
Setting Up Mellon
-----------------
@ -143,6 +147,4 @@ Remember to reload Apache after finishing configuring Mellon:
Continue configuring keystone
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
`Continue configuring keystone`_
.. _Continue configuring keystone: configure_federation.html#configuring-keystone
:ref:`Continue configuring keystone <federation_configuring_keystone>`

View File

@ -1,3 +1,5 @@
.. -*- rst -*-
..
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
@ -11,6 +13,8 @@
License for the specific language governing permissions and limitations
under the License.
.. _federation_openidc:
-------------------------
Setting Up OpenID Connect
-------------------------
@ -109,16 +113,12 @@ Remember to reload Apache after altering the VirtualHost:
.. note::
When creating `mapping rules`_, in keystone, note that the 'remote'
When creating :ref:`mapping rules <create_a_mapping>`, in keystone, note that the 'remote'
attributes will be prefixed, with ``HTTP_``, so for instance, if you set
``OIDCClaimPrefix`` to ``OIDC-``, then a typical remote value to check for
is: ``HTTP_OIDC_ISS``.
.. _`mapping rules`: configure_federation.html#mapping
Continue configuring keystone
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
`Continue configuring keystone`_
.. _Continue configuring keystone: configure_federation.html#configuring-keystone
:ref:`Continue configuring keystone <federation_configuring_keystone>`

View File

@ -1,3 +1,5 @@
.. -*- rst -*-
..
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
@ -11,6 +13,8 @@
License for the specific language governing permissions and limitations
under the License.
.. _shibboleth:
---------------------
Setting up Shibboleth
---------------------
@ -268,6 +272,4 @@ is your Identity Provider you do not need to upload this file.
Continue configuring keystone
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
`Continue configuring keystone`_
.. _Continue configuring keystone: configure_federation.html#configuring-keystone
:ref:`Continue configuring keystone <federation_configuring_keystone>`

View File

@ -297,8 +297,7 @@ service, such as, a user named ``nova`` for the Compute service, and a
special service project called ``service``.
For information about how to create services and endpoints, see the
`OpenStack Administrator Guide <https://docs.openstack.org/keystone/latest/
admin/manage-services.html>`__.
`Administrator Guide <manage_services>`__.
Groups
~~~~~~

View File

@ -26,11 +26,10 @@ keystone is deciding how you want keystone to source your identity data.
Keystone supports several different choices that will substantially impact how
you'll configure, deploy, and interact with keystone.
You can also mix-and-match various sources of identity (see `Domain-specific
Configuration`_ for an example). For example, you can store OpenStack service users
You can also mix-and-match various sources of identity (see
:ref:`Domain-specific Configuration <domain_specific_configuration>` for an
example). For example, you can store OpenStack service users
and their passwords in SQL, manage customers in LDAP, and authenticate employees
via SAML federation.
.. _Domain-specific Configuration: domain-specific-config.html
.. support_matrix:: identity-support-matrix.ini

View File

@ -1,3 +1,7 @@
.. -*- rst -*-
.. _integrate_with_ldap:
Integrate Identity with LDAP
============================

View File

@ -1,3 +1,5 @@
.. -*- rst -*-
..
Copyright 2018 SUSE Linux GmbH
All Rights Reserved.

View File

@ -1,3 +1,5 @@
.. -*- rst -*-
Logging
=======

View File

@ -1,3 +1,5 @@
.. _manage_services:
============================================
Create and manage services and service users
============================================

View File

@ -3,10 +3,9 @@ Managing trusts
===============
A trust is an OpenStack Identity extension that enables delegation and,
optionally, impersonation through ``keystone``. See the `user guide on using
trusts`_.
optionally, impersonation through ``keystone``. See the :doc:`user
guide on using trusts </user/trusts>`.
.. _user guide on using trusts: ../user/trusts.html
Removing Expired Trusts
===========================================================

View File

@ -1,3 +1,5 @@
.. -*- rst -*-
..
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain

View File

@ -64,8 +64,8 @@ when they start using the deployment.
}
}
See the `security compliance documentation
<security-compliance.html>`_ for more details.
See the :ref:`security compliance documentation
<security_compliance>` for more details.
.. _ignore_password_expiry:
@ -89,8 +89,8 @@ expired according to global configuration values.
}
}
See the `security compliance documentation
<security-compliance.html>`_ for more details.
See the :ref:`security compliance documentation
<security_compliance>` for more details.
.. _ignore_lockout_failure_attempts:
@ -112,8 +112,8 @@ locking out the user as a result.
}
}
See the `security compliance documentation
<security-compliance.html>`_ for more details.
See the :ref:`security compliance documentation
<security_compliance>` for more details.
.. _lock_password:
@ -136,8 +136,8 @@ password through self-service APIs.
}
See the `security compliance documentation
<security-compliance.html>`_ for more details.
See the :ref:`security compliance documentation
<security_compliance>` for more details.
.. _multi_factor_auth_enabled:

View File

@ -1,3 +1,7 @@
.. -*- rst -*-
.. _security_compliance:
Security compliance and PCI-DSS
===============================

View File

@ -6,6 +6,8 @@ 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:
Authorization scopes
--------------------

View File

@ -1,3 +1,5 @@
.. -*- rst -*-
Troubleshoot the Identity service
=================================

View File

@ -1,3 +1,5 @@
.. -*- rst -*-
URL safe naming of projects and domains
=======================================

View File

@ -20,8 +20,5 @@ Domain-specific Identity drivers
The Identity service supports domain-specific Identity drivers
installed on an SQL or LDAP back end, and supports domain-specific
Identity configuration options, which are stored in domain-specific
configuration files. See the
`Admin guide Identity Management Chapter
<https://docs.openstack.org
/keystone/latest/admin/identity-domain-specific-config.html>`_
configuration files. See :ref:`domain_specific_configuration`
for more information.

View File

@ -1,3 +1,5 @@
.. _keystone_configuration_options:
==============================
Keystone Configuration Options
==============================

View File

@ -30,9 +30,9 @@ Proposing a change
You need to create a RFE bug report, submit a specification against the `keystone-specs`_
repository and bring it up to discussion with the `keystone core team`_ for
agreement. Please refer to the `guide for proposing features`_ to learn more about the process.
agreement. Please refer to the :ref:`guide for proposing features
<proposing_features>` to learn more about the process.
.. _`guide for proposing features`: https://docs.openstack.org/keystone/latest/contributor/proposing-features.html
.. _`keystone-specs`: https://opendev.org/openstack/keystone-specs/
.. _`keystone core team`: https://review.opendev.org/#/admin/groups/9,members

View File

@ -14,6 +14,8 @@
License for the specific language governing permissions and limitations
under the License.
.. _auth_plugins:
Authentication Plugins
======================

View File

@ -11,6 +11,8 @@
License for the specific language governing permissions and limitations
under the License.
.. _developing_drivers:
===========================
Developing Keystone Drivers
===========================

View File

@ -44,7 +44,7 @@ while you learn the ropes:
* Review `new changes`_. Keep OpenStack's `review guidelines`_ in mind. Ask
questions when you don't understand a change.
Need any help? `Reach out`_ to the keystone team.
Need any help? :doc:`Reach out </getting-started/community>` to the keystone team.
.. _keystone: https://bugs.launchpad.net/keystone/+bugs?field.tag=low-hanging-fruit
.. _keystonemiddleware: https://bugs.launchpad.net/keystonemiddleware/+bugs?field.tag=low-hanging-fruit
@ -54,7 +54,6 @@ Need any help? `Reach out`_ to the keystone team.
.. _keystone maintainers: https://review.opendev.org/#/admin/groups/9,members
.. _new changes: https://review.opendev.org/#/q/is:open+project:openstack/keystone+OR+project:openstack/keystonemiddleware+OR+project:openstack/keystoneauth+OR+project:openstack/python-keystoneclient
.. _review guidelines: https://docs.openstack.org/project-team-guide/review-the-openstack-way.html
.. _Reach out: ../getting-started/community.html
The Meaning of Low Hanging Fruit
================================

View File

@ -11,6 +11,8 @@
License for the specific language governing permissions and limitations
under the License.
.. _proposing_features:
==================
Proposing Features
==================

View File

@ -499,8 +499,8 @@ you've made to policy enforcement in your service. Release notes are an
excellent way to signal changes to operators. You can find examples when
keystone implemented support for default roles. Additionally, you might have
operators or users ask questions about the various scopes or what they mean.
Don't hesitate to refer them to keystone's `scope documentation
<https://docs.openstack.org/keystone/latest/admin/tokens-overview.html#authorization-scopes>`_.
Don't hesitate to refer them to keystone's :ref:`scope documentation
<authorization_scopes>`.
Auth Token middleware
=====================

View File

@ -44,11 +44,11 @@ enable a true self-service experience for end users in a shared-resource system.
Application Control
-------------------
Keystone provides the ability for applications to have their own identity
through `application credentials`_, in service of developers building
applications that need to access cloud APIs and cloud-native applications.
.. _application credentials: https://docs.openstack.org/keystone/latest/user/application_credentials.html
Keystone provides the ability for applications to have their own
identity through :ref:`application credentials
<application_credentials>`, in service of developers building
applications that need to access cloud APIs and cloud-native
applications.
Interoperability
----------------

View File

@ -151,6 +151,8 @@ Install and configure components
Replace ``ADMIN_PASS`` with a suitable password for an administrative user.
.. _suse_configure_apache:
Configure the Apache HTTP server
--------------------------------

View File

@ -140,6 +140,8 @@ Install and configure components
Replace ``ADMIN_PASS`` with a suitable password for an administrative user.
.. _redhat_configure_apache:
Configure the Apache HTTP server
--------------------------------

View File

@ -144,6 +144,8 @@ Install and configure components
Replace ``ADMIN_PASS`` with a suitable password for an administrative user.
.. _ubuntu_configure_apache:
Configure the Apache HTTP server
--------------------------------

View File

@ -14,6 +14,8 @@
License for the specific language governing permissions and limitations
under the License.
.. _application_credentials:
=======================
Application Credentials
=======================

View File

@ -73,7 +73,6 @@ The delegation parameters are:
.. note::
See the administrator guide on `removing expired trusts`_ for recommended
See the administrator guide on :doc:`removing expired trusts
</admin/manage-trusts>` for recommended
maintenance procedures.
.. _`removing expired trusts`: ../admin/manage-trusts.html

View File

@ -140,7 +140,7 @@ deps =
commands=
bash -c "rm -rf doc/build"
bash -c "rm -rf doc/source/api"
sphinx-build -W -b html doc/source doc/build/html
sphinx-build -W -b html -d doc/build/doctrees doc/source doc/build/html
[testenv:releasenotes]
basepython = python3