From dfac754aa50f3460352b68f52e9722fdc9f4e3d3 Mon Sep 17 00:00:00 2001 From: Dolph Mathews Date: Mon, 11 Jul 2016 11:14:31 -0500 Subject: [PATCH] Improve keystone.conf [saml] documentation Change-Id: I25bbf4fed9f5358dd025b85be57e5f5c079e585d --- keystone/conf/saml.py | 78 ++++++++++++++++++++++++++----------------- 1 file changed, 48 insertions(+), 30 deletions(-) diff --git a/keystone/conf/saml.py b/keystone/conf/saml.py index cc7f771379..a8d400511a 100644 --- a/keystone/conf/saml.py +++ b/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 -absolute path or adjust your PATH environment variable if the binary cannot be -found. +Name of, or absolute path to, the binary to be used for XML signing. Although +only the XML Security Library (`xmlsec1`) is supported, it may have a +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 -be interested in using `keystone-manage pki_setup` to generate self-signed -certificates. Note, the path cannot contain a comma. +Absolute path to the public certificate file to use for SAML signing. The value +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 -set with a suffix. A value is required to generate IDP Metadata. For example: -https://keystone.example.com/v3/OS-FEDERATION/saml2/idp +This is the unique entity identifier of the identity provider (keystone) to use +when generating SAML assertions. This value is required to generate identity +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 -Provider's metadata. A value is required to generate IDP Metadata. For example: -https://keystone.example.com/v3/OS-FEDERATION/saml2/sso +This is the single sign-on (SSO) service location of the identity provider +which accepts HTTP POST requests. A value is required to generate identity +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 -provider. +This is the type of contact that best describes the identity provider's contact +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 -the keystone-manage saml_idp_metadata command. +Absolute path to the identity provider metadata file. This file should be +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 -wrapped assertions. +The prefix of the RelayState SAML attribute to use when generating enhanced +client and proxy (ECP) assertions. In a typical deployment, there is no reason +to change this value. """))