.NET Adapter

Introduction

The .NET Adapter allows customers to easily integrate their existing applications with the Signicat eHerkenning Broker.
The adapter provides the following functionality:
  1. 1.
    Send a SAML 2.0 Authentication Request to the Signicat eHerkenning Broker.
  2. 2.
    Process a SAML 2.0 response from the Signicat eHerkenning Broker and extract the information from this response:
    1. 1.
      The status (e.g. success, cancelled, error or session expired)
    2. 2.
      If the status is successful:
      1. 1.
        A unique, persistent identifier, called NameId, that allows you to identify returning users;
      2. 2.
        The value of “relay state”;
      3. 3.
        The level of assurance of the request;
      4. 4.
        A list of attributes provided by the Identity Provider.
  3. 3.
    Send a SAML 2.0 Logout Request to the Signicat eHerkenning Broker.
  4. 4.
    Generate and sign SAML 2.0 compliant metadata.
The .NET Adapter is an alternative to building a SAML implementation yourself. Building your own implementation is not recommended due to the potential of introducing unintended security vulnerabilities. The advantages of using our adapter instead of your own implementation are:
  1. 1.
    Guaranteed compatibility with the Signicat eHerkenning Broker;
  2. 2.
    Support offered to your developers through software updates and upgrades;
  3. 3.
    Support for future features of SAML through a simple upgrade of the adapter library.
Finally, using the .NET Adapter does not require any knowledge of the SAML protocol.
The adapter should enable you to quickly start your implementation whilst providing you with a secure connection to various networks such as eHerkenning, eIDAS or others as well as guaranteed long term support. Please consult your Signicat partner or sales representative for more information.
The archive you have received contains everything you need to start a secure connection with the Signicat Identity Broker.

Minimum system requirements for using the .NET Adapter

  • Windows Server 2008 SP2 or Windows 7 SP1
  • IIS 7.5
  • .NET Framework 4.5.2
Please note that .NET Framework versions 4.5.1, 4.5 and earlier are no longer supported by Microsoft, so we recommend upgrading to at least 4.5.2 which is, at the time of this writing, the oldest Framework API version that is still supported.
  • Windows Server version 1709 or Windows Server 2016
  • IIS 10
  • .NET Framework 4.7.2

Minimum system requirements for running the Demo Application

  • Windows 7 SP1
  • IIS 7.0
  • .NET Framework 4.5.2
  • Visual Studio Express 2012 for Web (Update 4) (depending on the licensing terms) or Visual Studio 2012 (Update 5) with the Web Developer Tools
  • Windows 10 Pro October 2018 Update
  • IIS Express 10 (installed by Visual Studio)
  • .NET Framework 4.7.2
  • Visual Studio Professional 2017 (Version 15.9.9) with the following installed workloads:
    • ASP.NET and Web Development
  • TypeScript SDK version 3.2.2 or later available at https://www.microsoft.com/download/details.aspx?id=55258
We do not recommend using versions 15.6.0 up to 15.6.4 of Visual Studio 2017 due to this issue affecting web application projects. Visual Studio 15.6.5 and later should work.
We do not recommend using versions 15.8.0 up to 15.8.5 due to an IntelliSense issue very similar to this issue. Visual studio 15.8.6 and later should work.

What is contained in the distribution?

