Configuration¶
To use Sustainsys.Saml2 in an application and configure it in web.config
(which is the default for the HttpModule
and MVC
libraries) it must be enabled
in the application’s web.config
. The sample applications contains complete
working web.config examples. For
ASP.NET MVC applications see this working web.config
example.
Note
Applications using the Owin
library usually make their configuration
in code and in that case no web.config changes are needed. If an Owin library
is set up to use web.config (by passing true
to the Saml2AuthenticationOptions
constructor) the information here applies.
Config Sections¶
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.
<configSections>
<!-- Add these sections below any existing. -->
<section name="system.identityModel" type="System.IdentityModel.Configuration.SystemIdentityModelSection, System.IdentityModel, Version=4.0.0.0, Culture=neutral, PublicKeyToken=B77A5C561934E089" />
<section name="system.identityModel.services" type="System.IdentityModel.Services.Configuration.SystemIdentityModelServicesSection, System.IdentityModel.Services, Version=4.0.0.0, Culture=neutral, PublicKeyToken=B77A5C561934E089" />
<section name="sustainsys.saml2" type="Sustainsys.Saml2.Configuration.SustainsysSaml2Section, Sustainsys.Saml2"/>
</configSections>
Loading Modules¶
When using the HttpModule
and the MVC
controller, the SessionAuthenticationModule
needs
to be loaded and if using the http module that needs to be loaded as well. The Owin
package
does not need any http modules, please see the separate info on the Owin Middleware:.
<system.webServer>
<modules>
<!-- Add these modules below any existing. The SessionAuthenticatioModule
must be loaded before the Saml2AuthenticationModule -->
<add name="SessionAuthenticationModule" type="System.IdentityModel.Services.SessionAuthenticationModule, System.IdentityModel.Services, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/>
<!-- Only add the Saml2AuthenticationModule if you're using the Sustainsys.Saml2.HttpModule
library. If you are using Sustainsys.Saml2.Mvc you SHOULD NOT load this module.-->
<add name="Saml2AuthenticationModule" type="Sustainsys.Saml2.HttpModule.Saml2AuthenticationModule, Sustainsys.Saml2.HttpModule"/>
</modules>
</system.webServer>
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).
A sample section is shown below. For full details and all avaialble options, see sustainsys.saml2.
<sustainsys.saml2 entityId="http://localhost:17009"
returnUrl="http://localhost:17009/SamplePath/"
discoveryServiceUrl="http://localhost:52071/DiscoveryService"
authenticateRequestSigningBehavior="Always">
<nameIdPolicy allowCreate="true" format="Persistent"/>
<metadata cacheDuration="0:0:42" validDuration="7.12:00:00" wantAssertionsSigned="true">
<organization name="Sustainsys IT AB" displayName="Sustainsys" url="http://www.Sustainsys.se" language="sv" />
<contactPerson type="Other" email="info@Sustainsys.se" />
<requestedAttributes>
<add friendlyName ="Some Name" name="urn:someName" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" isRequired="true" />
<add name="Minimal" />
</requestedAttributes>
</metadata>
<identityProviders>
<add entityId="https://stubidp.sustainsys.com/Metadata"
signOnUrl="https://stubidp.sustainsys.com"
allowUnsolicitedAuthnResponse="true"
binding="HttpRedirect"
wantAuthnRequestsSigned="true">
<signingCertificate storeName="AddressBook" storeLocation="CurrentUser"
findValue="Sustainsys.Saml2.StubIdp" x509FindType="FindBySubjectName" />
</add>
<add entityId="example-idp"
metadataLocation="https://idp.example.com/Metadata"
allowUnsolicitedAuthnResponse="true"
loadMetadata = "true" />
</identityProviders>
<!-- Optional configuration for signed requests. Required for Single Logout. -->
<serviceCertificates>
<add fileName="~/App_Data/Sustainsys.Saml2.Tests.pfx" />
</serviceCertificates>
<!-- Optional configuration for fetching IDP list from a federation -->
<federations>
<add metadataLocation="https://federation.example.com/metadata.xml" allowUnsolicitedAuthnResponse = "false" />
</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).
<system.identityModel>
<identityConfiguration>
<claimsAuthenticationManager type="Sustainsys.Saml2.Tests.ClaimsAuthenticationManagerStub, Sustainsys.Saml2.Tests"/>
</identityConfiguration>
</system.identityModel>
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.
<system.identityModel.services>
<federationConfiguration>
<cookieHandler requireSsl ="false"/>
</federationConfiguration>
</system.identityModel.services>