Developer Pages

# Getting Started

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

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 Connectis Adapter
    • Connectis.SPClientMvcDemo\log.txt - log file created when running the demo app

  • api_doc\index.html - the Connectis Adapter API documentation in HTML format

  • bin\ - the Connectis Adapter distribution binaries as both Debug (unoptimised) and Release (optimised) builds

    • NVelocity.dll - utility library that the Connectis 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 (opens new window).

The MemoryCache (opens new window) 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 (opens new window)) 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 (opens new window). 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 (opens new window) to clients, to allow for longer query strings (opens new window) and URLs (opens new window) (especially useful when using the HTTP-Redirect binding) and to filter requests (opens new window) 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.

Last updated: 3/1/24, 10:39:52 AM UTC

← Using the .NET Adapter with your application →