# Using the .NET Adapter with your application

Before using the .NET Adapter you have to configure it. The Adapter can be configured manually, by editing the configuration files.

# Configure the .NET Adapter manually

# Setup

To properly use the adapter in your application please follow these steps:

Make sure that you have a certificate (with a private key) installed and that it is readable by the user account that the application server runs under. The section on installing the provided SP certificate shows an example flow of importing a certificate. It is not recommended that you use the certificate included in this distribution on a production machine.
Copy all the binaries (.NET assembly DLLs) from the “bin” folder to your external library folder (you can exclude any “*Util” libraries that are not relevant to your platform, for example you can exclude “Connectis.SPClientMvcUtil.dll” if not using ASP.NET MVC). Add the required references to your application.
Copy the contents of the “resources” folder to a location of your choosing, The application server will need to have read access to that location.
Copy the configuration files in “adapter\Connectis.SPClientMvcDemo\configuration\” to your configuration folder. You will have to edit them so that they match your specific service details and the information of the broker that you are going to interact with. Please see the following sections for details. Optionally, you can also create them from scratch. We will refer to this location as “$CONFIGURATION_LOCATION” throughout the rest of the document (although it does not need to be configured as an actual environment variable).
Copy “log4.config” from “adapter\Connectis.SPClientMvcDemo\” to your configuration folder or take note of where your existing log4net configuration file is located. Edit the file (opens new window) to suit your needs. If you want to log to a file please make sure that it is writable from your web application.
Edit your application’s configuration file (Web.config) to include the following lines:

<appSettings>
  <add key="connectis.key.store.name" value="My" />
  <add key="connectis.key.store.location" value="CurrentUser" />
  <add key="connectis.loa.config.location" value="configuration\core\LevelOfAssurance.xml" />
  <add key="connectis.services.config.location" value="configuration\sps\Services.xml" />
  <add key="connectis.sp.config.location" value="configuration\sps\urn_etoegang_DV_00000003244440010000_entities_7788.xml" />
  <add key="connectis.broker.config.location" value="configuration\idps\https___eidas_staging_connectis_org_broker_saml.xml,configuration\idps\urn_etoegang_HM_00000003244440010000_entities_9530.xml" />
  <add key="connectis.certificate.expiration.check" value="True" />
  <add key="connectis.idp.servicePoint.connectionLimit.override" value="32" />
  <add key="connectis.idp.servicePoint.disable.securityProtocol.configuration" value=”False" />
  <add key="connectis.pseudonym.validation.point" value="BLHPFwnFpnoTvQm03lMQnLdOSpWOnTpsYfxHPmAg/Y3umIcW2PKuwW3Pk5+VDR1ba2z15114Ib8k62aVwieolneiO6bDOaQGKDzXi/4k1/MX"/>
  <add key="connectis.identity.validation.point" value="BAVhvzQkCzzIpoIX7uIfauLa6gPsMZp3Ka4DguHlDt5tGwbLeIsXorAwsSYm8QvNDntoKkqc+HF//OpATfa0028wefZnnMvRwgWqHS1/0t9G"/>
  <add key="file.resource.loader.path" value="resources" />
  <add key="file.resource.loader.modificationCheckInterval" value="300" />
  <add key="runtime.log.logsystem.class" value="NVelocity.Runtime.Log.SimpleLog4NetLogSystem\,NVelocity" />
  <add key="log4net.Config" value="log4.config" />
  <add key="log4net.Config.Watch" value="True" />
  <add key="log4net.Internal.Debug" value="False" />
</appSettings>

7. Edit the lines that you’ve just added to Web.config to match your own setup and preferences. You can find more details on what each setting means in the table provided in the Getting Started.

# Configure your Service Provider

This section will describe how to configure your Service Provider.

Your Service Provider is described by two xml files, both of them found under “$CONFIGURATION_LOCATION/Config/Sps/”:

$YOUR_SP_ENTITY_ID.xml
Services.xml

The $YOUR_SP_ENTITY_ID.xml file contains the following information (names are case sensitive):

