completed most configuration docs in rst format

docs/_static/custom.css

@@ -0,0 +1,3 @@
+.tight-table td {    
+    white-space: normal !important;
+}

docs/conf.py

@@ -85,6 +85,9 @@
 #
 html_theme = 'sphinx_rtd_theme'
 
+def setup(app):
+    app.add_stylesheet('custom.css')
+
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.

docs/config-elements/compatibility.rst

@@ -1,2 +1,17 @@
 ``<compatibility>`` Element
-===========================
+===========================
+This is an **optional** child element of the :doc:`sustainsys.saml2 <sustainsys-saml2>` element.
+
+Enables overrides of default behaviour to increase compatibility with identity providers.
+
+Attributes
+----------
+``unpackEntitiesDescriptorInIdentityProviderMetadata`` (Optional)
+    If an ``EntitiesDescriptor`` element is found when loading metadata for an IdentityProvider, automatically 
+    check inside it if there is a single ``EntityDescriptor`` and in that case use it.
+
+``IgnoreAuthenticationContextInResponse``
+    Do not read the ``AuthnContext`` element in Saml2Response. If you do not need these values to be present as 
+    claims in the generated identity, using this option can prevent XML format 
+    errors (``System.Xml.XmlException: ID0013: The value must be an absolute URI``), when value cannot parse 
+    as absolute URI.

docs/config-elements/contact-person.rst

@@ -1,2 +1,31 @@
 ``<contactPerson>`` Element
-===========================
+===========================
+Optional child element of the :doc:`metadata`  element.
+
+Attributes
+----------
+``type`` 
+    The type attribute indicates the type of the contact and is picked from the ``ContactType`` enum. Valid values are:
+
+    * ``Administrative``
+    * ``Billing``
+    * ``Other``
+    * ``Support``
+    * ``Technical``
+
+``company`` (Optional)
+    Name of the person's company.
+
+``givenName`` (Optional)
+    Given name of the contact person.
+
+``surname`` (Optional)
+    Surname of the contact person.
+
+``phoneNumber`` (Optional)
+    Phone number of the contact person. The SAML standard allows multiple phone number to be specified. Saml2 supports 
+    that, but not through the configuration file.
+
+``email`` (Optional)
+    Email address of the person. The SAML standard allows multiple email addresses to be specified. Saml2 
+    supports that, but not through the configuration file.

docs/config-elements/federations.rst

@@ -1,2 +1,27 @@
 ``<federations>`` Element
-=========================
+=========================
+This is an **optional** child element of the :doc:`sustainsys.saml2 <sustainsys-saml2>` element.
+
+This element contains a list of federations that the service provider knows and trusts.
+
+As with some other elements, individual items are added via an ``<add>`` element inside this element,
+so you'll end up with XML that looks like the following:
+
+.. code-block:: xml
+
+    <federations>
+        <add metadataLocation="" allowUnsolicitedAuthnResponse="" />
+        <add metadataLocation="" allowUnsolicitedAuthnResponse="" />
+        ...
+    </federations>
+
+Attributes
+----------
+``metadataLocation``
+    URL to the full metadata of the federation. Saml2 will download the metadata and add all identity 
+    providers found to the list of known and trusted identity providers. The location can be a URL, an 
+    absolute path to a local file or an app relative path (e.g. ``~/App_Data/IdpMetadata.xml``)
+
+``allowUnsolicitedAuthnResponse``
+    ``true`` or ``false`` value indicating whether unsolicited authn responses should be allowed from the 
+    identity providers in the federation.

docs/config-elements/identity-providers.rst

@@ -1,2 +1,86 @@
 ``<identityProviders>`` Element