In the archive you will find five top-level directories and four files:
  • adapter\ - the Demo Application source code
    • Connectis.SPClientMvcDemo.sln the Demo Adapter Visual Studio solution file
    • Connectis.SPClientMvcDemo\configuration\ - configuration files:
      • core
        • LevelOfAssurance.xml - the defined levels of assurance file
      • idps - directory containing configuration files of supported brokers
        • <entityID>.xml - broker metadata files, named as their corresponding entity IDs
      • sps - directory containing configuration files for supported service providers
        • Services.xml - your Service Provider’s services configuration file
        • <entityID>.xml - your Service Provider configuration file, named as the corresponding entity ID
    • Connectis.SPClientMvcDemo\Web.config - Demo Application configuration file, including application settings for the Signicat Adapter (see table below)
    • Connectis.SPClientMvcDemo\log.txt - log file created when running the demo app
  • api_doc\index.html - the Signicat Adapter API documentation in HTML format
  • bin\ - the Signicat Adapter distribution binaries as both Debug (unoptimised) and Release (optimised) builds
    • NVelocity.dll - utility library that the Signicat Adapter is using
    • BouncyCastle.Crypto.dll - cryptography library that the Connectis.Pep.dll is using
    • Connectis.SPClientCore.dll - protocol independent components of the Adapter
    • Connectis.SPClientSaml.dll - SAML2 components of the Adapter
    • Connectis.SPClientOwin.dll - authentication middleware for OWIN
    • Microsoft.Owin.dll, Microsoft.Owin.Security.dll and Owin.dll - utility libraries that the Connectis OWIN adapter is using
    • Connectis.SPClientLog4NetUtil.dll - logging utility allowing your application to capture the Connectis Adapter logs to your log4net logging infrastructure; additional utilities for other logging platforms can be easily implemented
    • Log4net.dll - logging library that the Demo application is using
    • Connectis.SPClientMvcUtil.dll - Web application utilities for ASP.NET MVC applications
    • Connectis.SPClientWebFormsUtil.dll - Web application utilities for Web Forms applications
  • certificate\ - files needed for the Demo Application certificate management
    • SPClient.p12 - certificate used by the Demo Application, including its private key
  • resources\ - NVelocity template files used by the Connectis Adapter components, these are copied to the adapter\Connectis.SPClientMvcDemo\resources directory as a post-build step
  • system-configuration\ - various files that can help you configure a system for running the Demo Application or a production application that uses the Connectis Adapter
  • License.txt - a text file containing the licensing terms for using the Connectis Adapter
  • Version.txt - a text file containing the API version and the binaries build version. The two are usually identical but it is possible for the binaries version to be incremented separately from the API version due to service releases and other enhancements with no API impact.
Please note that the relative location of various files in the distribution matters for proper functioning of the Demo Application. Please only move files to other relative locations if you understand how to re-configure the Demo Application.

The Web.config configuration options / app settings:

Parameter name
Parameter description
Example
connectis.key.store.name
Certificates Store name used for signing and encryption keys. For client authentication used by Artifact Binding (see the sslKeyName attribute), the “My certificate store of the current user” is always used, regardless of this setting.
My
connectis.key.store.location
Certificates Store location used for signing and encryption keys. For client authentication used by Artifact Binding (see the sslKeyName attribute), the “My certificate store of the current user” is always used, regardless of this setting.
CurrentUser
connectis.loa.config.location
path to a configuration file describing the levels of assurance; the path can be absolute or relative to the current directory of the running web application that is using the Connectis Adapter
configuration\core\LevelOfAssurance.xml
connectis.services.config.location
absolute or relative path to the services configuration file
configuration\sps\Services.xml
connectis.sp.config.location
comma separated list of paths to service provider configuration files; they can be absolute or relative
configuration\sps\urn_etoegang_DV_00000003244440010000_entities_7788.xml
connectis.broker.config.location
comma separated list of paths to broker metadata files; they can be absolute or relative
configuration\idps\urn_etoegang_HM_00000003244440010000_entities_9530.xml
connectis.certificate.expiration.check
Enable checking that the identity provider certificate is still in its validity time frame, i.e. it has not expired. This check is off by default.
True
connectis.idp.servicePoint.connectionLimit.override
the ConnectionLimit property that is used for Artifact binding. This value only takes effect if the corresponding ServicePoint has the connection limit set to its default. This is so that you can configure per-URL values yourself.
32
connectis.idp.servicePoint.disable.securityProtocol.configuration
The adapter will, by default, configure SecurityProtocol to disallow any protocol lower than TLS 1.2 and to require that EncryptionPolicy is set to RequireEncryption. This is so that Artifact binding is done over a secure channel. If needed, set this configuration option to “false” to disable this behavior.
False
connectis.disable.https.only.cookies
optional, disables setting the Secure flag for the cookies that the adapter manages directly (currently only used in the OWIN adapter); please do not set this to “True” unless absolutely necessary, as it will increase security risks
False
certificate.header.name
Header name for client certificate for artifact binding
X-SSL-Client-Cert
file.resource.loader.path
absolute or relative path to the NVelocity template files used for the SAML protocol implementation; other future resource files also be read from this location;
In the Demo Application this folder is created and populated from “..\..\resources” as a post-build event
resources
file.resource.loader.modificationCheckInterval
the resource files in “file.resource.loader.path” will be re-read from disk periodically, every X number of seconds; X is specified by this setting; this setting only affects NVelocity templates at present but might affect other resource files too in the future
300
runtime.log.logsystem.class
NVelocity logging setting; at present logging is broken in NVelocity so this setting has no significant effects; please keep the default value provided or don’t specify this setting at all
NVelocity.Runtime.Log.SimpleLog4NetLogSystem\,NVelocity
log4net.Config
See log4net documentation
og4.config
log4net.Config.Watch
See log4net documentation
True
log4net.Internal.Debug
See log4net documentation
false