entityId attribute - the entity id that you want your service to have (please note that some federations require specific formats)
contactEmail attribute - Contact email of your service
contactName attribute - The name of your service
contactPhone attribute - Phone number for your Service
organizationName attribute - The name of your organization
organizationDisplayName attribute - The name that you want to display for your organization
organizationUrl attribute - URL of your organization
assertionConsumerServiceUrl attribute - The endpoint to which you want the IdPs to return the login and logout response; when writing your own endpoint code, using the Connectis Adapter API, it is your responsibility for the endpoint URLs to match the metadata URLs
artifactResolutionServiceUrl attribute - The endpoint to which you want the IdPs to resolve artifact IDs from, when your application sends a login or logout request; if your SP supports artifact binding (in the SupportedBindings list) then this value must be configured.
singleLogoutServiceUrl attribute - The endpoint which you want the broker to send the SLO request and that can also receive the Logout response
signingKeyName attribute - the thumbprint of your certificate configured at the previous step, used for signing SAML protocol messages
encryptionKeyName attribute - the thumbprint of your certificate configured at the previous step, used for encrypting SAML protocol messages, it can be different from the signing certificate
sslKeyName attribute - the thumbprint of the certificate that is used for Artifact binding, when the adapter needs to be a HTTPS client of the IdP; this can be different from the signing and the encryption certificates; however, this is has to be the same certificate that will be used by your application server for serving HTTPS traffic on the Artifact Resolution Service endpoint; please see the "Artifact Binding Configuration Guidelines" section for details
notBeforeGracePeriodInSeconds attribute - number of seconds that the SP clock is allowed to be ahead of the IDP clock, used for response validation
SupportedBindings - a list of the supported communication protocols for your service
PreferredBinding - the default communication protocol that your service uses
DefaultServiceIndex - the default service index that your SP will use
ArtifactResolutionServiceIndex - the service index that your SP will use for its Artifact Resolution Service; if your SP supports artifact binding (in the SupportedBindings list) then this value must be configured

The Services.xml file contains the definition of all service indexes for all SPs that you have configured. It contains the following information (property names are case sensitive):

entityId attribute - the SP entity id
serviceIndex attribute - the service id for a given entityId
AcceptIdpInitiatedResponse - specifies if your service accepts IdP initiated response
Passive - specifies if your service accepts passive login
ForceAuthn - specifies if your service accepts force authentication
LevelOfAssurance level attribute- the level of assurance for your service
LevelOfAssuranceComparison - the level of assurance comparison level
DefaultBrokerEntityId - the entity id of the default IdP that your service communicates with.

You can test that the data you have entered is correct by visiting the SP metadata endpoint. See the corresponding section for details. In order to do that you will likely need to write the metadata endpoint code in your own application; you can use the Demo Application metadata endpoint code as an example.

# Exchange metadata with Signicat eHerkenning Broker

This section will provide information about the metadata exchange process.

The metadata exchange is a bidirectional agreement between an SP and an IdP that they communicate with each other.

To properly exchange the metadata:

Go to the metadata endpoint of the desired Service Provider (see she Quick Start section on metadata)
Save the response to an XML file
Send the XML file to Connectis Support asking that it is added to the list of supported SPs

By default the adapter already has a couple of IdPs configured that you can communicate with. If you wish to communicate with another one (for example you might want to switch to using the production IdP) you need to do the following:

Ask Signicat Support for the corresponding metadata file
Copy the metadata file to “$CONFIGURATION_LOCATION/configuration/idps/” and edit your “Web.config” by adding a new entry under “broker.config.location” (broker.config.location is a comma-separated values list of such paths).

For example, if under $CONFIGURATION_LOCATION/configuration/idps/ you have one file named “broker.xml”, then your “Web.config” should contain the following line:

<add key="broker.config.location" value="configuration/idps/broker.xml" />

The Signicat Support will provide you with a new metadata file, say “broker_prod.xml”. Copy the file under $CONFIGURATION_LOCATION/configuration/idps/ and change your “Web.config” entry to look like this:

<add key="broker.config.location" value="configuration/idps/broker.xml,configuration/idps/broker_prod.xml" />

Your SP will be able to communicate with both IdPs after this step.

# The .NET Adapter API

The API documentation is currently available via HTML documentation in the api_doc folder. Use the “ConnectisAdapter” class in the “Connectis.SPClientSaml.Api” namespace, implemented in the “Connectis.SPClientSaml.dll” assembly. You will also need to reference “Connectis.SPClientCore.dll” and most likely “Connectis.SPClientMvcUtil.dll” (or one of the other “*Util” libraries) as well, depending on your application.

If using log4net for logging you will probably want to reference “Connectis.SPClientLog4NetUtil.dll” and use the “LoggerFactory.SetLoggerService()” method in the “Connectis.SPClientCore.Logging” namespace with an instance of the “Log4NetLoggerService” class from the “Connectis.SPClientLog4NetUtil.Logging” namespace. Please carefully read the documentation of that method, we recommend calling it from a static constructor of your application's startup class. If you need to use other logging frameworks, please consider implementing the ILoggerService and ILogger interfaces from “Connectis.SPClientCore.Logging” appropriately. If that does not work please contact the Connectis Technical Support for assistance.

The Demo Application is a good example of using the Connectis Adapter API.

Please note that, although the “ConnectisAdapterConfiguration” class is public and is part of the Adapter API, it is expected that most applications won’t have a use for it; it is exposed in order to support the feature-rich demo application. If you need to use this class please do not modify the configuration objects that are returned by the API. The “ConnectisAdapterConfiguration” API is subject to frequent change without notice.

← Getting Started Security and Validations →