Open Stack

The existing documentation on setting up mod_auth_mellon 
(https://docs.openstack.org/keystone/latest/advanced-topics/federation/mellon.html) 
is sparse.

Our experience with using mod_auth_mellon either in the context of 
OpenStack federation or simply as a SAML SP working in conjunction with 
an IdP is the process is often fraught with problems of the following 
nature:

* Lack of understanding SAML concepts and terminology
* Inability to collect relevant data when problems occur
* Inability to diagnose the root cause of problems
* Inability read and comprehend the content of SAML messages
* Improper use of Mellon configuration directives
* Lack of understanding with regards to SAML metadata, it's importance,
   it's generation, it's consumption, it's distribution and it's
   synchronization (e.g. consistency).
* Inability to understand how SAML authentication information
   is communicated to Web Apps (e.g. Keystone and it's mapping engine).
* Configuration problems related to proxies, load balancers,
   and other HA issues.
* Improper use of TLS or TLS configuration issues.

I tried to collect every piece of relevant information related to 
deploying mod_auth_mellon such that you get all you need to know but 
nothing you don't need to know. I tried to organize the material so you 
don't need to read it in a linear fashion, you can jump into a topic and 
there are enough links inside you can easily navigate to related 
material. I also tried to make the document vendor neutral with 
callout's to specific operating system concerns.

We are proposing this document be included with upstream Mellon as part 
of it's documentation. Hopefully this will be a living document with 
others contributing. The source format is AsciiDoc.

We haven't decided on a final place for the document to live. Red Hat 
will maintain a version of the document in it's documentation set. It's 
not clear yet how upstream will offer the document but they are 
appreciative of contribution, it will almost certainly be incorporated 
into their github repository, but I'm not sure about how a "rendered" 
version would be hosted.

For now you can view the initial version of the document on my personal 
page.

https://jdennis.fedorapeople.org/doc/mellon-doc/mellon.html

Comments, corrections, additions, etc. are welcome and encouraged.
-- 
John