-===============================
+===============================
+This is an **optional** child element of the :doc:`sustainsys.saml2 <sustainsys-saml2>` element.
+
+It indicates a list of identity providers known to the service provider.
+
+Each identity provider is added as an ``<add>`` element to the ``<identityProviders>`` element and 
+the element will end up looking something like what is shown below.  Note the possible child element 
+of the ``<signingCertifcate>`` which is shown in the second added identity provider element below.
+
+.. code-block:: xml
+
+    <identityProviders>
+        <add entityId="" signOnUrl="" logoutUrl="" allowUnsolicitedAuthnResponse="" binding="" 
+            wantAuthnRequestsSigned="" loadMetadata="" metadataLocation="" disableOutboundLogoutRequests="" outboundSigningAlgorithm=""/>
+        <add entityId="" signOnUrl="" logoutUrl="" allowUnsolicitedAuthnResponse="" binding="" 
+            wantAuthnRequestsSigned="" loadMetadata="" metadataLocation="" disableOutboundLogoutRequests="" outboundSigningAlgorithm="">
+            <signingCertificate storeName="" storeLocation="" findValue="" x509FindType="" />
+        </add>
+        ...
+    </identityProviders>
+
+Attributes
+----------
+``entityId``
+    The issuer name that the idp will be using when sending responses. When ``<loadMetadata>`` is enabled, the entityId 
+    is treated as a URL to for downloading the metadata.
+
+``signOnUrl`` (Optional)
+    The url where the identity provider listens for incoming sign on requests. The url has to be written in a 
+    way that the client understands, since it is the client web browser that will be redirected to the url. Specifically, 
+    this means that using a host name only url or a host name that only resolves on the network of the server won't work.
+
+``logoutUrl`` (Optional)
+    The url where the identity provider listens for incoming logout requests and responses. To enable single logout 
+    behaviour there must also be a service certificate configured in Saml2 as all logout messages must be signed.
+
+``allowUnsolicitedAuthnResponse``
+    Allow unsolicited responses. That is, Idp initiated sign on where there was no prior AuthnRequest. If true 
+    ``InResponseTo`` is not required and the IDP can initiate the authentication process. If false ``InResponseTo`` is 
+    required and the authentication process must be initiated by an AuthnRequest from this SP. Note that if the 
+    authentication was SP-intiatied, ``RelayState`` and ``InResponseTo`` must be present and valid.
+
+``binding`` (Optional)
+    The binding that the services provider should use when sending requests to the identity provider. One of the supported 
+    values of the ``Saml2BindingType`` enum.
+
+    * ``HttpRedirect``
+    * ``HttpPost``
+    * ``Artifact``
+
+``wantAuthnRequestsSigned`` (Optional)
+    Specifies whether the Identity provider wants the AuthnRequests signed. Defaults to ``false``.
+
+``loadMetadata`` (Optional)
+    Load metadata from the idp and use that information instead of the configuration. It is possible to use a 
+    specific certificate even though the metadata is loaded, in that case the configured certificate will take 
+    precedence over any contents in the metadata.
+
+``metadataLocation`` (Optional)
+    The SAML2 metadata standard strongly suggests that the ``Entity Id`` of a SAML2 entity is a URL where the 
+    metadata of the entity can be found. When loading metadata for an idp, Saml2 normally interprets the 
+    EntityId as a url to the metadata. If the metadata is located somewhere else it can be specified with this 
+    configuration parameter. The location can be a URL, an absolute path to a local file or an app relative 
+    path (e.g. ``~/App_Data/IdpMetadata.xml``)
+
+``disableOutboundLogoutRequests`` (Optional)
+    Disable outbound logout requests to this idp, even though Saml2 is configured for single logout and the idp 
+    supports it. This setting might be usable when adding SLO to an existing setup, to ensure that everyone is 
+    ready for SLO before activating.
+
+``outboundSigningAlgorithm`` (Optional)
+    By default Saml2 uses SHA256 signatures if running on .NET 4.6.2 or later and otherwise SHA1 signatures. Set this 
+    to set the signing algorithm for any outbound messages for this identity provider. Possible values:
+
+    * ``SHA1``
+    * ``SHA256``
+    * ``SHA384``
+    * ``SHA512``
+
+Elements
+--------
+The following are the possible children elements of the ``<identityProviders>`` element.  Each are provided as a 
+link below with full explanations of each. 
+
+* :doc:`signingCertificate <signing-certificate>`

