SAML 2.

0 and Umbraco (version 1)

Table of Contents
1

Introduction ......................................................................................................................................... 3

Background .......................................................................................................................................... 3

Prerequisites ........................................................................................................................................ 3
3.1

Prerequisites for the binary distribution .................................................................................. 3

Distribution contents .......................................................................................................................... 3

Installing .............................................................................................................................................. 4

5.1

Preparation .................................................................................................................................. 4

5.2

Exchanging metadata................................................................................................................. 4

5.3

Installation of binary files .......................................................................................................... 4

Sample User Controls ......................................................................................................................... 5

6.1

LogOnOff ...................................................................................................................................... 5

6.2

SamlUserInfo ............................................................................................................................... 6

6.3

CurrentUserControl ..................................................................................................................... 6

Testing providers ................................................................................................................................ 6

7.1

Umbraco test installation ........................................................................................................... 6

7.2

Configure .NET in web.config ................................................................................................... 6

7.3

Macros for .NET User Controls.................................................................................................. 7

7.4

Creating a Document type and template ................................................................................ 8

7.5

Creating a login page ................................................................................................................. 9

7.6

Creating a default Member Group .......................................................................................... 10

7.7

Protecting a page...................................................................................................................... 11

7.8

Testing the login ....................................................................................................................... 12

Changing the default behavior ....................................................................................................... 15

8.1

Changing the default MemberGroup...................................................................................... 16

8.2

Changing the attribute for role queries ................................................................................. 16

References ......................................................................................................................................... 16

2/16

1 Introduction
This document describes a solution for authenticating and authorizing users, on a website build
with the Open Source CMS Umbraco, using an OIOSAML compatible Identity Provider.
Comments, suggestions and questions can be sent to support@silverbullet.dk

2 Background
Umbraco supports ASP .NET Membership and Role providers. The purpose of ASP .NET
MembershipProviders and RoleProviders are to provide a layer of indirection between
membership controls, like a login control and the data store containing membership and role
information.
This solution consists of a custom implementation of a MembershipProvider and a RoleProvider,
which enables Umbraco to authenticate and authorize users via an OIOSAML Identity Provider.
Via Umbracos administration console a page can be protected (public access). When this is
done, access to the protected page will always go through the MembershipProvider and
RoleProvider.
Besides the MembershipProvider and RoleProvider the solution contains sample custom .NET
user controls, which can be used to show user information on a web page.

3 Prerequisites
3.1 Prerequisites for the binary distribution

Website build in Umbraco version 4

OIOSAML.NET installation
OIOSAML 2.0 compatible Identity Provider

4 Distribution contents
The distribution contains a zip archive with the following content.
File in zip archive
UmbracoIdpLogin.zip

UmbracoIdpLogin-source.zip
UmbracoIdpLogin-guide,20090108

Description
Binary files including SamlMembershipProvider,
SamlRoleProvider, User Constrols and installation
wizard
Source files
This document in PDF and RTF

3/16

5 Installing
This chapter describes the steps required to install the solution and use the sample .NET User
Controls.

5.1 Preparation
In this document we will describe how to extend an existing website build in Umbraco 4 with
Identity Provider login. We will show this by altering a fresh new installation of Umbraco 4 with
the Boost package installed, but the installation steps can easily applied to any Umbraco 4
website.
OIOSAML.NET must be installed before installing the Umbraco-SAML solution.

5.2 Ensure that OIOSAML.NET is installed

Make sure that OIOSAML.NET is installed properly prior to installing this solution. Check for
example that dk.nita.saml20.dll is in the bin folder of your site root, and that proper
OOISAML.NET configurations are made in web.config.
See installation guide of OIOSAML.NET for further information.

5.3 Exchanging metadata

The Identity Provider and the Umbraco website must exchange metadata in order to
communicate via SAML 2.0.
Update Umbraco installation with your IdPs metadata:
1. Create a folder for the IdPs metadata for example c:\metadata
2. Get the IdPs metadata a put them in a file in the metadata folder for example
c:\metadata\idp-metadata.xml
3. Set access control entries on c:\metadata. Right click the folder, chose the security tab
and grant ASPNET on XP and NETWORK SERVICE on Vista full control on the folder.
Give your IdP the serviceprovider metadata you use in your OIOSAML.NET installation.

5.4 Installation of binary files

1. Unpack the zip archive UmbracoIdpLogin.zip into the root of your Umbraco website
installation. If Umbraco is installed in the default manner on a default IIS-installation the
path to the folder may be
C:\Inetpub\wwwroot\
2. Make sure IIS I started and then run and follow the installation wizard
http://localhost/Install/SamlInstall.aspx

