Net SAML2 Service Provider Framework
Net SAML2 Service Provider Framework
Chapter 5 provides a quick start guide for creating a functional sample application of the framework in your
own environment.
Each component in this distribution is described in detail in chapters 4 and 7.
The API reference chapter explains how the framework can be used to access user information issued by
identity providers.
2 Release history
1.0 RC 1 24th of April 08 Extracted the Saml2 framework from Safewhere’s codebase.
Created a demo service provider.
Moved classes into the dk.nita.saml2 namespace.
Created this document.
1.0 30th of May 08 Added demonstration identity provider.
Implemented SOAP binding.
Implemented ARTIFACT binding.
Implemented attribute queries.
Implemented persistent pseudonyms.
Extended documentation.
1.1 25th of July 08 Implemented review comments.
Demo IdP configuration is now persistent.
1.3.0.2 11th of .Net Framework requirement changed to 3.0 for binary dist.
September 2008
1.5 RC 1 27th of Incorporated 4 patches from Trifork:
November 2009 1) ID in signaturevalidation.
2) Wrong AttributeConsumingService block
3) Error regarding empty AttributeConsumingService
5) Logging
Implemented Configuration feature for the DemoIdP.
Corrected æøå-error in sign-out.
Implemented replay-check
Extended the documentation regarding
1) setup of Common Domain Cookie.
2) logging
3) Configuration of DemoIdP.
1.5 21th of Added description of private key access in 2008.
December 2009 Added paragraph on how to Connect DK.NITA with ADFSv2.
Moved Project Reference for WebDemoVirk
1.7 6th of december Support for POST-binding with regard to single-logout. The metadata
2010 generator will automatically add support for POST-binding SLO if new
metadata is generated.
The service providers will have to exchange metadata with the IdP's
again to ensure that the IdP's will use the post-binding.
Note that some IdP's might prefer HTTP-Redirect binding if both are
enabled (currently both are enabled, you will have to remove the
HTTP-Redirect entry from the metadata in that case)
1.7.3 11th of August Better validation of the reference URI in ds:signature elements
2011
1.7.4 18th of Hide detailed errormessages due to security vulnerability in XML
November 2011 Encryption
1.7.5 28th of March Fixed HttpRedirect endcoding issue to allow Danish character in
2012 certificate CN.
Saving IDP NameID in session state.
AllowCreate XmlIgnored on NameIDPolicy
Test option in SP page for AssuranceLevel
NameIdFormat added to metadata generation
Added template for web.config to help with nemlogin integration.
1.7.6 May 2012 Implemented missing logging required according to “Logningspolitik for
den fællesoffentlige log-in-løsning”
1.7.7 2013-09-11 Changed the serialization og the protocolSupportEnumeration element
so that it works with the .Net4.5 runtime
1.7.8 2013-11-07 Removed the dependency on log4net by defining an IAuditLogger
interface. The framework allows the implementor to define and use
their own implementation for audit logging (see section 14 for more on
audit logging).
Fixed bug about Single Logout failing when session had expired. The
framework now sends a successfull LogoutResponse even if the session
has expired.
dk.nita.saml20.config.IDPEndpoints.Refresh() method is no
longer public
dk.nita.saml20.config.IDPEndpoints.metadataLocation changed
to a property
dk.nita.saml20.config.IDPEndpoints.MetadataLocation
1.7.9 2014-02-25 Removed the default XmlResolver functionality from XmlDocument and
XmlTextReader objects.
The framework will now ignore external references when resolving XML
documents, hereby mitigating potential XXE attacks.
The IAction interface has been expanded with an extra method called
SoapLogoutAction(AbstractEndpointHandler, HttpContext, string) which
is called when a SOAP logout request is received. It is still necessary at
each HTTP request to check whether or not the user has been logged
out by a SOAP logout request as this is not possible at the time the
implementation of SoapLogoutAction is called.
1.7.11 2014-09-25 Enabled EnableViewStateMac, thereby mitigating potential exploit
where an attacker may be able to upload and execute arbitrary code on
the web server.
1.7.12 2015-04-13 Implemented check for Open Redirect Attack regarding return URL. It is
activated by default but can be configured. See section 9.1.5.
The dk.nita.saml20.ext.audit.log4net project uses Log4net to provide audit and logging facilities. More on
log4net can be found on http://logging.apache.org/log4net/index.html , a version of the log4net.dll is supplied
with the dk.nita solution. This version, or a version found on the Apache site, must be copied to the bin
directory of the service provider if log4net auditlogging is used.
4 Distribution contents
The framework is distributed as two packages
A binary archive containing compiled versions of the framework and sample applications.
A zip archive containing the source code for the above mentioned components.
5.1 Preparation
1. If working with the source distribution, open and compile in Visual Studio. The Saml2Test project
can be disabled, if you are not interested in executing the included automated tests.
2. Install the certificates (contained in the distribution) to support both the service provider and identity
provider. The certificates are located in dk.nita.saml20\bin (or …\src).
The password for the certificates is “test1234”.
a. Start the Microsoft Management Console (MMC) and add the Certificates snap-in.
Choose “Computer Account” and then “Local Computer”.
3. Open up IIS Manager and add two new Virtual Directories (Applications if on IIS 7):
a. One named demo that points to the service provider, the WebsiteDemo directory. The
resulting URL should be http://<machinename>/demo
b. One named IdP that points to the identity provider, the IdentityProviderDemo
directory. The resulting URL should be http://<machinename>/IdP
4. Set the correct access control entries, ACLs, on the certificates just installed in step 2:
Note: If running on IIS 6.0 or above you will most likely have applied the default setup of the websites,
which means they will be run by the built-in account, NETWORK SERVICE. This account must be
granted read access to the certificates – this can either be done directly from the MMC with the
certificate snap-in, or as described below (Will not work on Windows 7 or Windows Serve r 2008
R2):
On Windows server 2008 and Windows 7, the private key properties can be accessed directly from the
certificate snap-in in the MMC, as shown in the screenshot below:
5. Modify the Web.config of the identity provider, the IdentityProviderDemo application. One app
setting must be changed:
a. The <IDPDataDirectory> element holds the path to the directory containing metadata of
service providers. Make sure to specify a directory that is accessible by the web server
(typically the Network Service account).
6. Modify the Web.config of the service provider, the WebsiteDemo application. Two elements must
be changed in the <SAML20Federation> section:
a. The server attribute must contain the base URL without sub-directories.(This setting
will be used as the base for all URLs that are exposed to federation partners through
metadata.) Change this to http://<machinename>/
b. The <IDPEndPoints> element holds the path to the directory containing metadata of
identity providers. Make sure to specify a directory that is accessible by the web server
(typically the Network Service account).
c. Change the entity id to your demo IdP’s actual entity id:
<IDPEndPoints metadata="C:\metadata\">
<add id="DemoIdPEntityId">
<CertificateValidation>
<add type="…"/>
</CertificateValidation>
</add>
</IDPEndPoints>
You need to change the value “DemoIdPEntityId” to the actual entity id of your demo IdP. You can see
the correct entity id in the IdP’s control panel (Step 8 shows you how to get to the control panel).
The next step is to exchange metadata between the identity and service providers.
b. Enter the URL for this identity provider. Avoid localhost or 127.0.0.1
c. Download the metadata and place it into the directory specified in step 6.b
d. Add the sample service provider by uploading the metadata just downloaded to the temporary
location used in step 7
9Copy log4net.dll (found in the distribution of OIOSAML.net 1.5 ) to the bin directory of the demo service
provider.
The framework contains a number of automated tests that can be executed with NUnit 2.4 (or compatible
software), and can be executed by loading the dk.nita.test.saml20.dll and/or dk.nita.test.saml20.ext.brs.dll into
NUnit and executing the tests. Note that the tests are only included in the source distribution of OIOSAML.NET.
5. Clicking “Logout” will terminate the user’s session and initiate the logout conversation between the
service provider(s) and the identity provider.
To illustrate the dependence on correctly configured and always valid and not revoked certificates try to
change the certificate of the service provider or the identity provider after exchanging metadata. This will
cause messages between the federation partners to be rejected due to invalid signatures.
5.4 Demonstrating IdP Discovery using Common Domain Cookie
This section illustrates how to perform IdP Discovery as describe in the SAML Identity Provider Discovery Profile
by enabling the Common Domain Cookie approach in the Federation. Note that IdP Discovery is only relevant
when multiple IdPs are present in the same federation.
The setup explained in this section corresponds to the configuration illustrated in the first figure in chapter 11,
which consists of two Service Providers and two Identity Providers. It is assumed that the certificates are
already installed as explained in section 5.1.
5.4.1 Preparation
1. Create the directory ”C:\inetpub\cdctest”.
2. Copy the “dk.nita.saml20\WebsiteDemo” and
“dk.nita.saml20\IdentityProviderDemo” directories to the “C:\inetpub\cdctest”
directory.
3. Rename the “WebsiteDemo” folder to “sp1” and the “IdentityProviderDemo” folder to
“idp”.
4. Make a copy of the “sp1” folder and name the new copy “sp2”.
5. Open the IIS Manager and add three new Sites:
a. One named demosp1 that points to Service Provider 1, the sp1 directory.
b. One named demosp2 that points to Service Provider 2, the sp2 directory.
c. And finally one named demoidp pointing to the Identity Provider, the idp directory.
6. In the IIS Manager edit the bindings for the three sites:
a. For Service Provider 1:
Add the entries: demosp1.commondomain.local
demosp1.local
b. For Service Provider 2:
Add the entries: demosp2.commondomain.local
demosp2.local
c. Identity Provider:
Add the entry: commondomain.local
(Note that the Identity Provider must be located on the domain corresponding to the common domain.
This is not a requirement for Identity Providers in general, but is the only way to make it work with the
Demo IdP.
7. Add the following entries to the hosts file (C:\Windows\System32\drivers\etc\hosts):
127.0.0.1 commondomain.local
127.0.0.1 demosp1.commondomain.local
127.0.0.1 demosp2.commondomain.local
127.0.0.1 demosp1.local
127.0.0.1 demosp2.local
8. Modify the Web.config of the identity provider, the idp application. One app setting must be changed:
a. The <IDPDataDirectory> element holds the path to the directory containing metadata of
service providers. Make sure to specify a directory that is accessible by the web server
(typically the Network Service account).
2. Add a new file, cdcreader.ashx, to each of the two Service Providers, sp1 and sp2
a. Put the following into each cdcreader.ashx file:
<%@ WebHandler Class="dk.nita.saml20.protocol.Saml20CDCReader" %>
3. Modify the Web.config files of the two Service Providers, the sp1 and sp2 applications:
a. Two elements in the <SAML20Federation> section must be changed:
i. The id attribute of the <ServiceProvider> element must be changed to something
unique for each service provider, eg. http://sp1.example.net and
http://sp2.example.net
ii. The server attribute of the <ServiceProvider> element should be changed to
http://demospX.local – where X is either 1 or 2 depending on the Service Provider.
iii. The <IDPEndPoints> element holds the path to the directory containing metadata
of Identity Providers. Make sure to specify a directory that is accessible by the web
server (typically the Network Service account).
iv. In order to demonstrate the Common Domain Cookie, add a dummy Identity Provider
like so:
<IDPEndPoints metadata="C:\inetpub\cdctest\sp1\metadata\">
<add id="DemoIdPEntityId">
<CertificateValidation>
<add
type="dk.nita.saml20.Specification.SelfIssuedCertificateSpecification,
dk.nita.saml20"/>
</CertificateValidation>
</add>
<add id="dummy"></add>
</IDPEndPoints>
You need to change the “DemoIdPEntityId” to the actual entity id of your demo
IdP.
You can see the correct entity id in the IdP’s control panel.
b. Change the six places where it says “/demo/…” to ust “/”
c. Reading of the Common Domain Cookie can be enabled by adding the <CommonDomain>
element to the <SAML20Federation> element:
<CommonDomain enabled="true"
localReaderEndpoint="http://demospX.commondomain.local/cdcr
eader.ashx" /> (where X is either 1 or 2)
d. Change the <Federation> section to included to <Audience> tags containing the id’s of the two
service providers (the id attributes from the <ServiceProvider> elements mentioned above.)
11. The next step is to exchange metadata between the Identity and Service Providers:
a. Go to the Service Provider 1’s website (http://demosp1.local/default.aspx ), and download the
metadata to a temporary location of your choice.
b. Repeat the previous step for Service Provider 2.
c. Go to the Identity Provider’s control panel (http://demoidp/Control.aspx ) and configure the
running IdP:
i. Chose the certificate to identify this identity provider. Chose the IdentityProvider
certificate (CN=IdentityProvider, O=NITA, C=DK) in LocalMachine and My store.
ii. Enter the URL for this identity provider. Normally the default will be OK, but avoid
localhost or 127.0.0.1
iii. Download the metadata and place it into the directory (specified in 9.a.iii –
“C:\inetpub\cdctest\sp1\metadata\”.
d. Add the two Service Providers by uploading their metadata, which was download to the
temporary locations used in steps 10.a and 10.b.
5.4.2 Demonstration
1. Access Service Provider 1’s website (http://demosp1.local/Default.aspx ) and click “Go to My page”
2. Select which Identity Provider to authenticate the user from the list of Identity Providers. Notice the
dummy Identity Provider which cannot be selected, since it is not needed in order to demonstrate the
Common Domain Cookie proof of concept.
3. Login as the user “Lene1” and password “Test1234”.
4. Access Service Provider 2’s website (http://demosp2.local/Default.aspx ) and click “Go to My page”
5. Notice that the user is not asked to login again, since he has already been authenticated.
6. Clicking “Logout” will terminate the user’s session.
In case more than one IDP has been configured in the IDPEndPoints collection, and no Common Domain Cookie
has yet been set, it is possible to select authorization IDP in 3 ways:
1. By setting a default IDP in the SAML20Federation configuration section (see section 5.5.1)
2. In the SAML20Federation configuration section, by specifying a URL on the website that lets the user
select IDP (see section 5.5.2)
3. By implementing a .NET event handler that returns the IDPEndpoint to use (see section 5.5.3)
The list above is ordered, that is, in case a default is configured (method no. 1), use of the methods no. 2 and 3
are ignored by OIOSAML.NET. In the samples below it is therefore important to remove changes done to the
configuration file in the previous example.
1. In the example above, modify the Web.config by adding a default=”true” attribute to the
<add…> element for the Idp: <add id="http://commondomain.local/"
default="true">
2. Restart the browser to make sure the common domain cookie is removed
3. Access Service Provider 1’s website (http://demosp1.local/Default.aspx ) and click “Go to My page”
4. Notice that the user is not prompted, which IDP to use, since he is immediately redirected to the
default IDP.
With this method, the developer can specify a page that the user should be redirected to, in case multiple IDP’s
are available:
1. In case you modified the Web.config as explained in 5.5.1, remove the default=”true”
2. In the <IDPEndPoints> element, add the idpSelectionUrl and value, so the element looks like this:
<IDPEndPoints metadata="C:\inetpub\cdctest\sp1\metadata\"
idpSelectionUrl="/IDPSelectionDemo.aspx">
3. Restart the browser to make sure the common domain cookie is removed
4. Access Service Provider 1’s website (http://demosp1.local/Default.aspx ) and click “Go to My page”
5. Notice that the browser opens a web-page from the WebsiteDemo project (IDPSelectionDemo.aspx),
and not the default IDP selection list from the OIOSAML.NET framework. IDPSelectionDemo.aspx is just
a sample of, how a page could look like. The styling and contents is completely defined by the
web-developer. The only thing to remember is, that the link, that the user clicks, points to the URL
returned by the GetIDPLoginUrl() method on the
dk.nita.saml20.config.IDPEndPoint class. See IDPSelectionDemo.aspx.cs for an example.
The third method for selecting an IDP end point is done programmatically by using a .NET event:
1. In case you modified the Web.config as explained in 5.5.1, remove the attribute default=”true”
2. In case you modified the Web.config as explained in 5.5.2, remove the attribute
idpSelectionUrl="/IDPSelectionDemo.aspx"
3. See an example of a IDPSelectionEvent handler in Global.asax.cs, named
_idpSelectionEventHandler. To use this handler add this line to Application_Start (in
Global.asax.cs):
IDPSelectionUtil.IDPSelectionEvent += _idpSelectionEventHandler;
4. Since we are professional developers, always remembering to clean up, dispose etc. in our code (!) ,
add this line to Application_End (in Global.asax.cs):
IDPSelectionUtil.IDPSelectionEvent -= _idpSelectionEventHandler;
5. Restart the browser to make sure the common domain cookie is removed
6. Access Service Provider 1’s website (http://demosp1.local/Default.aspx ) and click “Go to My page”
7. Notice that the user is not prompted, which IDP to use, since he is immediately redirected to the IDP
chosen by the event handler.
6 Using the framework
To develop a new web site using the framework you may follow the procedure below for getting up and
running. This procedure serves only as a guide as your environment may differ from what is described below.
Also described are the steps to work with real identity providers and how to set up more than one service
provider.
2. In the solution, include the Saml2 project containing the framework (may be left out if you keep a
compiled version of the framework for reference)
3. Add a reference to the Saml2 project (or, if working with a compiled version, add a reference to the
dk.nita.saml20 assembly, dk.nita.saml20.dll)
4. Create three ASP.NET handlers (ashx files) each with the content as illustrated below:
o login.ashx (Your choice of name, but note it down as you will reference it later)
o logout.ashx (Your choice of name, but note it down as you will reference it later)
o metadata.ashx (Your choice of name, but note it down as you will reference it later)
<section name="Federation"
type="dk.nita.saml20.config.ConfigurationReader,
dk.nita.saml20" />
<section name="SAML20Federation"
type="dk.nita.saml20.config.ConfigurationReader,
dk.nita.saml20"/>
o In the system.web section, add/change the authentication element:
<authentication mode="Forms">
<forms cookieless="UseCookies"
loginUrl="<YOUR LOGIN HANDLER AS NAMED ABOVE>"
name="<YOUR COOKIE NAME>" />
</authentication>
o To describe which parts of the application are protected by forms authentication, you must use
the ASP.NET location tag (see the sample for an example of this). The reason for this is that
you need unauthenticated access to not only the login.ashx handler, but also the
metadata.ashx handler.
o For fastest results, copy from the sample service provider, WebSiteDemo, the Federation section
and modify to your application. Refer to the reference in section 10.1 for de tails on each element.
Note that to configure this element for a real world application, you will need your own
certificate configured correctly for access by the web server.
Note that the AllowedAudiencesUris element must be set to match the Id of the service
provider in the SAML20Federation as described below
o For fastest results, copy from the sample service provider, WebSiteDemo, the SAML20Federation
section and modify to your application. Refer to the reference in section 10.2 for details on each element.
Note that the Id attribute must be unique and match the audience requirements of the
Federation section (see previous point)
Note that for the signon service endpoint you do not have to set a redirect URL. If you
want the user to be able to directly access any part of your application, and
authentication on the way if necessary, remove this redirectUrl attribute.
6. Download the metadata of your application from the endpoint specified in the SAML20Federation
element as described above (e.g. https://hostname/MyApp/metadata.ashx). These metadata must be
given to the identity provider(s) of your choice.
7. Install the metadata of your identity provider(s) in the directory specified in the Saml20Federation
section
8. That’s it. Now try it out with the sample identity provider and finally integrate with a third party
identity provider
2. No matter how this is done, setting up more than one service provider, you must be sure to set
authentication cookie names to different values across machine and domain:
Once more than one service provider is available, you should notice that the user will not be re-authenticated
when logging in at the second service provider.
7 Components
Handles authentication and logout of user sessions across several service providers.
Validates signatures.
The demonstration identity provider uses the SAML 2.0 Framework and is primarily meant as a companion to
the demonstration service provider in order to deliver an easily created environment in which to get
acquainted with the framework. It should not be used as a permanent substitute for at real identity provider in
a development environment.
The users, passwords and issued attributes can be set-up in the web.config of the DemoIdP as shown in the
example below:
<configSections>
<section name="demoIdp"
type="IdentityProviderDemo.Logic.DemoIdPConfigurationSection"/>
</configSections>
<demoIdp>
<users>
<add userName="Lene" password ="Test1234"
ppid="PPID-FDFFE8F1-D92C-4838-B46D-B3DD558E700E">
<attributes>
<add name="urn:FirstName" value="Lene"/>
<add name="urn:LastName" value="Hansen"/>
<add name="urn:Age" value="32"/>
<add name="urn:oid:0.9.2342.19200300.100.1.3" value="[email protected]"/>
<add name="urn:dk:company:attribute:Role" value="Medarbejder"/>
<add name="urn:dk:company:attribute:Role" value="Udvikler"/>
</attributes>
</add>
<add userName="Åge" password ="Test1234"
ppid="PPID-7CDE9A20-8A40-429a-A390-FFAB7DF84DF3">
<attributes>
<add name="urn:FirstName" value="Åge"/>
<add name="urn:LastName" value="Børgesen"/>
<add name="urn:Age" value="23"/>
<add name="urn:oid:0.9.2342.19200300.100.1.3" value="Å[email protected]"/>
<add name="urn:dk:company:attribute:Role" value="Øverste Chef"/>
</attributes>
</add>
</users>
</demoIdp>
8 Certificate management
The certificates supplied and installed with the sample included in this framework, work nicely when being
used by the person who installed the certificates, which is the case when e.g. running the NUnit tests supplied.
When using the certificates of the sample, the account running the web site (NETWORK SERVICE by default)
must be granted read access to the private keys. This will ensure that communication between the service
provider and the identity provider may be signed correctly.
The following procedure uses a small utility supplied in the distribution. With the tool and this procedure you
may grant access to the private keys of the certificates as required by the web site setup.
1. Open a command prompt in the directory where the framework is installed (..\bin or ..\src).
3. Expand the ‘Issued To’ column, select the certificate you are going to use for the service provider (the
supplied certificate read “ServiceProvider”) and click the OK button.
6. Before closing the above dialog, verify that the account is now present on the l ist.
9 Configuration reference
All XML elements of this reference belong in the namespace ‘urn:dk.nita.saml20.configuration’,
unless otherwise noted.
9.1 <Federation>
This element contains settings that are general to federation: i.e. the certificate and identifier of the machine in
the federation.
auditLoggingTy The fully qualified name of the class that implements the IAuditLogger
pe interface. This interface allows implementors to define and use their own
audit logging functionality.
If the attribute is not provided the framework will use System.Diagnostics
tracing as default for the audit logging.
sessionType The fully qualified name of the class that implements the ISessions
interface. This interface allows service providers to define and use their
own session implementation.
If the attribute is not provided the framework will use the default
implementation dk.nita.saml20.session.inproc.InProcSessions as default for
handling the session state.
9.1.1 <SigningCertificate>
This element specifies the service provider’s certificate, which is used to verify the identity of the service
provider to its service partners. The element’s attributes are listed in the following
x509FindType Specifies which certificate attribute that will be used to identify the service
provider’s certificate. The documentation of the .net framework enumeration
X509FindType lists the possible values for this attribute.
A common way to locate a certificate is to search for its subject’s distinguished
name or its thumbprint. The service provider will use the first certificate that
matches the specified search criteria.
findValue The value of the attribute that is used to identify the certificate, e.g. its subject or
thumbprint.
storeLocation The location of the certificate store to use. The documentation of the .net
framework enumeration StoreLocation lists the possible values for this
attribute.
storeName Specifies which certificate store the certificate can be found in. The documentation
of the .net framework enumeration StoreName lists the possible values for this
attribute.
validOnly Search only the valid certificates. An invalid or expired certificate may cause
federation partners to reject communication, so enabling this option may give an
early warning that a certificate should be replaced. Value should be either true
or false.
Most of the above values for a given certificate can be found using the ‘Certificates’ management application
included with windows.
9.1.2 <AllowedAudienceUris>
Assertions are issued to specific audiences. This ensures that an assertion cannot be used at a different service
provider than the one that was intended by the identity provider. This configuration setting is a list of
audiences that are allowed for assertions sent to the service provider. The list must at least contain the
identifier of the service provider (See 10.2.1).
9.1.3 <Actions>
The <Actions> element defines a list of actions that take place on the service provider side when an assertion is
received from the IdP. The element is optional, and when not present , a default set of actions are performed.
Actions are performed in the sequence in which they are added. The default set of actions would look like this
in the configuration file:
<Actions>
<add name="SetSamlPrincipal" type="dk.nita.saml20.Actions.SamlPrincipalAction, dk.nita.saml20 " />
<add name="Redirect" type="dk.nita.saml20.Actions.RedirectAction, dk.nita.saml20 " />
</Actions>
A <clear/> tag can be used to clear the list of actions, and a <remove> tag can be used to remove a single action
by name, eg.: <remove name="SetSamlPrincipal"/>.
It is possible to write your own custom actions to perform any task needed during login and logout. Your action
must implement the dk.nita.saml20.Actions.IAction interface, and if you plan to make an
action that performs a redirect you should note the following:
1) A redirect must be the last action in the list, since redirecting ends the action pipeline.
2) Redirecting during logout should only be performed when the logout is NOT initiated by the IdP. If it is
initiated by the IdP, a redirect action should do nothing. You will know whether or not the logout is IdP
initiated by checking the Boolean parameter IdPInitiated of the LogoutAction function of the
IAction interface .
9.1.4 <SessionTimeout>
The <SessionTimeout> element defines when the OIOSAML.net session state must expire. The OIOSAML.net
component uses sliding expiration, which means the session timeout is reset on each request to the session.
The value must be specified in minutes and the default value is 30 minutes if no SessionTimeout element has
been specified. This value should be equal to or higher than the authentication session (e.g. if forms
authentication is used). Otherwise, strange behaviour can occur because the system thinks that the user is
logged id but no principal exists in the OIOSAML.net session.
9.1.5 <PreventOpenRedirectAttack>
The <PreventOpenRedirectAttack> element defines whether the return URL is checked for the Open Redirect
Attack. If not set, the default value is “true”. Legal values are “true” and “false” in lower case.
9.2 <Saml20Federation>
The <Saml20Federation> element contains configuration options that are specific to the SAML 2.0
protocol.
9.2.1 <ShowError>
This setting is used for development purposes alone – it default to false if omitted. When set to true, any
errors, both exceptions and validation errors are shown in the browser. Due to a security issue with XML
Encryption, this setting must be set to false (or omitted) when used in production, otherwise an attacker might
be able to decrypt any messages send to the serviceprovider.
Example
<ShowError>false</ShowError>
9.2.2 <ServiceProvider>
This element contains the following attributes
Attributes
Id The service provider’s identifier. This is often an URI signaling the domain of the service
provider.
server The base URL of the host where the service provider resides. No sub-directories.
<md:Organization xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
<md:OrganizationName>Firma</md:OrganizationName>
<md:OrganizationDisplayName>Firmanavn</md:OrganizationDisplayName>
<md:OrganizationURL>Error! Hyperlink reference not valid.>
</md:Organization>
9.2.3 <CommonDomain>
The <CommonDomain> element contains configuration options for common domain cookie reading, and has
the following attributes:
Attributes
Enabled A Boolean value indicating whether or not common domain cookie
reading is turned on.
localReaderEndpoint The fully qualified url to a local cookie reader endpoint. The host part of
this endpoint should be a sub domain to the common domain, e.g.
sp.commondomain.com
The following is an example of a CommonDomain section:
Read more about how to configure common domain cookie reading in chapter 11.
9.2.4 <RequestedAttributes>
This element names the SAML attributes that the service provider requires from its federation partners.
9.2.5 <IDPEndPoints>
The configuration in the <IDPEndPoints> element determines how the service provider communicates
with its federation partners. The minimal configuration specifies the directory in which metadata of the
federation partners can be found, and uses the default SAML bindings for communication.
Attributes
metadata The path to the directory where the metadata of the federation partners can
be found. Make sure that the directory is readable by the user running the web
server.
idpSelectionUrl URL for custom webpage that lets the user select from a list of available IDP’s.
The attribute is used only when no common domain cookie is set, and no
add-element (see below) has the default-property set to true. In case no
idpSelectionUrl is specified, a default IDPSelectionPage is displayed. See
example of using this attribute in section 5.5.2.
The <IDPEndPoints> section can furthermore override the settings that are found in the metadata of a
federation partner. This is useful for situations where the federation partner allows several ways of
communicating and the default way is not desirable.
9.2.6 <MinimumAssuranceLevel>
Valid values are the ones defined in the “OIO Web SSO Profile” specification. An assertion will be rejected if e.g.
configuration is set to 3 and the assertion is marked with assurance level 2.
The assurance level check is not made if the assertion does not contain the assurance level attribute.
The default value is 3 if not specified in the configuration.
Example
The SAML extended principal is obtained through the Saml20Identity.Current property. This property
is null if the user has not been authenticated with a SAML assertion.
Class Saml20Identity
Properties
static Saml20Identity Retrieves the user's identity and the attributes that were
Current extracted from the SAML assertion. Returns null if the user
has not been authenticated using SAML. If null is returned
the system must ensure that the user is logged out of the
system.
string PersistentPseudonym This property holds the persistent pseudonym, if one was
used when authenticating the user.
Methods
static bool IsInitialized
Returns true if the user has been authenticated using SAML. Can be used to check that the
Saml20Identity is available. If false is returned the SP must ensure that the user is logged out. This
check should be made in the beginning of each user request.
bool HasAttribute(string)
Checks whether the attribute with the given name was issued with the assertion.
List<SamlAttribute> this [string]
Retrieves a list of attributes with the given name.
Example of usage:
List<SamlAttribute> name =
Saml20Identity.Current[“urn:oid:2.5.4.5”];
This method will throw a KeyNotFoundException if the attribute is not found. Use
HasAttribute to verify the presence of an attribute before calling this method.
10.2 HttpHandlers
The endpoints handling protocol messages are implemented using ASP.NET Http Handlers.
There are 3 endpoint types that must be installed to get a functioning service provider.
A service provider installation must have all 3 handlers installed. The metadata endpoint can be removed once
the service provider’s configuration is finalized and its metadata file has been downloaded.
Furthermore there are two extra endpoints, of which at least one is necessary to install if common domain
cookie reading is enabled (more details about this in chapter 11):
Endpoint type HTTP Handler class
Local cookie reading dk.nita.saml20.protocol.Saml20CDCReader
IdP cookie writer return dk.nita.saml20.protocol.SAML20CDCIdPReturnPoint
point
ASP.NET provides (at least) two ways to add HTTP handlers to a web application
Web.config
HTTP handlers can be added to a web application by adding them in the <httpHandlers> section of
web.config. Consult the MSDN documentation for a reference on the <httpHandlers> element. The
verb attribute must be set to “*” for the handlers.
Website files
More examples of .ashx files can be found in the website demo in the distribution.
10.3 Attribute queries
An attribute query enables a service provider to request more attributes on an authenticated subject from the
federation partner that authenticated him. More information on attribute queries can be found in s ection
3.3.2.3 of [SAML].
The queries are executed with the currently authenticated user as a subject. Returned attributes are available
through the Saml20Identity class after the query finishes.
The following is an example of how to query for all availabl e attributes about the currently authenticated user
Specific attributes are requested by adding the name of the attributes to the request.
As illustrated in the figure above, there reside two Service Providers and two Identity Providers in the basic
setup. The following briefly explains the scenario illustrated in the figure.
12 Virk.dk extension
The assembly dk.nita.saml20.ext.brs.dll is a framework that allows programmatic access to the Authorisations
attribute from Virk.dk.
It is important to note that the Authorisations attribute is only supplied through attribute query when using
POST binding (The only binding currently supported by this toolkit when connecting to virk.dk).
After the user is authenticated and the Authorisations attribute has been obtained through an attribute query,
you can use code like following to determine if a user X has a given privilege Y:
if(util.HasAuthorisationAttribute())
{
The function HasPrivilegeforCvrNumber throws an exception if the Authorisations attribute has not been
obtained for the current user, which is why the HasAuthorisationsAttribute should be called. The
BRSUtil class also has a function called HasPrivilegeForProductionUnit which has the same method
signature as HasPrivilegeforCvrNumber, but the first parameter should be a production unit id instead of
a cvr number.
Please refer to the WebsiteDemoVirk folder for a more complete example on how to use this extension.
13 Troubleshooting
<system.diagnostics>
<trace autoflush="true" ></trace>
<sources>
<source name="dk.nita.saml20" switchValue="Information">
<listeners>
<add name="trace"/>
</listeners>
</source>
</sources>
<sharedListeners>
<add name="trace" type="System.Diagnostics.XmlWriterTraceListener"
initializeData="C:\logs\saml2.tracelog"/>
</sharedListeners>
</system.diagnostics>
Please note that the debug information will be written to the file specified in the initializeData attribute
and that the directory (in this case c:\logs) must exist.
If you need further information to be traced you can change switchValue from “Error” to “Information”.
14 Audit & Logging
The AuditLogging class uses a System.Diagnostics Trace as default audit logger implementation if
no configuration has been applied.
The web.config file for the demo service provider shows an example of setting up log4net logging
to a file, but log4net can also log to relational databases etc.
The example is shown here (remember to configure the auditLoggingType attribute of the
Federation element to use to log4net implementation):
<configuration>
<configSections>
…
<section name="log4net" type="log4net.Config.Log4NetConfigurationSectionHandler,Log4net"/>
</configSections>
<log4net>
<root>
<level value="All" />
<appender-ref ref="LogFileAppender" />
</root>
<appender name="LogFileAppender" type="log4net.Appender.RollingFileAppender" >
<param name="File" value="C:\temp\log.txt" />
<param name="AppendToFile" value="true" />
<rollingStyle value="Size" />
<maxSizeRollBackups value="10" />
<maximumFileSize value="10MB" />
<staticLogFileName value="true" />
<layout type="log4net.Layout.PatternLayout">
<param name="ConversionPattern" value="%-5p%d{yyyy-MM-dd hh:mm:ss}-%m%n" />
</layout>
</appender>
</log4net>
…
<Federation xmlns="urn:dk.nita.saml20.configuration"
auditLoggingType="dk.nita.saml20.Logging.Log4NetAuditLogger, dk.nita.saml20.ext.audit.log4net">
15 Session Providers
A custom made session handling has been made in order to support random access to all active
sessions. This is not supported by the ASP.NET session state. Random access is needed when
receiving SOAP Logout requests which through a back channel must be able to log arbitrary user
out.
See configuration section on how to configure the OIOSAML.net component to use your own
session provider.
The InProcSessions implementation is an in-memory implementation that are suitable for service
providers running on a single server. If nothing has been configured the InProcSe ssions is used as
default.
The AppFabricSessions implementation makes use of AppFabric Cache and is suitable for service
providers that will be running in a load balanced setup. The implementation can be retrieved
from NuGet which also automatically makes the proper configurations in the web.config file.
However, the AppFabric configuration section must be updated with settings matching your own
environment.
The following shows how to setup dk.nita with ADFS v2 as Identify Pro vider.
1. Install Windows Identify Framework:
http://www.microsoft.com/downloads/details.aspx?familyid=EB9C345F -E830-40B8-A5
FE-AE7A864C4D76&displaylang=en#filelist
2. Enable SSL on IIS (Preferably use “real” certificate, i.e. not self issued)
b. If you want to have automatic metadata exchange and monitoring the the SSL
certificate on the SP must be valid and trusted (I.e. no need to accept a “broken”
certificate)
c. If you don’t want to go through the trust exercise, just download the SP metadata
into a file and load the file into ADFS
6. Add “Claim rules” (use “Edit Claim Rules…” on the popup menu of the relying party)
9. If you get an error like “ErrorCode: …status: Responder. Message: .” it may be a problem
with the expected hashing algorithm on ADFS:
a. Check the event log of ADFS and look for trouble with the signature of the SAML
Request
b. If a problem with SHA-1 vs. SHA-256 is indicated, go to ADF and bring up the
properties of the relying party (Demo SP).
c. Go to the “Advanced” tab and change the signature algorithm to SHA-1. (For some
reason ADFS is not able to read this from metadata)
2. The provided demo certificates cannot be used in this scenario. Use real issued certificates
from a trusted party (e.g. and internal CA).
17 References
[SAML] Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) v2.0
saml-core-2.0-os
http://docs.oasis-open.org/security/saml/v2.0/
[Metadata] Metadata for the OASIS Security Assertion Markup Language (SAML) V2.0
saml-metadata-2.0-os
http://docs.oasis-open.org/security/saml/v2.0/
[Bindings] Bindings for the OASIS Security Assertion Markup Language (SAML) v2.0
saml-bindings-2.0-os
http://docs.oasis-open.org/security/saml/v2.0/