In addition to the <appSettings> detailed above, the Web.config file also contains the following configuration settings:

<system.runtime.caching>
<memoryCache>
<namedCaches>
<add name="ConnectisIdCache"
cacheMemoryLimitMegabytes="256"
physicalMemoryLimitPercentage="0"
pollingInterval="00:02:00" />
<add name="ConnectisArtifactStore"
cacheMemoryLimitMegabytes="64"
physicalMemoryLimitPercentage="0"
pollingInterval="00:01:00" />
</namedCaches>
</memoryCache>
</system.runtime.caching>
This set of configuration settings is documented here.
The MemoryCache instance that corresponds to “ConnectisIdCache” is used by the adapter internally to detect and prevent SAML messages replay attacks. Since the IDs of the messages need to be stored for this validation to work (see the “1.3.4 ID and ID Reference Values” in the SAML specifications) and since the adapter will reject IDs that are encoded using more than 255 characters and since it will store the IDs for limited time (currently 10 minutes but this is subject to change), the default cache size from the demo application should be sufficient for most applications.
Please note that, even if the internal adapter validation cache size is insufficient to prevent certain replay attacks, such attacks will likely fail due to the other checks and security measures taken by the adapter. Also note that not setting this configuration option in your application is not an error.
The instance that corresponds to “ConnectisArtifactStore” is used by the adapter internally only when sending requests to an IdP via Artifact binding. The request will be stored until it is retrieved by the IdP or until it expires. Expect the size of one cached request to be around 2 kibibytes maximum. The expiration time of each item is currently set internally to two minutes, but this is subject to change. The default cache size used in the demo application should be sufficient for most applications.
In the case when an entry is evicted early, the corresponding flow (login or logout) will fail and the user will have to retry the operation. Please note that this might actually happen under very low memory conditions, since MemoryCache does not offer strong guarantees regarding eviction under such conditions. Not setting this configuration option in your application is not an error.
Important Note: Please note that the adapter functionality using the cache detailed previously will not work on load-balancing / web farms setups “out of the box”. The cache used for detecting ID replay attacks and for storing artifacts is not shared across web application server instances. This means that, depending on how routing works, Artifact binding requests are likely to fail (if served from a different machine than the one that actually stores the request).
This also means that ID replay attack detection will be severely limited and will not catch all replay attempts. This will not render your application immediately vulnerable, due to the other mitigation factors, but will lower the successful attack threshold. If you are setting up your application in a web farm / load balancing context and you need to support Artifact binding for sending requests or have concerns around replay attacks risk, please contact Connectis technical support with details about the setup that you are trying to achieve. We will be able to assist you in finding an appropriate solution.
In addition to the settings described above, you may want to include these settings or to provide a similar mechanism to prevent the configuration files to be served to clients, to allow for longer query strings and URLs (especially useful when using the HTTP-Redirect binding) and to filter requests based on those maximum values. Please note that the settings in this example are only provided as starting points that you can use to determine what is best for your own application:
<system.web>
<httpRuntime targetFramework="4.5" maxUrlLength="1024" maxQueryStringLength="8192" />
</system.web>
<system.webServer>
<security>
<requestFiltering>
<requestLimits maxUrl="1024" maxQueryString="8192"/>
<hiddenSegments>
<add segment="configuration"/>
<add segment="resources"/>
</hiddenSegments>
</requestFiltering>
</security>
</system.webServer>

Demo Application example

The demo application is preconfigured to run with our Eh Broker and use the demo certificate. This is only an example because self signed ceritifcates are not allowed and a proper PKIO certificate needs to be used. If you want to install the SP certificate provided (this option is not recommended on a production machine), you can simply add it through your certificate management tool (the password is "insecure"). Please make sure the private key is exportable!!!
You might also need to provide your IIS User (or Application Pool User, e.g. "IIS AppPool\DefaultAppPool") access to the certificate private key. The process is the same for your actual PKIO certificate.

Metadata endpoint

Open the page metadata page the expected result is a page containing a list of links to pages rendering XML documents with the metadata of all your available connections to Identity Brokers. Clicking on one of the links should result in the metadata XML being displayed in the browser. Any errors usually indicate that the signing certificate was not properly set up or that the Service Provider configuration is invalid.
Please note that when using the adapter in your own application (instead of the Demo application) you might have to write a metadata endpoint that calls the corresponding Connectis Adapter API.