Virtual Happy Hour this month, Jun 28, we'll be getting a sneak preview at our soon to launch SaaS CMS!

Try our conversational search powered by Generative AI!
Jun 16, 2010
(8 votes)

Converting EPiServer 6 to use claims-based authentication with WIF

Claims and federated security are increasingly big news in enterprise architectures that seek to implement single sign-on across different domains and technologies.

This article describes how to modify EPiServer 6 to delegate authentication to a claims issuer as well as discussing the issues that have to be overcome to make it all hang together.

What is claims-based security?

Claims-based security is a means of de-coupling the whole process of authentication from applications and services. It’s a different way of looking at authentication – instead of users and roles being defined from a central location, you have the notion of claims that can be provided by a number of issuers.

Claims are statements made about users – for example their name, group or privilege – and they provide a much more flexible way of describing identity than a role-based model. For example, some claims issuers support the idea of private user identities, so an application can authenticate users without having to know any personal details about them. Claims effectively de-couple roles from authorisation logic, allowing for more finely-grained permission schemas.

In claims-based security, applications are no longer responsible for authenticating users and this role is delegated to Issuers. These issuers are completely separate systems that authenticate users and make claims about them, passing the claims to applications in the form of a signed and trusted token. This approach allows for greater flexibility in security configuration, as an application will expect to receive claims about a user, but they don’t care where these claims actually come from.

This gives rise to the notion of federated security, where users can be authenticated across different domains, organisations and technologies. In the Windows world this is supported by Microsoft’s Active Directory Federation Services, which allows Windows 2008 Server to act as a federation server and share identity with other security realms via tokens through a trust relationship.

The Windows Identity Foundation provides a programming framework that supports issuing and consuming claims in applications. It provides a model that allows ASP.NET applications to be easily converted to use claims-based authentication through HTTP.

How does this impact EPiServer?

The main impact that claims-based security has on EPiServer is that you are delegating responsibility for authentication and authorisation entirely to another system. EPiServer will not have any role in creating, managing or authorising users, nor will it have any direct access to any store of users and roles. It just accepts claims that have been created by an issuer and acts on them accordingly.

The diagram below shows [in grossly simplistic terms] the current EPiServer security model which involves EPiServer interacting directly with an authentication store via providers:

EPiServer security model without claims

The diagram below illustrates [again, pretty simplistically] how EPiServer fits in to a claims-based model, where authentication takes place in a separate system that EPiServer does not have any direct access to:

EPiServer security with claims

From a technical point of view, adapting an EPiServer site to claims-based security involves several major changes:

  • Forms authentication is not used – it is turned off in web.config.
  • Authentication takes place much earlier in the HTTP pipeline – a couple of HTTP modules are added to authenticate a user at the start of the page request cycle and re-direct them to an issuer if they are not authenticated.
  • The membership and role providers do not have any role to play in authentication – everything is handled by an external claims issuer.

Setting up EPiServer to use a token service

Setting up an EPiServer 6 site for claims-based authentication with WIF only requires a few tweaks of the web.config file.

You will need a security token service to connect to and you can mock one up if you have installed the Windows Identity Foundation SDK - this article explains how to set up a simple security token service using Visual Studio 2008.

To make an EPiServer application claims aware, a new configuration section needs to be added to the configSections element:

  <section name="microsoft.identityModel" type="Microsoft.IdentityModel.Configuration.MicrosoftIdentityModelSection, Microsoft.IdentityModel, Version=, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>

Next, you need to switch off forms authentication and deny access to the site:

<authentication mode="None"/>
  <deny users="?"/>

The two HTTP modules that perform the authentication should be added to the system.webServer\modules section:

  <modules runAllManagedModulesForAllRequests="true">
    <add name="WSFederationAuthenticationModule" type="Microsoft.IdentityModel.Web.WSFederationAuthenticationModule, Microsoft.IdentityModel, Version=, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>
    <add name="SessionAuthenticationModule" type="Microsoft.IdentityModel.Web.SessionAuthenticationModule, Microsoft.IdentityModel, Version=, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>

Next, you configure the Identity Foundation itself by adding a microsoft.identityFramework element into the end of your configuration section:

      <add value="http://EPiServer6Site/"/>
      <wsFederation passiveRedirectEnabled="true" issuer="http://SecurityTokenService/" realm="http://EPiServer6Site/" requireHttps="false"/>
      <cookieHandler requireSsl="false"/>
        <claimType type="" optional="true"/>
        <claimType type="" optional="true"/>
    <issuerNameRegistry type="Microsoft.IdentityModel.Tokens.ConfigurationBasedIssuerNameRegistry, Microsoft.IdentityModel, Version=, Culture=neutral, PublicKeyToken=31bf3856ad364e35">
        <add thumbprint="575BC741AAE8F063DD76615EE8152879B3C0F5EA" name="http://SecurityTokenService/"/>

Finally, just to demonstrate that claims are really driving authentication, you can disable the membership and role providers by replacing the membership and role declarations in the system.web section with the following:

  <roleManager enabled="false">

