Federated documentations lacks a concise introduction

Bug #1793374 reported by Lance Bragstad on 2018-09-19
14
This bug affects 3 people
Affects Status Importance Assigned to Milestone
OpenStack Identity (keystone)
Low
Colleen Murphy

Bug Description

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

Changed in keystone:
importance: Undecided → Low
status: New → Triaged
tags: added: documentation
tags: added: federation
description: updated
Colleen Murphy (krinkle) on 2018-09-19
Changed in keystone:
assignee: nobody → Colleen Murphy (krinkle)
Egor Panfilov (erakli) on 2018-10-07
description: updated

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) wrote :

I will like to be assigned

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

Changed in keystone:
status: Triaged → In Progress

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Changed in keystone:
status: In Progress → Fix Released

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

Changed in keystone:
milestone: none → stein-2

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

To post a comment you must log in.
This report contains Public information  Edit
Everyone can see this information.

Other bug subscribers