Area: Optimizely CMS

Applies to versions: CMS 10

Other versions:

ARCHIVED This content is retired and no longer maintained. See the version selector for other versions of this topic.

Initial configuration

The web.config file

An ASP.NET web application has a web.config file that stores the required configurations. The web.config file is written in XML with specific tags having specific meanings. Episerver's web.config file is located in the website's wwwroot folder.

The web.config file in your project only contains changes and additions to the configuration found in the machine.config file, which is the base configuration for all applications on the machine on which the website is running. Important configurations stored in web.config are for database connection, handling of session state and error, and security.

The web.config file is separated into sections; each section contains settings for a specific part of the application, usually based on namespaces. For example, the <system.web> section stores the settings used by the classes in the System.Web namespace.

There are also other configuration files in an Episerver solution, for example for error logging and modules. See Configuration for more details about default configuration settings when you install Episerver.

Page types

Page types and templates are defined in code and stored in the database. Each page type consists of a number of properties, for example Title (MetaTitle) and Main body (MainBody). Available page types are displayed in admin view, and their properties can be modified from here. Administrators can for example change the tab under which a property is displayed, or the order in which properties are displayed for a page type.

During website initialization, the synchronization engine in Episerver will scan and validate available content types and properties created in code, or from the CMS admin view. See Content, content model and views.

Note: Page types can be created from the admin view, however this is not recommended, as these will not be strongly typed like the page types created from code.

Database configuration

An important setting in the web.config file is the connection string, which must contain the path to your server and database, and SQL login and password. Make sure your connection string also contains MultipleActiveRecordSet=true. It is enabled by default when you install a website from a scratch, but not if you are generating a connection string from the server explorer in Visual Studio.

<connectionStrings>
  <add name="EPiServerDB" 
    connectionString="Data Source=(LocalDb)\MSSQLLocalDB;AttachDbFilename=|DataDirectory|EPiServerDB_4bde2112.mdf;Initial Catalog=EPiServerDB_4bde2112;
                      Connection Timeout=60;Integrated Security=True;MultipleActiveResultSets=True" 
    providerName="System.Data.SqlClient" />
</connectionStrings>

The site URL and start page are configured in the admin view and stored in the database. This makes deployment easier and it is possible to add and remove sites dynamically without having to restart the application.

Configuring the start page

When you build a website from scratch, you will first create a set of page types and pages. To be able to browse to your site, you need to define a site URL and start page. The site URL acts as a default URL to the site when links are generated.

The start page is often a specific page type with unique properties, but any page type can be configured as start page. You configure the start page in the CMS admin view under Config > Manage Websites, by selecting a page in the page tree. The SiteUrl, StartPage, and host mapping settings are stored in the database.

See Create a starter project and Setting up multiple sites.

Authentication and authorization

The default authentication in Episerver is based on the ASP.NET built-in framework for role and membership providers. You can use built-in role/membership providers, or build your own providers. When implementing an Episerver solution, you will need to configure the membership/role providers to use the built-in groups and roles in Episerver.

Configuring role and membership providers

When you install an empty Episerver site, the Windows roles/membership provider is default. In the following we describe different role and membership provider options.

Built-in role/membership providers

The Multiplexing membership/role provider configuration allows you to use multiple providers at the same time. You can for example retrieve Windows users using the Windows provider, as well as manage users internally in CMS from the admin view, through the SQL Server role/membership provider. See Authentication and authorization.

Note: For an empty Episerver site, the Windows roles/membership provider and Multiplexing are enabled by default.

Active Directory membership provider

You can use Active Directory (AD) together with Episerver. The .NET Framework has an Active Directory membership provider which is used together with the Episerver CMS Active Directory role provider. See Configuring Active Directory membership provider.

ASP.NET Identity authentication

You can also configure your website to use ASP.NET Identity as authentication for managing users and roles. The ASP.NET Identity system includes profile support, and works with OWIN (Open Web Interface for .NET). With this you can add redirection-based log-ins to for example social media authentication providers. See Episerver AspNetIdentity.

Note: The Episerver sample site (Alloy templates) uses ASP.NET Identity for authentication.

Azure AD integration

If you are developing a website for the cloud, you may want to use Azure Active Directory (Azure AD) for directory and identity management. Episerver provides the possibility to use OpenID Connect to integrate with Azure AD. See Integrate Azure AD using OpenID Connect.

Configuring access rights

When setting access for the website, you need to configure the membership/role providers to use the built-in groups and roles in Episerver. If you have installed an empty Episerver site, the Windows Role and Membership provider is the default.

Episerver uses an extension of the Role concept called VirtualRoles. These are roles where the membership criteria is determined at runtime, and the membership is not stored in the database. Virtual roles are controlled by the <virtualRoles> configuration element in the <episerver.framework> section in web.config.

These virtual roles are delivered with Episerver:

Administrators. Needed to support localized Windows versions
Everyone. Provides visitor access to front-end
Authenticated.
Anonymous.
CmsAdmins . Mapped role, maps to WebAdmins, Administrators
CmsEditors. Mapped role, maps to WebEditors
Creator.
PackagingAdmins. Mapped role, maps to WebAdmins, Administrators
SearchAdmins. Mapped role, maps to WebAdmins, Administrators

You can also create your own virtual roles in code and register them in web.config. See Virtual roles.

WebAdmins and WebEditors are non-virtual Episerver-specific groups. They provide access to the CMS admin and edit views. The groups are predefined in Episerver, but they need to be added from the admin view to become available for usage, if you manage users in the CMS admin view, with the SQL Server role/membership provider.

When you have configured your role/membership providers, and added users to appropriate groups, you need to define what users can do where in the content structure. See Access rights in the Episerver User Guide.

Logging

When setting up a website, you will also want to configure logging for example for troubleshooting. You can use different logging tools. The Logging API shipped with Episerver is an abstraction for writing log messages from the system, and is used internally by Episerver assemblies for all logging, but can also be used by any third-party product or implementation. See Logging.

Next topic in Learning path

Upgrading Episerver

Do you find this information helpful? Please log in to provide feedback.

Last updated: Oct 19, 2021