4/16

6 Sample User Controls

There are 3 sample user controls contained in the distribution. These controls contain
functionality for displaying information about the current session.
The controls are only part of the distribution for demonstration purpose, and may be altered
and customized if needed.

6.1 LogOnOff
If no Umbraco Member has logged on in the current session, this control displays a button with
a login text and a logoff text when a Member has logged on.
The control has the following properties which can be set in the Template section in the
Umbraco administration console
5/16

Property name
LogOnText
LogOffText
LogOnUrl
LogOffUrl

Description
Text on the button when no Member has logged in
Text on the button when a Member has logged in
The URL called for logging in
The URL called for logging off

6.2 SamlUserInfo
This control can display information contained in the authentication SAML assertion from an
Identity Provider.
The control has the following properties which can be set in the Template section in the
Umbraco administration console
Property name
Description
SamlAttributeName Name of and OIOSAML attribute for example urn:oid:2.5.4.3 for
Common Name and urn:oid:0.9.2342.19200300.100.1.3 for
Email

6.3 CurrentUserControl
This control can display the login name of an Umbraco Member which has logged in on the
current session. The purpose of this control is to show that Umbraco is aware that a Member
has logged in.
The control has no attributes.

7 Testing providers
The following sections describe how to set up a test scenario using the sample .NET user
controls and the installed providers.

7.1 Umbraco test installation

The following test scenario uses Umbraco Boost to demonstrate the solution. The steps below
may though be applied to any website if proper changes are made.
Umbraco boost can be installed using the Umbraco Administration console and the package
library. Check the Umbraco.org for further information.

7.2 Configure .NET in web.config

To use the supplied sample .NET User Controls the right version of .NET must be specified in
web.config
1. Edit web.config in the root of your Umbraco website and replace the following

6/16

<add tagPrefix="asp" namespace="System.Web.UI" assembly="System.Web.Extensions,

Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />

2. with
<add tagPrefix="asp" namespace="System.Web.UI" assembly="System.Web.Extensions,
Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35"/>
<add tagPrefix="asp" namespace="System.Web.UI.WebControls"
assembly="System.Web.Extensions, Version=3.5.0.0, Culture=neutral,
PublicKeyToken=31BF3856AD364E35"/>

7.3 Macros for .NET User Controls

To use the supplied sample .NET User Controls you can do the following
3. Log in to the Umbraco Administration Console.
4. Go to Developer section, right click Macros and choose Create
5. Create a new Macro named IdpLoginLogoff. Use the name for both name and alias.
6. Choose /usercontrols/LogOnOff.ascx in the .net user control drop down list.
7. Click Brows properties, choose All Properties and click Save
8. Tick Use in Editor and click save.
9. Create a new Macro named IdpLoginName. Use the name for both name and alias.
10. Choose /usercontrols/SamlUserInfo.ascx in the .net user control drop down
list.
11. Click Brows properties, choose All Properties and click Save
12. Tick Use in Editor and click save.
13. Create a new Macro named CurrentUmbracoUser. Use the name for both name and
alias.
14. Choose /usercontrols/CurrentUserControl.ascx in the .net user control drop
down list.
15. Tick Use in Editor and click save.

7/16

7.4 Creating a Document type and template

We are no ready to create a document type for the login page.
1.
2.
3.
4.
5.
6.
7.
8.

Log in to the Umbraco Administration Console.

Go to Settings section
Right click on Document Types and choose create.
Name the new Document Type LoginLogout and check Create matching
template. Click create.
Fill in LoginLogout in the Name and Alias fields and click save.
Go to templates and click on the new template LoginLogout
Change master template to Boost Master
Fill in the content below in the Template code window
<%@ Master Language="C#" MasterPageFile="/masterpages/BoostMaster.master"
AutoEventWireup="true" %>
<asp:Content id="LoginLogoutcontent" ContentPlaceHolderID="BoostMasterContentPlaceHolder"
runat="server">
<div id="content">
<div id="contentHeader">
<h2><umbraco:Item runat="server" field="pageName"/></h2>
</div>
<umbraco:Item runat="server" field="bodyText" />
<?ASPNET_FORM>
<umbraco:Macro LogOnText="Login" LogOffText="Log off" ControlType="Botton"
LogOnUrl="/login.ashx" LogOffUrl="/logout.ashx" Alias="IdpLoginLogoff"
runat="server"></umbraco:Macro>
</?ASPNET_FORM>
<br/>
<?ASPNET_FORM>
<umbraco:Macro SamlAttributeName="urn:oid:0.9.2342.19200300.100.1.3" Comment="Test"
Alias="IdpLoginName" runat="server"></umbraco:Macro>

