Episerver authentication

You can configure ImageVault to use the same user catalog as configured in Episerver. You then manage all users and roles in your Episerver instance.

Depending on how you configure the authentication in Episerver, you need to configure ImageVault authentication accordingly.

Different types of Episerver user management

Membership providers

If you are using forms/windows authentication and utilizes old style Membership/Role providers then you can use the ImageVault proxy providers for Memberhip/role providers. Just follow the instructions below to set it up.

AspNetIdentity

Optimizely CMS 12

Note

The ImageVault.EPiServer.AspNetIdentity is not supported for CMS 12 so be sure to remove this package when upgrading to CMS 12.

Instructions for how to configure the ImageVault plugin in Optimizely for AspNetIdentity can be found in the installation instructions.

EPiServer CMS 10-11

If your Episerver site uses the newer form of user management, AspNetIdentity, then you need to need to include the ImageVault.EPiServer.AspNetIdentity nuget package and add the follwing row in your Startup configuration.

app.ActivateImageVaultIdentityProxy<ApplicationUser>();

This row needs to be added just after the call to AddCmsAspNetIdentity, see example below.

public void Configuration(IAppBuilder app)
{
    // Add CMS integration for ASP.NET Identity
    app.AddCmsAspNetIdentity<ApplicationUser>();
    // Add ImageVault identity support for proxy endpoint
    app.ActivateImageVaultIdentityProxy<ApplicationUser>(); 
    ...
}

After that is done, follow the instructions below to set it up.

Configure Episerver

ImageVault needs to be able to communicate with Episerver using the imagevaultidentity handler. This is available when you install the ImageVault.Episerver.UI nuget package in your Episerver project.

As default it is only accessible when called from the same server so if your ImageVault is running on the same server instance as the Episerver instance, then no further configuration is needed.

If you are hosting Episerver and ImageVault in the cloud or on separate physical machines, you need to configure a secret that the ImageVault instance need to supply in order to communicate with the handler. This is done by setting the ImageVault_IdentityHandler_AuthKey app setting in web.config.

<appSettings>
    <add key="ImageVault_IdentityHandler_AuthKey" value="superPassword"/>
</appSettings>

Also make sure that the imagevaultidentity path on the Episerver site allows anonymous access. This is added to the web.config by the ImageVault.Episerver.UI and should look like below.

<location path="imagevaultidentity">
    <system.web>
        <authorization>
            <allow users="?" />
        </authorization>
    </system.web>
</location>

Configure ImageVault

To enable ImageVault to use the same user catalog as Episerver you need to configure it to use the IdentityProxy membership and role provider.

On each provider you need to specify the authKey and serviceUri attributes where authKey contains the same authkey as specified in the Episerver app settings above and serviceUri points to the url of the episerver site with the /imagevaultidentity/ suffix.

<system.web>
    <authentication mode="None" />
    <membership defaultProvider="IdentityProxyMembershipProvider">
        <providers>
            <clear />
            <add name="IdentityProxyMembershipProvider"                 
                 type="ImageVault.UI.Mvc.Security.IdentityProxyMembershipProvider, ImageVault.UI.Mvc" 
                 authKey="superPassword" 
                 serviceUri="https://myepiserver.com/imagevaultidentity/"/>
        </providers>
    </membership>
    <roleManager defaultProvider="IdentityProxyRoleProvider" enabled="true">
        <providers>
            <clear />
            <add name="IdentityProxyRoleProvider"          
                 type="ImageVault.UI.Mvc.Security.IdentityProxyRoleProvider, ImageVault.UI.Mvc" 
                 authKey="superPassword"
                 serviceUri="https://myepiserver.com/imagevaultidentity/"/>
        </providers>
    </roleManager>
</system.web>

IdentityProxy configuration

Here follows a list of all attributes that can be applied to both the IdentityProxyMembershipProvider and the IdentityProxyRoleProvider as described below.

authKey

The authentication key to use when communicating with the imagevaultidentity handler. Must match the value set in the Episerver web.config.

serviceUri

You can set the uri to the imagevault identity service manually by adding the serviceUri attribute. The uri must end with a / but can be either absolute or relative. If relative it will be converted to an absoute uri using the incoming request URI as base.

<add name="IdentityProxyRoleProvider" 
     type="ImageVault.UI.Mvc.Security.IdentityProxyRoleProvider, ImageVault.UI.Mvc" 
     serviceUri="http://www.site.com/imagevaultidentity/"
     />
Note

If omitted, the relative path ../imagevaultidentity/ will be used.

cacheDuration

Each lookup to the imagevaultidentity service is cached for a period of time (default 10 min). You can control this by setting the cacheDuration attribute to the number of minutes that the lookup result should be cached. Set to 0 to disable the cache.

<add name="IdentityProxyRoleProvider" 
     type="ImageVault.UI.Mvc.Security.IdentityProxyRoleProvider, ImageVault.UI.Mvc" 
     cacheDuration="3"
     />

Single sign on

Note

Single sign on using forms/EPiServer authentication and the following instructions is only supported on CMS 11 or earlier (it requires .net framework). Even then, this is a workaround and a more recommended way is to use some kind of federated authentication.

If you are using forms authentication SSO is achieved by checking the following list.

  • Both sites need to have a url with a common domain name. Like a.site.com and b.site.com or site.com.

  • The forms cookie needs to have the domain set to the common domain name.

    If you are running Episerver on site.com and ImageVault on iv.site.com, then use the domain name site.com.

  • Authentication in ImageVault web.config must be set to mode="Forms" for it to accept the cookie attributes.

  • The forms cookie need to have the same name on both sites.

  • Setting the same machine key in Episerver and ImageVault web.config.

  • You also need to make sure that Episerver and ImageVault are using the same Encryption compability mode

For ImageVault you configure the forms cookie using the example below (substitute the values for domain and name with your actual values).

<system.web>
    <authentication mode="Forms">
        <forms domain="site.com" name=".EPiServerLogin2" loginUrl="account/login" timeout="120" />
    </authentication>
</system.web>
Note

Observe that you need to set authentication mode="Forms" for ImageVault to accept the cookie attributes.

Note

a tip is that if you change the domain value for a cookie, change its name as well, since it will force the client to login again and set the correct domain for the cookie.

In Episerver you only modify the domain and name properties of the <form> element.

Troubleshooting

Encryption compability mode

Make sure that Episerver and ImageVault are using the same encryption compability mode.

<machineKey compatibilityMode="Framework45" />

A mismatch can occur if one site declares running on targetFramework 4.5 and the other is using an earlier version.

If this occur, the login won't work and you will repetedly be faced with the login page since the authentication cookie cannot be decrypted.

To set the encryption mode, you can either set the targetFramework to 4.5. This is controlled in the system.web/httpRuntime.

<system.web>
    <httpRuntime targetFramework="4.5" />

Read more about the targetFramework and what impact it has in the following article. https://blogs.msdn.microsoft.com/webdev/2012/11/19/all-about-httpruntime-targetframework/