docs/config-elements/metadata.rst

@@ -1,2 +1,44 @@
 ``<metadata>`` Element
-======================
+======================
+This is an **optional** child element of the :doc:`sustainsys.saml2 <sustainsys-saml2>` element.
+
+The metadata part of the configuration can be used to tweak the generated metadata. These configuration options 
+only affect how the metadata is generated, no other behavior of the code is changed.
+
+Attributes
+----------
+``cacheDuration`` (Optional)
+    Describes for how long in anyone should cache the metadata presented by the service provider before trying 
+    to fetch a new copy. Defaults to one hour. 
+
+    Examples of valid format strings:
+
+    * 1 day, 2 hours: ``1.2:00:00``
+    * 42 seconds: ``0:00:42``
+
+``validDuration`` (Optional)
+    Sets the maximum time that anyone may cache the generated metadata. If ``cacheDuration`` is specified, the 
+    remote party should try to reload metadata after that time. If that refresh fails, ``validDuration`` determines 
+    for how long the old metadata may be used before it must be discarded.
+
+    In the metadata, the time is exposed as an absolute ``validUntil`` date and time. That absolute time is 
+    calculated on metadata generation by adding the configured ``validDuration`` to the current time. 
+
+    Examples of valid format strings:
+
+    * 1 day, 2 hours: ``1.2:00:00``
+    * 42 seconds: ``0:00:42``
+
+``wantAssertionSigned`` (Optional)
+    Signal to IDPs that we want the Assertions themselves signed and not only the SAML response. Saml2 supports 
+    both, so for normal usage this shouldn't matter. If set to ``false`` the entire ``wantAssertionsSigned`` attribute 
+    is dropped from the metadata as the default values is ``false``.
+
+Elements
+--------
+The following are the possible children elements of the ``<metadata>`` element.  Each are provided as a 
+link below with full explanations of each. 
+
+* :doc:`organization <organization>`
+* :doc:`contactPerson <contact-person>`
+* :doc:`requestedAttributes <requested-attributes>`

docs/config-elements/name-id-policy.rst

@@ -1,2 +1,29 @@
 ``<nameIdPolicy>`` Element
-==========================
+==========================
+This is an **optional** child element of the :doc:`sustainsys.saml2 <sustainsys-saml2>` element.
+
+This element controls the generation of ``NameIDPolicy`` element in AuthnRequests. The element 
+is only created if either ``allowCreate`` or ``format`` are set to a non-default value.
+
+Attributes
+----------
+``allowCreate`` (Optional)
+    Default value is empty, which means that the attribute is not included in generated AuthnRequests.
+    Supported values are ``true`` or ``false``.
+
+``format`` (Optional)
+    Sets the requested format of ``NameIDPolicy`` for generated authnRequests.
+
+    Supported values (see section 8.3 in the `SAML2 Core specification <http://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf>`_ for explanations of the values).
+
+    * ``Unspecified``
+    * ``EmailAddress``
+    * ``X509SubjectName``
+    * ``WindowsDomainQualifiedName``
+    * ``KerberosPrincipalName``
+    * ``EntityIdentifier``
+    * ``Persistent``
+    * ``Transient``
+
+    If no value is specified, no format is specified in the generated AuthnRequests. If ``Transient`` is specified, it 
+    is not permitted to specify ``allowCreate`` (see 3.4.1.1 in the `SAML2 Core spec <http://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf>`_).

docs/config-elements/organization.rst

@@ -1,2 +1,21 @@
 ``<organization>`` Element