8/16

</?ASPNET_FORM>
<br/>
<?ASPNET_FORM>
<umbraco:Macro Alias="CurrentUmbracoUser" runat="server"></umbraco:Macro>
</?ASPNET_FORM>
</div>
<div id="subNavigation">
</div>
</asp:Content>

9. Click save
10. Go the Document Type section and click on Boost Homepage
11. On the Boost Homepage document type, find Allowed Templates and check
LoginLogout.
12. Click the Structure tab, and check LoginLogout
13. Click save.

7.5 Creating a login page

Do the following to create a login page
1. Log in to the Umbraco Administration Console.
2. Go to Content section
3. Right click on Boost Homepage and choose create.
Name the new page LoginLogoutPage and use the Document Type LoginLogout
4. Click create.
9/16

5. Click on the new LoginLogoutPage and make sure that the properties point to the
template LoginLogout.
6. Click Save and Publish.

7.6 Creating a default Member Group

Before protecting pages we must create Member Group, which users visiting the pages must be
a member of.
1. Log in to the Umbraco Administration Console.
2. Go to Member section
3. Right click on Member Group and choose create. Name the new Member Group
Partner.
4. Click create.

10/16

7.7 Protecting a page

We will now try to protect a page. We choose one of the Boost website pages.
1.
2.
3.
4.
5.
6.
7.
8.
9.

Log in to the Umbraco Administration Console.

Go to Content section
Right click on the page Go further and choose Public access.
Choose advanced mode
Select the Partner Member Group
Change the Login Page to LoginLogoutPage
Change the Error Page to LoginLogoutPage
Click Update and save
Right click on Content and republish entire site

11/16

7.8 Testing the login

We are now ready to test protection of pages and authentication by and Identity Provider
Go to the Boost Website (http://127.0.0.1/), and you should see something like this

12/16

No try to click on the link Go further which points to the page we protected earlier.

13/16

You will see that you get redirected to the login page. The page will display a login button
because we have not logged in yet.
Click on login and you will be redirected to the Identity Provider. After you have logged, you will
be sent back to the login page. The login page will now display some of the user information
received from the Identity Provider.

14/16

The login button will now display Log off. The first line under the button displays information
contained in the SAML assertion. In the template we configured this to be the OISAML Common
Name. The second line displays the login name of the Umbraco Member logged on to the site.

8 Changing the default behavior

The default behavior of this solution can be changed in a few ways, which will be shown in the
next two subsections, but first a little explanation about the authentication and authorization
process.
After IdP logon the user is redirected back to Umbraco. In Umbraco the
SamlMembershipProvider handles the user login.
Umbraco supports two different types of users, Members and Users. Members model a user
visiting a site, while a User models a backend CMS user. This solution is about Members.
The SamlMembershipProvider fetches the email address from the SAML assertion, and then
tries to find an existing Umbraco Member with this email. If a Member does not exist in
Umbraco, the Member is created but not persisted in the Umbraco database. If a Member does
exist, then the existing Umbraco Member object is used. Either way, the Member is logged in to
Umbraco.

15/16

The next step is authorization. The Member found by SamlMembershipProvider is attached to

an Umbraco MemberGroup (role) by the SamlRoleProvider.
First the SamlRoleProvider queries the IdP for role names/MemberGroups. This is done by a
standard SAML attribute query on a role attribute specified in web.config. If the IdP sends
back a MemberGroup name, the Member is attached to this MemberGroup, otherwise the
Member is attached to a default MemberGroup (specified in web.config).

8.1 Changing the default MemberGroup

The default MemberGroup can be changed this way:
1. Edit web.config in the root of your Umbraco website and locate the following
<setting name="DefaultMemberGroup" serializeAs="String">
<value>Partner</value>
</setting>
</IdPSamlUtilLib.Properties.Settings>

2. Change Partner with an existing Umbraco MemberGroup. MemberGroups can be

browsed and created in the Umbraco Administration Console.

8.2 Changing the attribute for role queries

The attribute used for role queries can be changed this way:
3. Edit web.config in the root of your Umbraco website and locate the following
<IdPSamlUtilLib.Properties.Settings>
<setting name="SamlRole" serializeAs="String">
<value>urn:oid:2.5.4.5</value>
</setting>

4. Change the value of the SamlRole with an attribute that can be used in the query to the
IdP.

9 References
[OIOSAML]

Danish SAML V2.0.5 profile

http://www.oiosaml.info/OIOWebSSOProfileV205-review.pdf

[OIOSAML.NET]

.NET reference implementation of OIOSAML 2.0.5

[Umbraco]

Open Source .NET Content Management System

http://www.umbraco.org/

16/16