This is all you need to do to get EPiServer up and running with claims. When you try to access your site you will be re-directed to your security token service website where you will submit your credentials. Once the security token service has logged you in then you’re re-directed back to EPiServer with a set of claims.

Inevitably, there are some catches…

On the surface, things work quite smoothly as claims authentication provides an identity object that implements the IPrincipal interface, so the EPiServer API seems to play nicely with claims-based credentials.

However, things get more tricky with the EPiServer UI, mainly because EPiServer expects direct access to the authentication store through the role and membership APIs, making a number of direct calls to them. Once role and membership providers have been taken out of the equation then a fair amount of the functionality in the EPiServer UI either becomes redundant or just plain fails.

The details of how you would solve these UI issues depend very much on the nature and type of claims that your are receiving from your issuer, but there are two main issues to solve.

Firstly, when assigning access right to content in EPiServer, a call is made to a role provider for a list of all the currently available roles. If you want to be able to assign access rights for content and features to roles that are returned by claims then you will need to create a custom role provider for EPiServer that supplies a list of all the valid roles that your claims issuer is likely to use.

The exact implementation of this custom role provider would depend on the number of roles, the source of roles and the frequency with which they are likely to change. Whatever the approach, there is no getting away from having to create some kind of custom role provider to serve a valid list of roles to the EPiServer UI.

The second issue is that EPiServer exposes a lot of functionality that is no longer available in a claims-aware application – e.g. creating and managing users and groups. In some cases – such as the log-out button – this functionality will just fail, while in other cases it will fail with some pretty ugly exceptions.

Again, the solution to this depends on circumstances and your users’ tolerance for a slightly flakey UI. You can resolve this issue either by educating your users (difficult, but straightforward), customising the EPiServer UI (clever, but risky) or by creating “dummy” custom providers that return empty results for every significant method (dirty, but effective).


Although EPiServer does not provide direct support for claims-based security, the fact that its security model is pluggable and closely aligned to ASP.NET’s standard design patterns means that, with a bit of tweaking, you can get an EPiServer-based site to be claims-aware.

However, the devil is in the detail – or the EPiServer UI – and you will probably need to do some work with custom role and membership providers to deliver a solution. The exact details of these would depend on the nature of the claims that you are receiving and the authentication store that they are coming from.

Jun 16, 2010


Sep 21, 2010 10:33 AM

Wonderful, thanks for sharing your knowledge on this area. I was a bit surprised to find that Windows Identity Foundation does not leverage role/membership providers.

Sep 21, 2010 10:33 AM

Thank you for a great article! We will see if we can fully support WIF for the next major CMS release - I'll make no promises but I will put it on the wishlist.
Apart from the issues that you already have discovered, there will be a major problem with scheduled jobs/workflows since these are executed outside the HTTP context and no claims about the user are available. In this case we would most likely need a role provider to query for role memberships to allow for access checks. It will be an interesting challenge...

henriknystrom Sep 21, 2010 10:33 AM

Really good post Ben, I believe that there is a lot to learn in this area for most people!
It also sounds good that you will be looking into claim based security in EPiServer Magnus!

I guess that the problems that surfaces in the EPiServer UI are really due to that the traditional security providers is actually used for two separate use cases, the claims based approach takes care of the authentication/authorization/profile task but not the member/role management.
And since the application in a Claims based architecture should be separated from the authentication provider it shouldn't be the responsibility of the application either, which in turn can explain why the role/membership model was dropped.

I hope that this is just a first step to further discussions in this area and I hope to contribute further in the future, just need to get a bit organized first!

Knut Hamang
Knut Hamang Sep 21, 2010 10:33 AM

Hi Ben, have you actually tried to write any of the suggested providers and see how it's working ?

Sep 2, 2014 11:00 AM

Nice article. Does anyone know if EPiServer 7.5 fully support WIF now?


Søren Raarup
Søren Raarup Sep 17, 2014 07:25 AM

Wow - very nice article to get started on, Ben. Thanks a lot.

For local development, I am using EmbeddedSts
If you are using IIS (opposed to IIS Express), then you also need to add EmbeddedSts as one of the assemblies:

Next I want to make Role provider like here:

Any other suggestions, anyone?

Please login to comment.
Latest blogs
Copying property values part 2

After publishing my last article about copying property values to other language versions, I received constructive feedback on how could I change t...

Grzegorz Wiecheć | Jun 18, 2024 | Syndicated blog

Enhancing online shopping through Optimizely's personalized product recommendations

In this blog, I have summarized my experience of using and learning product recommendation feature of Optimizely Personalization Artificial...

Hetaxi | Jun 18, 2024

New Series: Building a .NET Core headless site on Optimizely Graph and SaaS CMS

Welcome to this new multi-post series where you can follow along as I indulge in yet another crazy experiment: Can we make our beloved Alloy site r...

Allan Thraen | Jun 14, 2024 | Syndicated blog

Inspect In Index is finally back

EPiCode.InspectInIndex was released 9 years ago . The Search and Navigation addon is now finally upgraded to support Optimizely CMS 12....

Haakon Peder Haugsten | Jun 14, 2024