Configurable Authentication Provider Chain

Product version:

EPiServer CMS 4.62

Document version:

1.0

Document creation date:

05-06-2006

Document last saved:

04-10-2007

Purpose

The authentication system in EPiServer CMS is configurable with the possibility to add your own authentication providers. This technical note outlines the authentication providers that are provided with EPiServer CMS and explains, among other things, authentication provider configuration from web.config.



Table of Contents

Introduction

Authentication Providers in EPiServer CMS


    - CacheAuthenticationProvider
    - LdapAuthenticationProvider
    - WindowsAuthenticationProvider
    - DatabaseAuthenticationProvider
    - RemoteAuthenticationProvider
    - ClearTrustAuthenticationProvider

Default Provider Configuration

Configure Authentication Providers from web.config
 
Add Your Own Authentication Provider
 
Configuring EPiServer CMS for RSA ClearTrust

Introduction

The authentication system in EPiServer CMS is configurable with the possibility to add your own authentication providers. From EPiServer CMS 4.41, it is also possible to remove existing authentication handlers added by EPiServer CMS or to add your own authentication provider anywhere but to the end of the existing chain as defined by EPiServer CMS.

Note If you do not modify web.config or override the SetupAuthenticationProviders method in global.asax.cs, the authentication system will continue to work exactly as before.

Authentication Providers in EPiServer CMS

This is a description of the authentication providers that are included with EPiServer CMS.

CacheAuthenticationProvider

Type: EPiServer.Security.CacheAuthenticationProvider

Method: CacheAuthentication

By default the first authentication provider in the chain. Will try to authenticate the incoming request against a cached UnifiedPrincipal. Will significantly improve performance if you have a ”slow” authentication provider (for example LdapAuthenticationProvider).

LdapAuthenticationProvider

Type: EPiServer.Security.LdapAuthenticationProvider

Method: LdapAuthentication

Handles authentication against an LDAP source. Requires that the EPsLdap... configuration parameters are set to authenticate against an LDAP source. Currently supports ActiveDirectory and eDirectory.

WindowsAuthenticationProvider

Type: EPiServer.Security.WindowsAuthenticationProvider

Method: WindowsAuthentication

Authenticate the given credentials as a Windows user. Will handle local accounts as well as domain and ActiveDirectory user accounts.

DatabaseAuthenticationProvider

Type: EPiServer.Security.DatabaseAuthenticationProvider

Method: DatabaseAuthentication

Authenticate against built-in user tables in the EPiServer CMS database.

RemoteAuthenticationProvider

Type: EPiServer.Security.RemoteAuthenticationProvider

Method: RemoteAuthentication

Authenticate against a remote EPiServer CMS. Requires two EPiServer CMS installations configured for a front end-back end scenario with .NET Remoting as the communication mechanism.

ClearTrustAuthenticationProvider

Type: EPiServer.Security.ClearTrustAuthenticationProvider

Method: ClearTrustAuthentication

Authenticate against HTTP header information provided by RSA ”Web Agent for IIS”, i.e. integrate with RSA ClearTrust for an enterprise single sign-on solution. Only present in EPiServer CMS 4.41 and later versions.

Note If you enable this provider, you should also change the default login page to fully enable single sign-on. See the ”Configuring EPiServer CMS for RSA ClearTrust” chapter for further information.

Default Provider Configuration

The default provider sequence is set up as follows:

  1. CacheAuthenticationProvider
  2. LdapAuthenticationProvider (only added if the required EPsLdap... parameters are set in web.config)
  3. WindowsAuthenticationProvider
  4. DatabaseAuthenticationProvider

Configure Authentication Providers from web.config

It is possible to set up exactly which authentication providers EPiServer CMS should use from the web.config file. To accomplish this you need to set up web.config as specified below:

<?xml version="1.0" encoding="utf-8" ?>

<configuration>

       <configSections>

              <sectionGroup name="episerver">

                    <section name="Security" allowDefinition="MachineToApplication" allowLocation="false" type="EPiServer.Security.SecurityConfigurationHandler,EPiServer" />

              </sectionGroup>

       </configSections>

       <episerver>

              <Security>

                    <authenticationProvider type="EPiServer.Security.CacheAuthenticationProvider, EPiServer" method="CacheAuthentication" />

                    <authenticationProvider type="EPiServer.Security.WindowsAuthenticationProvider, EPiServer" method="WindowsAuthentication" />

                    <authenticationProvider type="EPiServer.Security.DatabaseAuthenticationProvider, EPiServer" method="DatabaseAuthentication" />

              </Security>

       </episerver>

.

.

.

This example will set up the default provider chain with support for Windows users as well as users in the EPiServer CMS database. To use any of the built-in providers in EPiServer CMS, add an <authenticationProvider> tag in the Security section, and fill in the values from Type and Method (see the list under the "Authentication Providers in EPiServer CMS" chapter) for the type and method attributes.

Add Your Own Authentication Provider

