tweaking the organization of the config doc(s)

docs/config-elements/compatibility.rst

@@ -0,0 +1,2 @@
+``<compatibility>`` Element
+===========================

docs/config-elements/contact-person.rst

@@ -0,0 +1,2 @@
+``<contactPerson>`` Element
+===========================

docs/config-elements/federations.rst

@@ -0,0 +1,2 @@
+``<federations>`` Element
+=========================

docs/config-elements/identity-providers.rst

@@ -0,0 +1,2 @@
+``<identityProviders>`` Element
+===============================

docs/config-elements/metadata.rst

@@ -0,0 +1,2 @@
+``<metadata>`` Element
+======================

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

@@ -0,0 +1,2 @@
+``<nameIdPolicy>`` Element
+==========================

docs/config-elements/organization.rst

@@ -0,0 +1,2 @@
+``<organization>`` Element
+==========================

docs/config-elements/requested-attributes.rst

@@ -0,0 +1,2 @@
+``<requestedAttributes>`` Element
+=================================

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

@@ -0,0 +1,2 @@
+``<requestedAuthnContext>`` Element
+===================================

docs/config-elements/service-certificates.rst

@@ -0,0 +1,2 @@
+``<serviceCertificates>`` Element
+=================================

docs/config-elements/signing-certificate.rst

@@ -0,0 +1,2 @@
+``<signingCertificate>`` Element
+================================

docs/config-elements/sustainsys-saml2.rst

