Federated documentations lacks a concise introduction

[Lance Bragstad]

The documentation for federated identity [1] doesn't clearly describe what the purpose of federated identity is or why someone would want to use it.

This was apparent during the Stein PTG in Denver [0] when working with a set of people with fresh perspectives. Most regular keystone contributors have such an in-depth understanding of identity federation that it makes us gloss over some things that might be confusing to new-comers.

This bug is to track reworking the federated identity documentation to include a clear and concise introduction that helps people understand the purpose of federation before leading them into technical details.

The introduction should try and describe the following:

What is identity federation?
Why is it useful?
What is SAML?
What protocols can be used?
What are the benefits of using different protocols, if any?

[0] https://etherpad.openstack.org/p/keystone-stein-federation
[1] https://docs.openstack.org/keystone/latest/advanced-topics/federation/federated_identity.html

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/613408
Committed: https://git.openstack.org/cgit/openstack/keystone/commit/?id=914885fefda269e27d815c52f8134e206222259c
Submitter: Zuul
Branch: master

commit 914885fefda269e27d815c52f8134e206222259c
Author: Colleen Murphy <email address hidden>
Date: Thu Oct 25 21:58:34 2018 +0200

    Delete administrator federation guide

    The federated-identity guide in the admin section is out of date
    relative to the one in the operator section. It is sort of incoherent
    and the information within it that is valuable is already present in the
    other guide. Delete this guide in favor of just promoting the operator
    guide.

    Related-bug: #1793374

    Change-Id: I8c0190725d0f7297957bbf10fd9d7184e52ff5f3

[Shuayb Popoola (shuayb)]

I will like to be assigned

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/615384

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/615384
Committed: https://git.openstack.org/cgit/openstack/keystone/commit/?id=4a141fea5170cd0e5bda1c8333cae553e0a8e175
Submitter: Zuul
Branch: master

commit 4a141fea5170cd0e5bda1c8333cae553e0a8e175
Author: Colleen Murphy <email address hidden>
Date: Sat Nov 3 17:10:12 2018 +0100

    Add introduction section to federation docs

    Add an introduction to the federation documentation discussing
    background information on identity federation and how it is implemented
    in keystone.

    This repurposes some of the content in this blog post[1] of which I am
    the author.

    [1] http://www.gazlene.net/demystifying-keystone-federation.html

    Partial-bug: #1793374

    Change-Id: I5f3a5e70c7b868762880930ea6277691f44c046a

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/627842

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/627843

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/627844

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/627845

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/627846

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/627847

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/627966

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/627968

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/627972

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/627975

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/627976

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/627982

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/627993

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/628037

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/627842
Committed: https://git.openstack.org/cgit/openstack/keystone/commit/?id=131acaccaf36b640056dd5bf90a7730bc8d04d28
Submitter: Zuul
Branch: master

commit 131acaccaf36b640056dd5bf90a7730bc8d04d28
Author: Colleen Murphy <email address hidden>
Date: Sun Dec 9 23:16:49 2018 +0100

    Restructure federation guide

    Having everything on a single page is nice for ctrl-F-ability but it
    makes the flow very confusing. This change breaks the guide into three
    logical parts: the introduction, the configuration steps, and the
    advanced mapping rules guide. Keeping all the configuration steps within
    one page means it can still be searched easily, but removing the prose
    of the introduction and breaking out the deep-dive mapping rules guide
    reduces clutter and enhances readability.

    Partial-bug: #1793374

    Change-Id: Id2fd59d62a2675691d545e4cd0404558f00cf481

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/627843
Committed: https://git.openstack.org/cgit/openstack/keystone/commit/?id=40e0f5d976d6b5172a408bdd548937e24361db35
Submitter: Zuul
Branch: master

commit 40e0f5d976d6b5172a408bdd548937e24361db35
Author: Colleen Murphy <email address hidden>
Date: Fri Dec 21 10:50:35 2018 -0800

    Bring SP/IdP URLs closer to style guide guidance

    The documentation style guide recommends using example URLs for
    OpenStack services that look like
    `http://<service>.openstack.example.org`. This patch changes the URLs
    for hypothetical keystone Service Providers to use HTTPS endpoints to
    set a good example of security, to use the example.org domain instead of
    localhost or example.com, to include keystone in the name for clarity of
    what the service is, and to use a consistent URL path and port. It
    doesn't include 'openstack' in the domain name because that becomes a
    bit long.

    [1] https://docs.openstack.org/doc-contrib-guide/writing-style/urls.html

    Partial-bug: #1793374

    Change-Id: I8e12edaa589be3c8e71b10d0609c057fd2bfb247

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/627844
Committed: https://git.openstack.org/cgit/openstack/keystone/commit/?id=9bc2b8875d8c2bba6038185a68bfce05afdb36e2
Submitter: Zuul
Branch: master

