Creating a simple SP from scratch

In this tutorial, we will set up a simple Service Provider, written in Microsoft.NET, and connect it to the SURFconext infrastructure.

The tutorial is created with Visual Studio 2010 using ASP.NET and C#.NET and the open source library OIOSAML.NET.

Download OIOSAML.NET

The library OIOSAML.NET was developed as a project for the Danish government as their common SSO solution. You can download it from: OIOSAML.NET project. The version used for this example is 1.7.4.

Add valid certificate

Make sure you have your certificate for your service provider. You can either use a real certificate, or create a selfsigned certificate (http://technet.microsoft.com/en-us/library/cc753127%28v=ws.10%29.aspx)

Import the certificate into Local Computer\Personal\Certificates.

Futhermore, the identity of the application pool should be given full control of the SP-certificate in the Microsoft Management Console (mmc.exe). See the following two screenshots.

The certificate of SURFconext will not be stored in the certificate store, but it is part of the metadata file (see paragraph: Download SURFconext metadata). You have to change to web.config file to use the certificate in the metadata file in stead of the certificate store.

Create ASP.NET web site

In Visual Studio create a new website based on the ASP.NET Web Site with target Framework 3.0 or higher.

Configure federated login

This paragraph contains the steps to configure the web site for federate login.

• Add the OIOSAML.NET assembly dk.nita.saml20.dll as reference to the web site.

• Create 3 handler files (.ashx) with the content as described:

  • login.ashx

    Code Block
    language css
    <%@ WebHandler class="dk.nita.saml20.protocol.Saml20SignonHandler" %>

  • logout.ashx

    Code Block
    language css
    <%@ WebHandler class="dk.nita.saml20.protocol.Saml20LogoutHandler" %>

  • metadata.ashx

    Code Block
    language css
    <%@ WebHandler class="dk.nita.saml20.protocol.Saml20MetadataHandler" %>

• Open the web.config file and make the following changes to configure federated login:

  • Add 2 configuration section for Federation and SAML20Federation

    Code Block
    language csharp theme Default
    <configSections> <section name="Federation" type="dk.nita.saml20.config.ConfigurationReader, dk.nita.saml20"/> <section name="SAML20Federation" type="dk.nita.saml20.config.ConfigurationReader, dk.nita.saml20"/> </configSections>

  • Create the section Federation

    Code Block
    language xml theme Default
    <Federation xmlns="urn:dk.nita.saml20.configuration"> <SigningCertificate findValue="{Certificate Subject Details}" storeLocation="LocalMachine" storeName="My" x509FindType="FindBySubjectDistinguishedName"/> <!-- The list of allowed audiences must at least contain the id of the service provider. --> <AllowedAudienceUris> <Audience>https://your.website.nl/</Audience> </AllowedAudienceUris> </Federation>

  • Change the findValue into the Subject details of the SP certificate, for example "CN=your.website.nl, C=NL" and the text of the <Audience> element.

• • Create the section SAML20Federation

    Code Block
    language xml theme Default
    <SAML20Federation xmlns="urn:dk.nita.saml20.configuration"> <ShowError>true</ShowError> <!-- may not be set to TRUE in production --> <ServiceProvider id="https://your.website.nl/" server="https://your.website.nl"> <ServiceEndpoint localpath="/login.ashx" type="signon" redirectUrl="/Members/Hello.aspx" index="0"/> <ServiceEndpoint localpath="/logout.ashx" type="logout" redirectUrl="/Default.aspx" index="1"/> <ServiceEndpoint localpath="/metadata.ashx" type="metadata"/> <md:ContactPerson contactType="administrative" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"> <md:Company>Your Organisation</md:Company> <md:GivenName>Givenname</md:GivenName> <md:SurName>Surname</md:SurName> <md:EmailAddress>address@yourorganisation.nl</md:EmailAddress> <md:TelephoneNumber>010-1234567</md:TelephoneNumber> </md:ContactPerson> </ServiceProvider> <RequestedAttributes> <att name="urn:mace:dir:attribute-def:uid" isRequired="true"/> <att name="urn:mace:dir:attribute-def:sn"/> <att name="urn:mace:dir:attribute-def:givenName"/> <att name="urn:mace:dir:attribute-def:cn"/> <att name="urn:mace:dir:attribute-def:displayName"/> <att name="urn:mace:dir:attribute-def:mail"/> <att name="urn:mace:dir:attribute-def:eduPersonAffiliation"/> </RequestedAttributes> <IDPEndPoints metadata="C:\Metadata\"> <add id="https://engine.surfconext.nl/authentication/idp/metadata"> <CertificateValidation> <add type="dk.nita.saml20.Specification.SelfIssuedCertificateSpecification, dk.nita.saml20"/> </CertificateValidation> </add> </IDPEndPoints> </SAML20Federation>

  • Change the id and server attributes of the <ServiceProvider> element. The id is the name you will use for the registration at SURFconext. The server is the host name of the web server as it can be reach from the internet.
  • Set the redirectUrl attributes to a page where you want to go after the user is logged in or logged out.
  • Fill in the correct values of the child elements of <md:ContactPerson>.
  • Define the requested attributes. See SURFconext wiki for the available attributes.
  • Change the attribute metadata of the element <IDPEndPoints> to a folder on the server, where the application pool user has read rights. In the following step you will download the metadata of SURFconext and save in the folder specified in the metadata attribute. The CertificateValidation element is used to do the certificate validation with the certificate in the metadata file.
  • Modify the loginUrl of the <forms> element into "~/Login.ashx".

Download SURFconext metadata

Download the metadata from SURFconext and save the xml file as: metadata.xml.

After you stored the metadata file and try to login to your web site, the following error message will appear:

The next step is to connect to SURFconext.

Connect to SURFconext

First check your website by opening: https://your.website.nl/metadata.ashx. When the data is properly showed in the internet browser, it is time to notify SURFnet.

SURFnet doesn't allow just anyone to connect directly to its production platform. To register, send an email to support@surfconext.nl. Include at least the following information:

• location of you metadata (e.g., [https://your.website.nl/metadata.ashx])
• description of your service
• name, email address, and phone number of a technical and an administative contact at your organization
• contact information for you end user support
• a list of identity providers that need access to your service. For testing purposes, it is common to request access for the SURFconext TEST/DIY IdP only.

The SURFconext administrators will get back to you quickly.

Test the web site.

All is set and done. When you click login to the web site, you will be redirected to the WAYF page of SURFconext.

When you get an error message about an invalid signature, you have to verify that both the certificates of your SP and SURFconext are imported correctly into the certificate store.

Please note that this example is for the production environment of SURFconext. For the connect/development (playground) environment of SURFconext all references to https://engine.surfconext.nl/ should be replaced by https://engine.connect.surfconext.nl/

That's all folks!

You now have an example of a .NET web site connected to SURFconext. Enjoy!

Any questions and comments are welcome at support@surfconext.nl