Divided the keystone docs into four categories, depending
upon the usage criteria: general information (which will
be common for all), developer documentation,
user documantation and operator documentation.
Change-Id: I2f5dd41acd9874739accc54c4f4fd69460b58334
This change removes the unused "warnerrors" setting that
was part of [pbr] which was replaced by "warning-is-error"
in sphinx 1.5 and above[0]. This also fixes any warnings
and errors that came up when running `tox -edocs` using
this new feature:
- Invalid code example highlighting
- Redundant loading of todo extension
[0] http://lists.openstack.org/pipermail/openstack-dev/2017-March/113085.html
Change-Id: I9a8789b448ffa199b4539f57e692bac251d75036
It can be easy, even for seasoned operators, to either forget to restart the
web server or to cautiously avoid restarting the webserver unless instructed
to do so. Since there are notes all over the rest of the documentation to
restart the web server after making configuration changes, add a similar note
to the WebSSO section for consistency.
Change-Id: I1d171a2f0ccc2b70fe3e2e48fe2f2303c515b9a6
python-openstackclient is friendlier than cURL and is able to handle
listing resources available to federated users as well as scoping
unscoped tokens, so let's use openstackclient in the examples for
performing federated authentication.
Change-Id: Ie4578d4a371b50ad8c2b2a6836caba580c120cd4
Make corrections and clarifications to the OpenID Connect federation
plugin documentation, including:
- Generalize the note about Remote IDs to include OpenID Connect
- Add the https:// scheme to the notes about Google's remote ID.
Originally Google's Issuer Identifier did not use the https://
scheme. It now claims to allow both[1] but in testing I often ran
into the error "Could not find Identity Provider:
https://accounts.google.com." when the remote-id was given as
"accounts.google.com".
- Make shell examples consistent with each other by including prompt
symbols and "sudo" where needed
- Fix the apache module configuration instructions: on Ubuntu, the
package installed in the earlier step already adds the LoadModule
config, but does not automatically enable the module
- Fix OIDCRedirectURI directive examples: fix typo and remove /redirect
ending, which would cause a 404 error
Also, this patch changes references to the 'oidc' plugin to 'openid'
since 'oidc' does not exist. 'mapped' could also be used as the name of
this plugin and protocol[2]. However, the documentation is structured in
a such a way that it demonstrates using both SAML And OIDC plugins side
by side, which is only possible when they have different names. Rather
than trying to decouple these examples this patch opts to keep the
openid plugin examples distinct from the SAML plugin examples.
[1] https://developers.google.com/identity/protocols/OpenIDConnect
[2] https://git.openstack.org/cgit/openstack/keystone-specs/tree/specs/keystone/juno/generic-mapping-federation.rst
Change-Id: Ie5a07f9d6f3571b0559f91c9620f5328e4c6d7cc
Make corrections to the mod_auth_mellon federation documentation for
consistency and clarity, including:
- Remove reference to shibboleth.xml when explaining the remote-id
attribute in the main federation configuration instructions, as this
does not generalize to all IdPs
- Change references from /etc/httpd to /etc/apache2 because the
document begins with an apt-get so it follows that the rest of the
examples should assume a Debian-like environment
- Change references to example IdP 'idp_1' to 'myidp' for consistency
with the shibboleth examples
- Change references to example protocol 'saml2' to 'mapped' since the
saml2 auth plugin was removed[1]
- Remove references to wsgi-keystone.conf since devstack just calls it
keystone.conf, and enabling this vhost is already covered in the
"Running Keystone in HTTPD" section
- Remove reference to the ssl mod: it's obviously recommended but not
strictly relevant to this topic
- Remove instruction to restart apache immediately after enabling
auth_mellon, as it would fail while Mellon is not yet fully
configured. The document already mentions restarting apache after
Mellon is configured.
- Add a link to the mellon_create_metadata.sh script, since this does not
come as an executable with the mod package.
- Add tip about the SP metadata file generated by mod_auth_mellon
- Move paragraph about fetching the IdP metadata to the end of the
section so that the information about generating and uploading the
SP metadata is grouped together
[1] https://review.openstack.org/#/c/374508/
Change-Id: I47255db5e762bd2d2901b78afba2b1efa0c0f224
The documentation was originally written using imprecise language.
This resulted in lots of confusion when read.
Change-Id: I9f1af3cee3216c4c10c0bf6d91a6353a28f27dd5
The openstack.org pages now support https and our references to
the site should by default be one signed by the organization.
Change-Id: I30a462e03d1fd7852511e22cac34c6bc0e8917f4
There were several problems with keystone-manage mapping_engine
* It aborts with a backtrace because of wrong number of arguments
passed to the RuleProcessor, it was missing the mapping_id
parameter.
* Error messages related to input data were cryptic and inprecise.
* The --engine-debug option did not work.
A fake mapping_id is now generated and passed to the RuleProcessor.
If there was invalid data passed it was nearly impossible to determine
what was causing the error, the command takes 2 input files, but which
file contained the error? At what line? Why? For example I was
consistently getting this error:
Error while parsing line: '{': need more than 1 value to unpack
and had no idea of what was wrong, the JSON looked valid to me. Turns
out the assertion file is not formatted as JSON (yes this is
documented in the help message but given the rules are JSON formatted
and the RuleProcessor expects a dict for the assertion_data it's
reasonsable to assume the data in the assertion file is formatted as a
JSON object).
The documentation in mapping_combinations.rst added a note in the
section suggesting the use of the keystone-manage mapping_engine
tester alerting the reader to the expected file formats.
The MappingEngineTester class was refactored slighly to allow each
method to know what file it was operating on and emit error messages
that identify the file. The error message in addition to the pathname
now includes the offending line number as well. As a bonus it doesn't
fail if there is a blank line. The error message now looks like this:
assertion file input.txt at line 4 expected 'key: value' but found 'foo' see help for file format
The mapping_engine.LOG.logger level is now explictily set to DEBUG
when --engine-debug is passed instead of (mistakenly assuming it
defaulted to DEBUG) otherwise it's set to WARN.
Closes-Bug: 1655182
Signed-off-by: John Dennis <jdennis@redhat.com>
Change-Id: I2dea0f38b127ec185b79bfe06dd6a212da75cbca
This change fixes multiple issues of "WARNING: document isn't included
in any toctree" that were appearing when building "tox -edocs" by adding
the pages to the toctree in index.rst.
Change-Id: Iefc19e4aa8a950ffc35256e0fd22bb6bc7b3d2da
Partial-Bug: #1602422
There are multiple tracebacks and warnings being thrown whenever
the keystone docs are built due to documents being moved/deleted as
well as formatting issues in a couple places.
This fixes a few of the warnings due to broken links and fixes a few
of the method docs.
Master: http://paste.openstack.org/show/591730/
This Patch: http://paste.openstack.org/show/591735/
Change-Id: I11cbbc7a10fa24dcbf67c76e3061a39a58529c06
Partial-Bug: #1602422
Some time ago, the default WSGIScriptAlias was changed from
/var/www/keystone/main to /usr/local/bin/keystone-wsgi-public
and /usr/local/bin/keystone-wsgi-admin.
The federation docs still referred to /var/www/keystone/main which
won't work in default configuration of keystone within apache.
Change-Id: Ib9c059d30c12e982a6b0b5b7fcbca6da650650ba
The saml2 auth plugin was already removed in this release (ocata)
and therefore is no longer a need to document that it'll be removed.
The patch that removed the plugin was:
https://review.openstack.org/#/c/374508/
bp removed-as-of-ocata
Change-Id: I19da4726fd83d70e01118ff4bf98802de584f7bb
This patch updates and adds examples and clarifies some instructions
that were unclear or needed additional explanation for the Federation
configuration overview, the Shibboleth setup instructions, and the
horizon WebSSO documentation. These changes include:
- Change instances of 'saml2' to 'mapped' where appropriate, since the
documentation currently notes that using 'saml2' is deprecated
- Make note of differences when using keystone-to-keystone federation
and keystone as an Identity Provider where appropriate
- Linkify section contents listings
- Add examples using openstackclient
- The examples include adding both a domain and a project for
federated users, since there seems to be a horizon bug that
cause federated users to not be able to log in if their group is
only authorized on a domain and no projects[1] (not yet filed)
- Move discussion of remote IDs from the websso section to the main
configuration section, since the instructions to add identity
providers are already in the main section and this is really more
about keystone configuration than horizon configuration
- Add example mapping rules for both a keystone-to-keystone
configuration and a Shibboleth (using testshib.org) configuration
- Correct description of token response format in "Performing
federated authentication" section
- Enhance description of configuration options for keystone as an IdP
- Make the names and domain names of Service Providers and Identity
Providers consistent throughout the documentation (beta and BETA
were especially confusing)
- Change references to wsgi-keystone.conf to keystone.conf since
that's what devstack calls it now
- Change keystone-to-keystone authentication demo to use keystoneauth
instead of cURL (inspired by rodrigods's blog post on
keystone-to-keystone[2])
- Move the note about fetching the SP's metadata to after
shibboleth2.xml configuration is done, since the entityID needs to
be set in the metadata for the IdP to recognize it
- Enhance the description of what needs to be changed in
shibboleth2.xml and use the package-generated example
- Remove the section on removing REMOTE_USER from shibboleth2.xml, as
this is needed to allow keystone to look up the remote user in the
SAML assertion
- Remove sections about keystone v3 from the WebSSO, that's old news
and it's the default now
- Add a step to ensure the SSO redirect template is copied into place,
since devstack does not do that by default
[1] http://git.openstack.org/cgit/openstack/django_openstack_auth/tree/openstack_auth/backend.py?h=2.4.1#n174
[2] http://blog.rodrigods.com/it-is-time-to-play-with-keystone-to-keystone-federation-in-kilo/
Change-Id: Id3ad18c43ace9e43d05b0acf966e577c909fa3e8
A sample mapping does not contain valid JSON and will fail to validate.
Replace the "=" with ":" to correct the example.
Change-Id: I0c6c64ad131da1120d6acad903d5388e30eb7604
When the API reference was moved and the old pages cleaned up, a lot of
dead links were created. This patch fixes them for the documentation on
"Configuring Keystone for Federation".
Moreover, a lot of the link text was nondescriptive, which makes the
documentation inaccessible for screen readers (see the W3C
guideline[1]). This patch cleans that up as well if the link URL
needed to be updated anyway.
[1] https://www.w3.org/TR/WCAG20-TECHS/H30.html
Change-Id: I58803276d9b06bad0252da2494c81a46c951916f
Fixed some more trivial doc items missed in the previous patch.
* Removed extra underlining characters
* Removed extra blank lines at the end of the file
Change-Id: Ida511ff6fc0d28ee68c1ded1e272ed9cba1be4d7
The mapping schema is now super long and complex, and anyone interested
in it can go to our code base and read about it, no need to track in
the doc.
Closes-bug: #1617361
Change-Id: I8a83dd91d0cde7af2a10e02b75659704baad5496
keystone-all command was removed but no alternative for running
keystone in developer mode was added. Update documentation with uwsgi
command and update keystone-all reference.
Change-Id: Ia949620de21c1b05127769c6da249b38d83cda9c
When reviewing If74aaf07b77399f1648843280153c7523de5eb38 I noticed that
one of the examples was incorrect.
Change-Id: I4d5d88ea45c00fe874382c06a0626ea6aaeb87c9
Related-Bug: #1575057
several of the federated identity docs were spread out in hard
to find locations. this puts the documentation more front and
centrer. expect detailed changes for each docs in future patches.
Change-Id: I82ba117dfd02f921d72b9f010becad57da03e090
The documentation for setting up Shibboleth gives you a snippet of code
that you can copy and paste and then later in notes tells you to remove
options for apache 2.4.
At this point apache 2.4 should be considered the default and not the
exception and we can easily convey this information in the config
snippet and make copying it easier than having to re-read documentation
to figure out why options are unknown.
Change-Id: I9546b6b9cabdaffdb0473711dc07fc234f00d297
We recently added a new federation call to Keystone that will allow federated
authentication flows for a specific Identity Provider. This commit adds
documentation around configuring httpd modules for the newly added call and
horizon configuration.
Co-Authored-By: Lin Hua Cheng <os.lcheng@gmail.com>
Change-Id: Id334e979c951387b1d70da70fc5d4939a6e7d6a6
related: bp federation-idp-websso
Closes-Bug: 1491910
Related-Bug: 1491916
mod_auth_mellon is an authentication module for Apache.
It authenticates the user against a SAML 2.0 IdP, and
grants access to directories depending on attributes
received from the IdP. It can be used by Keystone to provide
authentication via the
keystone.contrib.federation.backends.sql.Federation federation
authentication driver for the saml2 auth method.
closes-bug: #1470952
Change-Id: Id0467abe37ac4c4c74832ca5bb98f98c63afded1
Until now all the docs assumed the OS-FEDERATION is still an extension.
Since this is not true since Kilo release, we should also update our
documentation.
We also moved some of the files from the ``extension`` directory to the
``federation`` one.
Change-Id: I7f71fea55accaaaf38b2ee069fab9726c1045b4c
Closes-Bug: #1466092