commit 9bc2b8875d8c2bba6038185a68bfce05afdb36e2
Author: Colleen Murphy <email address hidden>
Date: Fri Dec 21 11:16:49 2018 -0800

    Fix nits in code blocks in federation guide

    Fix inconsistent indentation of code-blocks, ensure shell samples
    correctly differentiate betweeen root-required commands and non-root
    commands in accordance with the openstack-manuals recommendations[1],
    and use proper markup for interactive shell examples.

    [1] http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/common/conventions.rst

    Partial-bug: #1793374

    Change-Id: Ia9e5280d131e1aa50af41aff6155eb07954b7d15

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/627845
Committed: https://git.openstack.org/cgit/openstack/keystone/commit/?id=5cc61bb644133f6e36f3255fada95ae78a65edf4
Submitter: Zuul
Branch: master

commit 5cc61bb644133f6e36f3255fada95ae78a65edf4
Author: Colleen Murphy <email address hidden>
Date: Fri Dec 21 14:25:47 2018 -0800

    Use samltest.id as an example sandbox IdP

    The federation documentation inconsistently references samltest.id
    (formerly testshib.org, which is not well maintained) or a keystone IdP
    (before keystone-to-keystone is introduced). This change switches the
    examples to use samltest.id[1] and renames 'myidp' to 'samltest' where
    appropriate. In the case of the WebSSO horizon configuration examples,
    it's not appropriate to switch the openid examples to samltest because
    samltest.id does not support OpenIDC. The examples are meant to show
    that you can pair different protocols to a single IdP, so use 'acme' as
    the example.

    [1] https://samltest.id

    Partial-bug: #1793374

    Change-Id: I2633ba460182ed8ed5195a10cdaae663add8b1aa

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/627846
Committed: https://git.openstack.org/cgit/openstack/keystone/commit/?id=bc202f70433f435fc335bf0ddf460d89df55350a
Submitter: Zuul
Branch: master

commit bc202f70433f435fc335bf0ddf460d89df55350a
Author: Colleen Murphy <email address hidden>
Date: Fri Dec 21 14:54:34 2018 -0800

    Update federation SP prerequisites section

    Remove outdated information, update version information and expand on
    preliminary information that will be needed throughout the rest of the
    guide.

    Partial-bug: #1793374

    Change-Id: I0e5c4ccde4c88bec3fa78114e1ede9545ed98678

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/627847
Committed: https://git.openstack.org/cgit/openstack/keystone/commit/?id=94b3ba6310f2bb241d9295b1f0d1c241cf1667e5
Submitter: Zuul
Branch: master

commit 94b3ba6310f2bb241d9295b1f0d1c241cf1667e5
Author: Colleen Murphy <email address hidden>
Date: Fri Dec 21 15:27:24 2018 -0800

    Add prerequisites section to keystone-to-keystone

    Make the keystone-to-keystone section mirror the keystone-as-sp section
    by adding a prerequisites section that identifies some useful background
    information, and clean up some outdated information.

    Partial-bug: #1793374

    Change-Id: I39235a394d6bc59aad84e6f6a779d39036199302

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/627966
Committed: https://git.openstack.org/cgit/openstack/keystone/commit/?id=fc3dcc8071bd0c83618ad8abe19d8922669fa3d0
Submitter: Zuul
Branch: master

commit fc3dcc8071bd0c83618ad8abe19d8922669fa3d0
Author: Colleen Murphy <email address hidden>
Date: Fri Dec 21 15:48:50 2018 -0800

    Enhance authn sections in federation guide

    Modernize the examples on using the CLI to authenticate with an external
    IdP or keystone IdP, add tips on how to get needed information, and add
    examples on authenticating with horizon.

    Partial-bug: #1793374

    Change-Id: Ieec899a1551be69da232196c59b9aeed0e85f5f5

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/627968
Committed: https://git.openstack.org/cgit/openstack/keystone/commit/?id=3d6930e171d200e2c07683bd179a804f220b8317
Submitter: Zuul
Branch: master

commit 3d6930e171d200e2c07683bd179a804f220b8317
Author: Colleen Murphy <email address hidden>
Date: Fri Dec 21 16:57:05 2018 -0800

    Clean up keystone-to-keystone section

    Clean up the wording and add clarifications and examples to the guide on
    configuring keystone as an IdP.

    Partial-bug: #1793374

    Change-Id: I5feee2da6b8b8f15e1de2e2f1ba493f31babb35f

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/627972
Committed: https://git.openstack.org/cgit/openstack/keystone/commit/?id=4d7bc6a36deefbe816390f94692fddb86bb2c6eb
Submitter: Zuul
Branch: master

commit 4d7bc6a36deefbe816390f94692fddb86bb2c6eb
Author: Colleen Murphy <email address hidden>
Date: Fri Dec 21 17:46:37 2018 -0800

    Reorganize guide on configuring a keystone SP

    The federation guide on configuring keystone as a Service Provider is
    disjointed and hard to follow. This patch reorganizes it as follows to
    improve the flow by first moving the instructions on creating an IdP,
    mapping, and protocol in keystone to the beginning, since all other
    steps in this guide depend on understanding what these objects are and
    deciding on a name for them, and second by consolidating instructions on
    creating role assignments into the section on mappings, since these two
    concepts are informed by one another and splitting them apart makes
    it difficult to mentally connect them. It also cleans up and clarifies
    some of the wording and pares down unnecessary tangents.

    Partial-bug: #1793374

    Change-Id: Ib09f127f47a0897cc1be03428bfae70f3f18e174

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/627975
Committed: https://git.openstack.org/cgit/openstack/keystone/commit/?id=708d3f4d59ceb3df78b3c5d6820c6b150f25dfb6
Submitter: Zuul
Branch: master