It is also possible to add your own authentication providers in the provider chain in web.config, as in the example above. Your authentication provider needs to conform to some requirements.

  1. Your authentication class must provide an authentication method with the signature
    public static void Method(object sender, AuthenticationEventArgs e)
    The method name should of course be something more meaningful than Method.
  2. The authentication method should follow this basic skeleton:

public static void Method(object sender, AuthenticationEventArgs e)

{

       // If user name is "john" you will never be authenticated,

       // regardless of what other providers (executed before or

       // after this provider) says. Setting IsDenied makes it

       // possible to filter out banned users for example.

       if (e.Username == "john")

              e.IsDenied = true;

 

       // If another provider has already authenticated this user,

       // do nothing. Note that all authentication providers will

       // always be called in response to an authentication event,

       // this is due to the nature of events in the .NET environment.

       if (e.IsHandled)

              return;

 

       // Very simple authentication - here you should implement

       // your own lookup and check credentials against your

       // user store. Several out-of-band techniques can be used

       // if the information in AuthenticationEventArgs is

       // insufficient - primarily looking at HttpContext.Current

       // gives you the possibility to extract any information

       // about the current Http request.

       if (e.Username != "peter" || e.Password != "expert")

              return;

 

       // A request is authenticated by setting e.Principal to an

       // object instance that implements the IPrincipal interface.

       // Since the principal also carries the roles of the

       // principal it is usually a good idea to do the

       // authorization at the same time for performance reasons.

       UnifiedPrincipal up = new UnifiedPrincipal(

              new GenericPrincipal(

              new GenericIdentity( e.Username, "My Authentication Type" ),

              new string[] { "Administrators" } ) );

 

       // If you want to cache the principal to speed up

       // authentication for subsequent requests, the

       // following code sequence is needed.

       up.Password = e.Password;

       up.AddToCache();

 

       // Return the principal to indicate that authentication

       // was successful

       e.Principal = up;

}

Assuming that the fully qualified class name is ”development.MyAuthentication” and the code is placed in the EpiServerSample assembly, you can set up your provider with the following entries in web.config:

<?xml version="1.0" encoding="utf-8" ?>

<configuration>

       <configSections>

              <sectionGroup name="episerver">

                    <section name="Security" allowDefinition="MachineToApplication" allowLocation="false" type="EPiServer.Security.SecurityConfigurationHandler,EPiServer" />

              </sectionGroup>

       </configSections>

       <episerver>

              <Security>

                    <authenticationProvider type="EPiServer.Security.CacheAuthenticationProvider, EPiServer" method="CacheAuthentication" />

                    <authenticationProvider type="EPiServer development.MyAuthentication, EPiServerSample" method="Method" />

              </Security>

       </episerver>

.

.

.

Note It is recommended to have CacheAuthenticationProvider as the first provider entry to make the principal cache work properly.


Configuring EPiServer CMS for RSA ClearTrust

RSA ClearTrust (see http://www.rsasecurity.com/ for more information) is a Web access management product that can be used to enable Single Sign-On capabilities for disparate Web applications. EPiServer CMS supports simple integration with ClearTrust from version 4.41.

Set up ClearTrust for your Web server using the ClearTrust installation instructions for detailed instructions. You then need to import the groups that you want to use for setting access rights in EPiServer CMS. If using ClearTrust with Microsoft ActiveDirectory, you can simply import groups from Admin mode / Administer groups / New group. If using an LDAP source, you must first configure EPiServer CMS for LDAP authentication and import groups / OU:s from the LDAP server.

When you enable ClearTrust support, it is recommended that you only add CacheAuthenticationProvider and the ClearTrustAuthenticationProvider, i.e.

<?xml version="1.0" encoding="utf-8" ?>

<configuration>

       <configSections>

              <sectionGroup name="episerver">

                    <section name="Security" allowDefinition="MachineToApplication" allowLocation="false" type="EPiServer.Security.SecurityConfigurationHandler,EPiServer" />

              </sectionGroup>

       </configSections>

       <episerver>

              <Security>

                    <authenticationProvider type="EPiServer.Security.CacheAuthenticationProvider, EPiServer" method="CacheAuthentication" />

                    <authenticationProvider type="EPiServer.Security.ClearTrustAuthenticationProvider, EPiServer" method="ClearTrustAuthentication"/>

              </Security>

       </episerver>

.     

.

.

You should also use forms login and the special file CTLogin.aspx, i.e. change the <authentication> section of web.config to:

<authentication mode="Forms">

       <forms name=".EPiServerLogin" loginUrl="Util/CTLogin.aspx" />

</authentication>

The new CTLogin.aspx will check for authentication information from the ClearTrust agent before displaying the login form. Otherwise it will work just like the regular Login.aspx.

Important! You should not enable the ClearTrustAuthenticationProvider unless you have a running ClearTrust agent on your Web server. This could otherwise be a security issue, as the client would simply need to send a specific set of HTTP headers to get access to your EPiServer installation.