Last updated: Jan 29 2019
Federated security lets you separate the service a client is accessing from the associated authentication and authorization procedures, for example, to enable collaboration across multiple systems, networks, and organizations. This topic describes how to configure federated security where Episerver acts as a claims-aware application.
This topic describes how to configure Episerver and does not cover basics in federated security or how to configure ADFS.
Note: Episerver Mail and Episerver Relate (using Common Framework), do not support federated security.
How it works
Federated security includes features such as Single-Sign-On (SSO) which allows a single user authentication process across multiple IT systems or even organizations. The protocol used is WS-Federation which is a specification supported by a wide range of federation software, such as Active Directory Federation Services (ADFS). Other federation specifications may require third-party software. In the documentation, the Relying party (RP) refers to the website running Episerver. The identity server/identity provider/federation server/Security Token Service(STS) is a third-party software, such as ADFS.
In short, when authentication is required (Episerver sends HTTP status code 401), a redirect sends the user to an identity provider which after authentication sends back claims about the user. You can use role claims to assign access rights to content or enable access to edit view. There is no user interface to manage roles and users synchronized from the identity provider; everything that is synchronized is visible for setting access rights by an editor.
To support assigning access rights to role claims or sending notifications to a user that is not logged in, users and roles are synchronized to the database. The synchronization of users and roles is triggered when an identity provider sends back claims about a user to Episerver. Users and groups are synchronized to custom Episerver tables in the database when a user is authenticated (see ISynchronizingUserService in the code example below). There is no background synchronization so for a role change to take affect the user have to login to the site again.
Windows Identity Foundation and OWIN
Federated security was originally implemented in Windows Identity Foundation (WIF), but is fully integrated into the core framework (as of .NET 4.5). Since the release of .NET 4.5, Microsoft has developed a new module called Microsoft.Owin.Security.WSFederation which simplifies configuration but builds on the same proven platform support. This module requires the OWIN framework, which contains abstractions to simplify building .NET middleware which need to run on multiple hosts. See OWIN and Episerver.
Limited multi-site support
The OWIN provider for WS Federation does not support multi-tenancy so each site must run in its own web application for authentication to work on all URLs (the WtRealm configuration specified in the example below cannot vary per request). The OWIN provider for OpenID connect can work with multiple URLs, see for example Integration with Azure Active Directory.
Configuring Episerver federated security
- The site must be able to access the identity server metadata URL.
- The site must be registered as a Relying Party Trust in the identity server. See the federation provider documentation for details.
- The identity provider must at least send a Name claim for each user but should also send Role claims to enable setting access righs in Episerver.
1. Disable Role and Membership Providers
Disable the built-in Role and Membership providers in web.config because they do not support federated security:
<authentication mode="None" />
Note: roleManager is disabled to prevent administrators from adding users to group membership in the admin view, because these users cannot log in with federated security in place.
2. Configure Episerver to support federation
Enable claims on virtual roles by setting the addClaims property. Also add the provider for security entities, which is used by the set access rights dialog and impersonating users. The SynchronizingRolesSecurityEntityProvider configured in the following example is using the SynchronizingUserService that is used in step 4.
<add name="SynchronizingProvider" type ="EPiServer.Security.SynchronizingRolesSecurityEntityProvider, EPiServer"/>
//existing virtual roles
3. Install NuGet packages
Open Package Manager in Visual Studio and install the following packages:
Update-Package Microsoft.IdentityModel.Protocol.Extensions -Safe
Note: Always use Microsoft.IdentityModel.Protocol.Extensions package version 1.0.2 or later, previous versions contain a critical bug that might cause threads to hang.
4. Configure WSFederation
The WSFederation package is configured from code rather from configuration files, which is a practice used for Owin-based middleware. See ASP.NET documentation for details about having different configuration in production and development.
Add the following code to the template project. Replace the MetadataAdress with the URL to the federation server and the Wtrealm must match exacly what is registrered in the federation server. See inline comments for more details.
public class Startup
const string LogoutUrl = "/util/logout.aspx";
public void Configuration(IAppBuilder app)
//Enable cookie authentication, used to store the claims between requests
AuthenticationType = WsFederationAuthenticationDefaults.AuthenticationType
//Enable federated authentication
//Trusted URL to federation server meta data
MetadataAddress = "https://devdc.dev.test/federationmetadata/2007-06/federationmetadata.xml",
//Value of Wtreal must *exactly* match what is configured in the federation server
Wtrealm = "https://localhost:44303/",
Notifications = new WsFederationAuthenticationNotifications()
RedirectToIdentityProvider = (ctx) =>
//To avoid a redirect loop to the federation server send 403 when user is authenticated but does not have access
if (ctx.OwinContext.Response.StatusCode == 401 && ctx.OwinContext.Authentication.User.Identity.IsAuthenticated)
ctx.OwinContext.Response.StatusCode = 403;
//XHR requests cannot handle redirects to a login screen, return 401
if (ctx.OwinContext.Response.StatusCode == 401 && ctx.OwinContext.Request.IsXhrRequest())
SecurityTokenValidated = (ctx) =>
//Ignore scheme/host name in redirect Uri to make sure a redirect to HTTPS does not redirect back to HTTP
var redirectUri = new Uri(ctx.AuthenticationTicket.Properties.RedirectUri, UriKind.RelativeOrAbsolute);
ctx.AuthenticationTicket.Properties.RedirectUri = redirectUri.PathAndQuery;
//Sync user and the roles to EPiServer in the background
//Add stage marker to make sure WsFederation runs on Authenticate (before URL Authorization and virtual roles)
//Remap logout to a federated logout
app.Map(LogoutUrl, map =>
//Tell antiforgery to use the name claim
AntiForgeryConfig.UniqueClaimTypeIdentifier = ClaimTypes.Name;
Generic error when redirected to identity provider
Identity providers, such as ADFS, do not display helpful error information on the login screen because that could compromise security. Check the event log of the identity provider to get details about the cause of an error.
The most common cause is that WtRealm in the code above does not exactly match the value entered as "Relying party identifiers" in the identity provider. Be aware that the value of the WtRealm is just an identifier and does not have to be the URL to the site. The URL that the identity provider posts back the claims to is in most cases another setting defined in the identity provider.
SSL related issues - The remote certificate is invalid according to the validation procedure
Both servers should be using SSL to the protect the communication for dev/test purposes. You can use self-signed certificates on both the web server and identity server. The web server must trust the certificate of the SSL connection to the identity server to access the metadata document defined in the code, when using self-signed certificates you can add the root certificate to the web server.
Value cannot be null. Parameter name: userName
You may not configure the identity provider to send a Name-claim. See the identity provider documentation to resolve this.
Login and logout from the Alloy templates
The Alloy templates use Forms Authentication in the Login/Logout link at the bottom the layout, to provide federated authentication change the Login link to send a 401 Access Denied, which triggers the WS Federation middleware. For Logout, use either /Util/Logout.aspx, which is remapped in the previous example, or call the same Signout method in the templates.
401.2 Access Denied when accessing edit mode instead of redirect to identity provider
If the project previously did not have an Owin startup class and optimizeCompilations was enabled, then sometimes the new code is not executed, the result is that you get a 401.2 Access Denied message instead of the redirect to the identity provider. Temporarily set optimizeCompilations in web.config to false to clear the cache.
401.2 Access Denied or 403 Forbidden when accessing edit mode after redirect to identity provider
When the identity provider does not send the required role claims, you will not get access to edit view. You could configure the identity provider to send the CmsAdmins role claim for a specific group of users.
Enable logging for Owin Security
You can view warning messages reported by Owin Security by adding the following configuration to web.config. These warning messages may contain information about errors in the WS-Federation communication protocol.
<add name="Microsoft.Owin.Security" value="Warning" />
<add name="file" type="System.Diagnostics.TextWriterTraceListener" initializeData="App_Data\OwinSecurity.log" />
<add name="file" />
Alloy: The login link redirects to "/Login.aspx"
The Alloy templates assume you are running forms authentication. You can remove the login link if not required, or implement custom login functionality. For example, create a controller or web forms page that sends a 401 Access Denied message for non-authenticated users.