@@ -0,0 +1,90 @@
+``<sustainsys.saml2>`` Element
+==============================
+The ``<sustainsys.saml2>`` element is a child node of the ``<configuration>`` element.  Its
+attributes are listed and described below, and its child elements are listed as well and 
+are linked to full explanations of each.
+
+Attributes
+----------
+``returnUrl``
+    The Url that you want users to be redirected to once the authentication is complete. This is typically the start 
+    page of the application, or a special signed in start page.
+
+``entityId``
+    The name that this service provider will use for itself when sending messages. The name will end up in the ``Issuer`` 
+    field in outcoing authnRequests.
+
+    The SAML standard requires the entityId to be an absolute URI. Typically it should be the URL where the metadata 
+    is presented. E.g. http://sp.example.com/Saml2/.
+
+``discoveryService`` (Optional)
+    Specifies an idp discovery service to use if no idp is specified when calling sign in. Without 
+    this attribute, the first idp known will be used if none is specified.
+
+``modulePath`` (Optional)
+     Indicates the base path of the Saml2 endpoints. Defaults to /Saml2 if not specified. This can usually be left as the 
+     default, but if several instances of Saml2 are loaded into the same process they must each get a separate base path.
+
+``authenticateRequestSigningBehavior`` (Optional)
+    Sets the signing behavior for generated AuthnRequests. Three values are supported:
+
+    * ``Never``: Saml2 will never sign any created AuthnRequests.
+    * ``Always``: Saml2 will always sign all AuthnRequests.
+    * ``IfIdpWantAuthnRequestsSigned`` (default if the attribute is missing): Saml2 will sign AuthnRequests if the idp is configured for it (through config or listed in idp metadata).
+
+``validateCertificates`` (Optional)
+    Normally certificates for the IDPs signing use is communicated through metadata and in case of a breach, the 
+    metadata is updated with new data. If you want extra security, you can enable certificate validation (the 
+    default value for this attribute is ``false``). Please note that the SAML metadata specification explicitly 
+    places no requirements on certificate validation, so don't be surprised if an Idp certificate doesn't pass validation.
+
+``publicOrigin`` (Optional)
+    Indicates the base url of the Saml2 endpoints. It should be the root path of the application. E.g. The SignIn url is 
+    built up as ``PublicOrigin + / + modulePath + /SignIn``. Defaults to Url of the current http request if not 
+    specified. This can usually be left as the default, but if your internal address of the application is 
+    different than the external address the generated URLs (such as ``AssertionConsumerServiceURL`` in the 
+    ``saml2p:AuthnRequest``) then this will be incorrect. The use case for this is typically with load balancers 
+    or reverse proxies. It can also be used if the application can be accessed by several external URLs to make sure 
+    that the registered in metadata is used in communication with the Idp.
+
+    If you need to set this value on a per-request basis, provide a ``GetPublicOrigin`` Notification function instead.
+
+``outboundSignAlgorithm`` (Optional)
+    By default Saml2 uses SHA256 signatures if running on .NET 4.6.2 or later or when you 
+    have called ``GlobalEnableSha256XmlSignatures()``. Otherwise, it uses SHA1 signatures. Use this attribute to 
+    set the default signing algorithm for any messages (including metadata) that Saml2 generates. Possible values:
+
+    * ``SHA1`` (or http://www.w3.org/2000/09/xmldsig#rsa-sha1)
+    * ``SHA256``
+    * ``SHA384``
+    * ``SHA512``
+
+    The full url identifying the algorithm can also be provided. The algorithm can be overridden for each IdentityProvider 
+    too.
+
+``minIncomingSigningAlgorithm`` (Optional)
+    The minimum strength required on signatures on incoming messages. Messages with a too weak signing algorithm will be 
+    rejected.  By default Saml2 requires SHA256 signatures if running on .NET 4.6.2 or later or when you have 
+    called ``GlobalEnableSha256XmlSignatures()``. Otherwise, it uses SHA1 signatures.
+
+    Possible values:
+
+    * ``SHA1`` (or http://www.w3.org/2000/09/xmldsig#rsa-sha1)
+    * ``SHA256``
+    * ``SHA384``
+    * ``SHA512``
+
+    The full url identifying the algorithm can also be provided.
+
+Elements
+--------
+The following are the possible children elements of the ``<sustainsys.saml2>`` element.  Each are provided as a 
+link below with full explanations of each. 
+
+* :doc:`nameIdPolicy <name-id-policy>`
+* :doc:`requestedAuthnContext <requested-authn-context>`
+* :doc:`metadata <metadata>`
+* :doc:`identityProviders <identity-providers>`
+* :doc:`federations <federations>`
+* :doc:`serviceCertificates <service-certificates>`
+* :doc:`compatibility <compatibility>`

docs/configuration.rst

@@ -12,7 +12,8 @@ constructor) the information here applies.
 
 Config Sections
 ---------------
-Three new config sections are required. Add these under ``configuration/configSections``:
+Three new config sections are required. Add these under ``configuration/configSections``.  Each of the sections
+will be a child element of the main ``configuration`` section and each is described below.
 
 .. code-block:: xml
 
@@ -43,12 +44,15 @@ does not need any http modules, please see the separate info on the :doc:`owin-m
     </system.webServer>
 
 
-sustainsys.saml2 Section
+Sustainsys.Saml2 Section
 ------------------------
 The ``sustainsys.saml2`` section contains the configuration of the Sustainsys.Saml2
 library. It is required for the http module and the mvc controller. The Owin middleware can
 read web.config, but can also be configured from code (see [Owin middleware](OwinMiddleware.md)).
 
+A sample section is shown below.  For full details and all avaialble options, see  
+:doc:`sustainsys.saml2 <config-elements/sustainsys-saml2>`.
+
 .. code-block:: xml
 
     <sustainsys.saml2 entityId="http://localhost:17009"
@@ -88,14 +92,34 @@ read web.config, but can also be configured from code (see [Owin middleware](Owi
         </federations>
     </sustainsys.saml2>
 
+System.IdentityModel Section
+----------------------------
+There must be a ``<system.identityModel>`` section in the config file or there will be a runtime error. The section can be 
+empty (use ``<system.identityModel />``).
+
+The reason you might want this to be non-empty is to provide a custom ``ClaimsAuthenticationManager`` as shown in the 
+sample below (you would obviously provide your own type in place of the Stub shown in the sample).
+
+.. code-block:: xml
 
-``<sustainsys.saml2>`` Element
-++++++++++++++++++++++++++++++
-*Child element of `<configuration>` element.*
+    <system.identityModel>
+        <identityConfiguration>
+            <claimsAuthenticationManager type="Sustainsys.Saml2.Tests.ClaimsAuthenticationManagerStub, Sustainsys.Saml2.Tests"/>
+        </identityConfiguration>
+    </system.identityModel>
 
-Root element of the config section.
+System.IdentityModel.Services Section
+-------------------------------------
+The ``<system.identityModel.services>`` element configures the built in servies. For testing on non ssl sites, the 
+requirement for ssl for the session authentication cookie must be disabled.
+
+.. danger::  
+    It is a severe security risk to leave the requireSsl setting as false in a production environment.
+
+.. code-block:: xml
 
-Attributes
-__________
-* [``returnUrl``]
-* [``entityId``]
+    <system.identityModel.services>
+        <federationConfiguration>
+            <cookieHandler requireSsl ="false"/>
+        </federationConfiguration>
+    </system.identityModel.services>

docs/contributing.rst

@@ -0,0 +1,57 @@
+Contributing
+============
+Sustainsys.Saml2 is maintained by and have mostly been developed by Sustainsys in Stockholm, Sweden. The library's 
+source code is hosted on `github <https://github.com/Sustainsys/Saml2>`_.   When doing work on protocol features, it is recommended to consult 
+`the official SAML specifications <https://wiki.oasis-open.org/security/FrontPage#SAMLV2.0Standard>`_.
+
+Issue tracking
+--------------
+Github issues are used to keep track of issues and releases. For requests of functionality or to 
+report bugs, please open an issue in the github repo. It is advised to open an issue describing the plans 
+before starting any major coding work. Discussing before writing code significantly reduces the risk of 
+getting a pull request denied.
+
+Versioning 
+----------
+Sustainsys uses semantic versioning as defined on http://semver.org/.
+Given a version number MAJOR.MINOR.PATCH, increment the:
+
+* MAJOR version when you make incompatible API changes,
+* MINOR version when you add functionality in a backwards-compatible manner, and
+* PATCH version when you make backwards-compatible bug fixes.
+
+Coding Conventions
+------------------
+The coding conventions follow the classic .NET style of coding, with the following styles:
+
+* Always use ``{}`` for if statements, even when there is only one line.
+* Code analysis is enabled and all code should compile without compiler warnings or code analysis errors. Code analysis warnings that are not relevant are supressed in the source. Rules should only be disabled on a global level if it really is appropriate to disable the rule for the entire code base. Unknown words are added to CustomDictionary.xml instead of suppressing individual warnings.
+* Private members in classes are named with camelCasing, no underscores or similar.
+* Member variables are not prefixed with ``this``. unless required to resolve ambiguity (such as in a constructor having parameters with the same name as the members).
+* Any single method is short enough to fit on one screen (on a typical laptop monitor, not a 30-inch development monster-monitor in vertical orientation).
+* The code is formatted to (mostly) fit in 80 columns.
+
+Unit Tests
+----------
+The Sustainsys.Saml2 library has been developed using TDD (Test Driven Development). All functionality is covered 
+by tests, and it will remain that way. Pull requests will only be merged if they contain tests covering the 
+added functionality. Parts of the code that aren't practically possible to test because of tight integration with 
+the web server (see e.g. ``CommandResult.ApplyPrincipal``) are excluded from this rule and should be 
+marked with an ``[ExcludeFromCodeCoverage]`` attribute. The code coverage report is at 100.00% coverage 
+and should remain so.
+
+Continuous Integration / Build Server
+-------------------------------------
+All pull requests are built on AppVeyor and code coverage is checked.
+
+Branching
+---------
+To make a clean pull request, it is important to follow some git best practices. Nancy has an 
+`excellent guide <https://github.com/NancyFx/Nancy/wiki/Git-Workflow>`_ that outlines the steps required.
+
+Licensing
+---------
+The library is licensed under LGPL and by submitting code it is accepted that the submitted code will be 
+released under the same license. Third party code may only be added to the library if the author of the 
+pull request holds the copyright to the code, or the code is previously licensed under a 
+license compatible with LGPL.

docs/getting-started.rst

@@ -8,7 +8,8 @@ described below and are having any trouble, make sure to check out the :doc:`Tro
 
 A sample SAML identity provider is available to further assist you in getting started if you don't already 
 have a SAML identity provider that you can test with.  You can access it directly at https://stubidp.sustainsys.com, 
-or you can download the solution to run it locally yourself (it's a project within the `Sustainsys.Saml2 github repository <https://github.com/Sustainsys/Saml2>`_).
+or you can download the solution to run it locally yourself (it's a project within the 
+`Sustainsys.Saml2 github repository <https://github.com/Sustainsys/Saml2>`_).
 
 ASP.NET Web Forms
 -----------------
@@ -59,9 +60,9 @@ If you're using ``IdentityServer`` (v3 or later), you may want to
 configure SAML identity providers like Okta or Ping as external
 identity providers within your IdentityServer implementation.
 
-The ``Owin`` & ``ASP.NET Core2`` modules enables SAML identity 
-providers to be integrated within IdentityServer3 and 
-IdentityServer4 packages. 
+The ``Owin`` & ``ASP.NET Core2`` modules enable SAML identity 
+providers to be integrated within `IdentityServer3 <https://github.com/IdentityServer/IdentityServer3>`_ and 
+`IdentityServer4 <https://github.com/IdentityServer/IdentityServer4>`_ packages. 
 
 Nuget Package to use for IdentityServer3: `Sustainsys.Saml2.Owin <https://www.nuget.org/packages/Sustainsys.Saml2.Owin/>`_
 Nuget Package for IdentityServer4: `Sustainsys.Saml2.AspNetCore2 <https://www.nuget.org/packages/Sustainsys.Saml2.AspNetCore2/>`_
@@ -71,9 +72,12 @@ IdentityServer3 and Okta to add Okta as an
 identity provider to an IdentityServer3 project. There is 
 also a SampleIdentityServer3 project in the Saml2 repository.
 
+.. note:: 
 
+    There is also a Sustainsys.Saml2 Nuget package, but this only contains functionality shared 
+    across the packages above and is not meant to be referenced directly in other projects.
 
 .. note:: 
 
-    There is also a Sustainsys.Saml2 Nuget package, but this only contains functionality shared 
-    across the packages above and is not meant to be referenced directly in other projects.
+    The protocol handling classes are available as a public API as well, making it possible to reuse some of the 
+    internals for writing your own service provider or identity provider.

docs/index.rst

@@ -7,7 +7,7 @@ Welcome to Sustainsys.Saml2
 ===========================
 The Sustainsys.Saml2 library adds SAML2P support to ASP.NET web sites, allowing the web site 
 to act as a SAML2 Service Provider (SP). The library was previously named Kentor.AuthServices.
-Sustainsys.Saml2 is open sourced and contributions are welcome, please see contributing guidelines 
+Sustainsys.Saml2 is open sourced and contributions are welcome, please see :doc:`contributing guidelines <contributing>` 
 for info on coding standards etc.
 
 Using Sustainsys.Saml2
@@ -20,7 +20,9 @@ Using the Sustainsys.Saml2 library to add SAML2P support into your ASP.NET web a
 The exact nature of these steps depends on the ASP.NET integration you're after.  
 See :doc:`getting-started` for all the details.
 
-
+Licensing
+---------
+The library is licensed under the `GNU Lesser General Public License (LPGL) <https://www.gnu.org/licenses/lgpl-3.0.en.html>`_.
 
 .. toctree::
    :maxdepth: 2 
@@ -31,5 +33,27 @@ See :doc:`getting-started` for all the details.
    configuration
    owin-middleware
    troubleshooting
+   contributing
+
+.. toctree::
+   :maxdepth: 2 
+   :hidden:  
+   :caption: web.config elements
+
+   config-elements/sustainsys-saml2
+   config-elements/name-id-policy
+   config-elements/identity-providers
+   config-elements/signing-certificate
+   config-elements/metadata
+   config-elements/organization
+   config-elements/contact-person
+   config-elements/requested-attributes
+   config-elements/requested-authn-context
+   config-elements/federations
+   config-elements/service-certificates
+   config-elements/compatibility
+
+
+
 
 

docs/troubleshooting.rst

@@ -9,4 +9,3 @@ The items below may point you in the right direction.
 * Log your actual SAML2 conversation with `SAML Chrome Panel <https://chrome.google.com/webstore/detail/saml-chrome-panel/paijfdbeoenhembfhkhllainmocckace>`_ or `SAML Tracer for Firefox <https://addons.mozilla.org/en-US/firefox/addon/saml-tracer/>`_.
 * Connect an ``ILoggerAdapter`` to your ``SPOptions.Logger``. If you are using the ``OWIN`` middleware this is done for you automatically and you can see the output in the OWIN/Katana logging.
 * Last but not least, download the Saml2 source and check out what's really happening.
-