Improve keystone.conf [saml] documentation

Change-Id: I25bbf4fed9f5358dd025b85be57e5f5c079e585d

keystone/conf/saml.py

@@ -20,102 +20,118 @@ assertion_expiration_time = cfg.IntOpt(
     'assertion_expiration_time',
     default=3600,
     help=utils.fmt("""
-Default TTL, in seconds, for any generated SAML assertion created by Keystone.
+Determines the lifetime for any SAML assertions generated by keystone, using
+`NotOnOrAfter` attributes.
 """))
 
 xmlsec1_binary = cfg.StrOpt(
     'xmlsec1_binary',
     default='xmlsec1',
     help=utils.fmt("""
-Binary to be called for XML signing. Install the appropriate package, specify
+Name of, or absolute path to, the binary to be used for XML signing. Although
-absolute path or adjust your PATH environment variable if the binary cannot be
+only the XML Security Library (`xmlsec1`) is supported, it may have a
-found.
+non-standard name or path on your system. If keystone cannot find the binary
+itself, you may need to install the appropriate package, use this option to
+specify an absolute path, or adjust keystone's PATH environment variable.
 """))
 
 certfile = cfg.StrOpt(
     'certfile',
     default=constants._CERTFILE,
     help=utils.fmt("""
-Path of the certfile for SAML signing. For non-production environments, you may
+Absolute path to the public certificate file to use for SAML signing. The value
-be interested in using `keystone-manage pki_setup` to generate self-signed
+cannot contain a comma (`,`).
-certificates. Note, the path cannot contain a comma.
 """))
 
 keyfile = cfg.StrOpt(
     'keyfile',
     default=constants._KEYFILE,
     help=utils.fmt("""
-Path of the keyfile for SAML signing. Note, the path cannot contain a comma.
+Absolute path to the private key file to use for SAML signing. The value cannot
+contain a comma (`,`).
 """))
 
 idp_entity_id = cfg.StrOpt(
     'idp_entity_id',
+    max_length=1024,
     help=utils.fmt("""
-Entity ID value for unique Identity Provider identification. Usually FQDN is
+This is the unique entity identifier of the identity provider (keystone) to use
-set with a suffix. A value is required to generate IDP Metadata. For example:
+when generating SAML assertions. This value is required to generate identity
-https://keystone.example.com/v3/OS-FEDERATION/saml2/idp
+provider metadata and must be a URI (a URL is recommended). For example:
+`https://keystone.example.com/v3/OS-FEDERATION/saml2/idp`.
 """))
 
 idp_sso_endpoint = cfg.StrOpt(
     'idp_sso_endpoint',
     help=utils.fmt("""
-Identity Provider Single-Sign-On service value, required in the Identity
+This is the single sign-on (SSO) service location of the identity provider
-Provider's metadata. A value is required to generate IDP Metadata. For example:
+which accepts HTTP POST requests. A value is required to generate identity
-https://keystone.example.com/v3/OS-FEDERATION/saml2/sso
+provider metadata. For example:
+`https://keystone.example.com/v3/OS-FEDERATION/saml2/sso`.
 """))
 
 idp_lang = cfg.StrOpt(
-    'idp_lang', default='en',
+    'idp_lang',
+    default='en',
     help=utils.fmt("""
-Language used by the organization.
+This is the language used by the identity provider's organization.
 """))
 
 idp_organization_name = cfg.StrOpt(
     'idp_organization_name',
+    default='SAML Identity Provider',
     help=utils.fmt("""
-Organization name the installation belongs to.
+This is the name of the identity provider's organization.
 """))
 
 idp_organization_display_name = cfg.StrOpt(
     'idp_organization_display_name',
+    default='OpenStack SAML Identity Provider',
     help=utils.fmt("""
-Organization name to be displayed.
+This is the name of the identity provider's organization to be displayed.
 """))
 
 idp_organization_url = cfg.StrOpt(
     'idp_organization_url',
+    default='https://example.com/',
     help=utils.fmt("""
-URL of the organization.
+This is the URL of the identity provider's organization. The URL referenced
+here should be useful to humans.
 """))
 
 idp_contact_company = cfg.StrOpt(
     'idp_contact_company',
+    default='Example, Inc.',
     help=utils.fmt("""
-Company of contact person.
+This is the company name of the identity provider's contact person.
 """))
 
 idp_contact_name = cfg.StrOpt(
     'idp_contact_name',
+    default='SAML Identity Provider Support',
     help=utils.fmt("""
-Given name of contact person
+This is the given name of the identity provider's contact person.
 """))
 
 idp_contact_surname = cfg.StrOpt(
     'idp_contact_surname',
+    default='',
     help=utils.fmt("""
-Surname of contact person.
+This is the surname of the identity provider's contact person.
 """))
 
 idp_contact_email = cfg.StrOpt(
     'idp_contact_email',
+    default='support@example.com',
     help=utils.fmt("""
-Email address of contact person.
+This is the email address of the identity provider's contact person.
 """))
 
 idp_contact_telephone = cfg.StrOpt(
     'idp_contact_telephone',
+    default='+1 800 555 0100',
     help=utils.fmt("""
-Telephone number of contact person.
+This is the telephone number of the identity provider's contact person.
 """))
 
 idp_contact_type = cfg.StrOpt(
@@ -123,24 +139,26 @@ idp_contact_type = cfg.StrOpt(
     default='other',
     choices=['technical', 'support', 'administrative', 'billing', 'other'],
     help=utils.fmt("""
-The contact type describing the main point of contact for the identity
+This is the type of contact that best describes the identity provider's contact
-provider.
+person.
 """))
 
 idp_metadata_path = cfg.StrOpt(
     'idp_metadata_path',
     default='/etc/keystone/saml2_idp_metadata.xml',
     help=utils.fmt("""
-Path to the Identity Provider Metadata file. This file should be generated with
+Absolute path to the identity provider metadata file. This file should be
-the keystone-manage saml_idp_metadata command.
+generated with the `keystone-manage saml_idp_metadata` command. There is
+typically no reason to change this value.
 """))
 
 relay_state_prefix = cfg.StrOpt(
     'relay_state_prefix',
     default='ss:mem:',
     help=utils.fmt("""
-The prefix to use for the RelayState SAML attribute, used when generating ECP
+The prefix of the RelayState SAML attribute to use when generating enhanced
-wrapped assertions.
+client and proxy (ECP) assertions. In a typical deployment, there is no reason
+to change this value.
 """))