-==========================
+==========================
+Optional child element of the :doc:`metadata`  element.
+
+Provides information about the organization supplying the SAML2 entity (in plain English that means the organization 
+that supplies the application that Saml2 is used in).
+
+Attributes
+----------
+``name``
+    The name of the organization.
+
+``displayName``
+    The display name of the organization.
+
+``url``
+    URL to the organization's web site.
+
+``language``
+    In the generated metadata, the ``name``, ``displayName`` and ``url`` attributes have a language specification. If none 
+    is specified, the ``xml:lang`` attribute will be generated with an empty value.

docs/config-elements/requested-attributes.rst

@@ -1,2 +1,38 @@
 ``<requestedAttributes>`` Element
-=================================
+=================================
+Optional child element of the :doc:`metadata`  element.
+
+List of attributes that the SP requests to be included in the assertions generated by an identity provider.
+Each attribute is added to the list with an ``<add>`` element.
+
+The element should look something like this:
+
+.. code-block:: xml
+
+    <requestedAttributes>
+        <add name="" friendlyName="" nameFormat="" isRequired=""/>
+        <add name="" friendlyName="" nameFormat="" isRequired=""/>
+        ...
+    </requestedAttributes>
+
+Attributes
+----------
+``name``
+    The name of the attribute. This is usually in the form of an urn/oid, e.g. ``urn:oid:1.2.3``. The format of the 
+    name should be specified in the ``nameFormat`` attribute.
+
+``friendlyName`` (Optional)
+    An optional friendly (i.e. human readable) friendly name of the attribute that will be included in the 
+    metadata. Please note that the SAML2 standard specifically forbids the friendlyName to be used for anything 
+    other than information to a human. All matching of attributes must use the ``name``.
+
+``nameFormat`` (Optional)
+    Format of the name attribute. Valid values are:
+
+    * ``urn:oasis:names:tc:SAML:2.0:attrname-format:uri``
+    * ``urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified``
+    * ``urn:oasis:names:tc:SAML:2.0:attrname-format:basic``
+
+``isRequired`` (Optional)
+    ``true`` or ``false`` value indicating whether the attribute is required by the service provider or just a 
+    request that it would be nice if the Idp includes it.

docs/config-elements/requested-authn-context.rst

@@ -1,2 +1,47 @@
 ``<requestedAuthnContext>`` Element
-===================================
+===================================
+This is an **optional** child element of the :doc:`sustainsys.saml2 <sustainsys-saml2>` element.
+
+Attributes
+----------
+``classRef`` (Optional)
+    Class reference for authentication context. Either specify a full URI to identify an authentication context 
+    class, or a single word if using one of the predefined classes in the SAML2 Authentication context specification:
+
+    * ``InternetProtocol``
+    * ``InternetProtocolPassword``
+    * ``Kerberos``
+    * ``MobileOneFactorUnregistered``
+    * ``MobileTwoFactorUnregistered``
+    * ``MobileOneFactorContract``
+    * ``MobileTwoFactorContract``
+    * ``Password``
+    * ``PasswordProtectedTransport``
+    * ``PreviousSession``
+    * ``X509``
+    * ``PGP``
+    * ``SPKI``
+    * ``XMLDSig``
+    * ``Smartcard``
+    * ``SmartcardPKI``
+    * ``SoftwarePKI``
+    * ``Telephony``
+    * ``NomadTelephony``
+    * ``PersonalTelephony``
+    * ``AuthenticatedTelephony``
+    * ``SecureRemotePassword``
+    * ``TLSClient``
+    * ``TimeSyncToken``
+    * ``unspecified``
+
+``comparison`` (Optional)
+    Comparison method for authentication context as signalled in AuthnRequests.
+    Valid values are:
+
+    * ``Exact`` (default)
+    * ``Minimum``
+    * ``Maximum``
+    * ``Better``
+
+    ``Minimum`` is an inclusive comparison, meaning the specified ``classRef`` or anything better is 
+    accepted. ``Better`` is exclusive, meaning that the specified ``classRef`` is not accepted.