Commit Graph

40 Commits

Author SHA1 Message Date
Samriddhi Jain 459f078d0c Reorganised keystone documentation structure
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
2017-06-22 13:26:46 +05:30
Ngo Quoc Cuong 4a9a05b9c8 Trivial fix typo in doc
Change-Id: I3f8fd55408dfeed6933526dc2fe903eda1562c35
2017-05-08 13:10:08 +07:00
Jenkins 7048b6759b Merge "Remove pbr warnerrors in favor of sphinx check" 2017-03-09 01:21:36 +00:00
Gage Hugo 32da690e50 Remove pbr warnerrors in favor of sphinx check
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
2017-03-03 14:04:10 -06:00
Jenkins 364285000e Merge "Exchange cURL examples for openstackclient" 2017-03-02 15:13:28 +00:00
Colleen Murphy 67b148f988 Add instruction to restart apache
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
2017-02-28 08:55:27 +01:00
Colleen Murphy f5649079bb Exchange cURL examples for openstackclient
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
2017-02-27 21:35:20 +01:00
Colleen Murphy 6f4e31e4f4 Correct and enhance OpenId Connect docs
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
2017-02-25 11:39:06 +01:00
Colleen Murphy 95afd48fde Correct and enhance Mellon federation docs
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
2017-02-24 21:32:12 +01:00
David Stanek 0015e1a41e Federated mapping doc improvements
The documentation was originally written using imprecise language.
This resulted in lots of confusion when read.

Change-Id: I9f1af3cee3216c4c10c0bf6d91a6353a28f27dd5
2017-02-10 00:03:59 +00:00
Eric Brown 30d9095d28 Use https for docs.openstack.org references
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
2017-01-30 16:05:08 -08:00
Jenkins 0a4ca273ae Merge "Updates to project mapping documentation" 2017-01-20 20:42:21 +00:00
Jenkins bc8a145de1 Merge "Add documentation for auto-provisioning" 2017-01-20 01:49:39 +00:00
David Stanek e988490f1d Updates to project mapping documentation
Change-Id: I8d3c510a9fb5c86a13bae7e3129069ccee741929
2017-01-20 00:14:28 +00:00
Lance Bragstad ca5117778e Add documentation for auto-provisioning
We need some concrete examples that describe how auto-provisioning
works.

bp shadow-mapping

Change-Id: I503316840baa84b4bad7824f599dc69da6044925
2017-01-19 16:58:28 +00:00
pallavi 7f2b7e58e7 Fix typo in shibboleth federation docs
The WSGIScriptAlias is actually a WSGIScriptAliasMatch

Change-Id: I329b08680a380fee4fb964e8afa18910b47ce4b9
2017-01-17 23:31:19 -05:00
John Dennis f2d0f8c9ab Fix keystone-manage mapping_engine tester
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
2017-01-12 05:50:43 +00:00
Gage Hugo ebbc06ebb9 Fixed not in toctree warnings when building docs
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
2017-01-07 14:20:50 -06:00
Jenkins bc10ba452a Merge "Fixed multiple warnings in tox -edocs" 2016-12-08 13:54:18 +00:00
Eric Brown 4de9d6b111 Trivial indentation corrections in mappings doc
Some of the indentation in the federation mapping doc were off.

Change-Id: Idf83f92b23451abb1b712430dc55faf53ea24f37
2016-12-07 16:26:15 -08:00
Gage Hugo b9c8963d0a Fixed multiple warnings in tox -edocs
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
2016-12-07 16:26:53 -06:00
Eric Brown e120ac341a SAML federation docs refer to old WSGIScriptAlias
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
2016-11-28 17:25:52 -08:00
Eric Brown 2d540f5cea Remove reference to future removal of saml
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
2016-11-14 17:04:43 -08:00
Boris Bobrov 731a766ef3 Fix broken links in the docs
Change-Id: If2f462a240485e4c1b904fc76d572f069d3f3df2
2016-10-31 17:18:26 +03:00
Jenkins 8e07232006 Merge "Update, correct, and enhance federation docs" 2016-10-15 12:36:54 +00:00
Colleen Murphy 38f79a8edf Update, correct, and enhance federation docs
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
2016-10-14 20:33:25 +02:00
jolie 9fa78cb9c8 [doc] Correct mapping JSON example
A sample mapping does not contain valid JSON and will fail to validate.
Replace the "=" with ":" to correct the example.

Change-Id: I0c6c64ad131da1120d6acad903d5388e30eb7604
2016-10-10 03:49:22 +00:00
Colleen Murphy c2fd1f6af5 Fix links on configure_federation documentation
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
2016-09-13 15:40:53 -07:00
Eric Brown 3c3df9049b More nit doc fixes
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
2016-09-07 11:27:14 -07:00
Marek Denis c613dd3a6c Remove mapping schema from the doc
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
2016-08-29 02:32:59 +00:00
Ryosuke Mizuno 293c891dcf Fix broken link of federation docs
Fixed a place that was in some broken links in the federation document.

Change-Id: I296c4e2cff718f3eac02fa1c14563a2a4437cb80
2016-05-20 20:01:48 +09:00
nonameentername f6ac0661bf Update documentation to remove keystone-all
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
2016-05-10 17:06:49 -05:00
David Stanek 70b798641a Fixes example in the mapping combinations docs
When reviewing If74aaf07b77399f1648843280153c7523de5eb38 I noticed that
one of the examples was incorrect.

Change-Id: I4d5d88ea45c00fe874382c06a0626ea6aaeb87c9
Related-Bug: #1575057
2016-05-05 15:48:04 +00:00
Dolph Mathews cafbe1b9f0 Correct RST syntax for a code block
The code block was being rendered as a plaintext paragraph:

  http://docs.openstack.org/developer/keystone/federation/federated_identity.html#configure-apache-httpd-for-mod-auth-mellon

Change-Id: I183d220228b3a2e804c4dcc68164da362523b3d0
2016-04-29 15:54:39 -05:00
Steve Martinelli e082c72861 group federated identity docs together
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
2016-04-13 05:42:51 +00:00
Jamie Lennox c7047d8321 Exclude old Shibboleth options from docs
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
2015-11-13 12:15:49 +11:00
Dave Chen df2ef52390 Correct the filename
There is an extra `s` in filename.

Change-Id: Ic5ebc7cc63be7185fc830c1f77fbac447d155399
2015-10-14 11:27:58 +08:00
Lance Bragstad 609518ff2b Add documentation for configuring IdP WebSSO
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
2015-09-18 11:09:54 -07:00
Rich Megginson 4f36d900e6 add federation docs for mod_auth_mellon
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
2015-07-21 12:10:30 -06:00
Marek Denis 8cb9548ad0 OS-FEDERATION no longer extension in docs
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
2015-07-01 15:09:54 +02:00