commit 708d3f4d59ceb3df78b3c5d6820c6b150f25dfb6
Author: Colleen Murphy <email address hidden>
Date: Fri Dec 21 19:08:26 2018 -0800

    Add section on configuring protected auth paths

    Without this change, the federation guide does not do a good job of
    explaining which URL paths should be protected by a federation-capable
    auth module and why. Instead, the SP-specific guides give code samples
    with no context, which makes it confusing to understand how to modify
    the paths in the examples to fit one's own deployment. This change adds
    that introduction.

    Partial-bug: #1793374

    Change-Id: I5cf940e0c54e5dd89cd3db810f8b5889a8ddce2e

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/627976
Committed: https://git.openstack.org/cgit/openstack/keystone/commit/?id=069392fe95f59d3ab5933644adefb27a48cfb4b3
Submitter: Zuul
Branch: master

commit 069392fe95f59d3ab5933644adefb27a48cfb4b3
Author: Colleen Murphy <email address hidden>
Date: Fri Dec 21 19:44:17 2018 -0800

    Consolidate WebSSO guide into SP instructions

    The WebSSO documentation does not have a good flow with the rest of the
    federation guide. It includes instructions about the remote_id_attribute
    which is not WebSSO specific, as well as instructions for configuring
    Apache which is partly redundant with the SP-specific instructions. This
    change consolidates the guide into the main guide so that it makes sense
    with the rest of the document.

    Partial-bug: #1793374

    Change-Id: I0c8fa537a950090f85b3cb4a4aac6c896f02db89

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/627982
Committed: https://git.openstack.org/cgit/openstack/keystone/commit/?id=83c37f4a943e8e7181f2f6f973b82885f598e010
Submitter: Zuul
Branch: master

commit 83c37f4a943e8e7181f2f6f973b82885f598e010
Author: Colleen Murphy <email address hidden>
Date: Fri Dec 21 19:52:45 2018 -0800

    Enhance the shibboleth guide

    Update, reorganize and clean up the shibboleth guide. Remove the full
    example of shibboleth2.xml, it does not add anything useful and just
    creates clutter. Use the systemctl command to modernize the service
    management commands. Add examples of configuring all required endpoints
    in Apache to mirror the new section on configuring protected endpoints
    in the main guide and replace the lost examples from the consolidated
    WebSSO guide. Add a section on configuring REMOTE_USER and
    attributes-map.xml. Remove use of ``a2enmod`` since the Shibboleth
    module is automatically enabled by the package on all supported distros.

    Partial-bug: #1793374

    Change-Id: I0eed3420aa49fdc75349a467e91f8e7f22b075e9

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/627993
Committed: https://git.openstack.org/cgit/openstack/keystone/commit/?id=dcb9d8d084a60c1e8f83adf0a9ae84df9cc85ebe
Submitter: Zuul
Branch: master

commit dcb9d8d084a60c1e8f83adf0a9ae84df9cc85ebe
Author: Colleen Murphy <email address hidden>
Date: Fri Dec 21 20:12:58 2018 -0800

    Enhance the mellon guide

    Update, reorganize and clean up the mellon guide. Use the systemctl
    command to modernize the service management commands. Add examples of
    configuring all required endpoints in Apache to mirror the new section
    on configuring protected endpoints in the main guide and replace the
    lost examples from the consolidated WebSSO guide. Remove use of
    ``a2enmod`` since the Mellon module is automatically enabled by the
    package on all supported distros.

    Partial-bug: #1793374

    Change-Id: If17d8e73688775b8aeae88f5d0907273bc8de193

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/628037
Committed: https://git.openstack.org/cgit/openstack/keystone/commit/?id=ec7f8b95b353ea1e172cc15b9703367f1edd0cc1
Submitter: Zuul
Branch: master

commit ec7f8b95b353ea1e172cc15b9703367f1edd0cc1
Author: Colleen Murphy <email address hidden>
Date: Fri Dec 21 20:17:53 2018 -0800

    Enhance the openidc guide

    Update, reorganize and clean up the openidc guide. Use Google as a
    concrete IdP example. Use the systemctl command to modernize the service
    management commands. Add examples of configuring all required endpoints
    in Apache to mirror the new section on configuring protected endpoints
    in the main guide and replace the lost examples from the consolidated
    WebSSO guide. Remove use of ``a2enmod`` since the Mellon module is
    automatically enabled by the package on all supported distros.

    Closes-bug: #1793374

    Change-Id: Ie5dc4899beff77f121cc62bc8d56763c7671ecc3

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/keystone 15.0.0.0rc1 release candidate.