Area: Optimizely CMS
Applies to versions: Latest

Initial configuration

Recommended reading 

This topic describes some typical initial configurations you need to consider when setting up an Optimizely solution. Configuration can be done in multiple locations in Optimizely, depending on the type of settings. Typical examples are configuration files such as web.config, page types and templates in code and connection strings in the database.

In this topic

We assume here that you have installed an empty CMS site and added a page type, as described in Create a starter project.

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. Optimizely'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 Optimizely solution, for example for error logging and modules. See Configuration for more details about default configuration settings when you install Optimizely. 

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 Optimizely 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.

  <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" />

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 Optimizely 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 Optimizely solution, you will need to configure the membership/role providers to use the built-in groups and roles in Optimizely.

Configuring role and membership providers

When you install an empty Optimizely 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 Optimizely site, the Windows roles/membership provider and Multiplexing are enabled by default. 

Active Directory membership provider

You can use Active Directory (AD) together with Optimizely. The .NET Framework has an Active Directory membership provider which is used together with the Optimizely 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 Optimizely AspNetIdentity.

Note: The Optimizely 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. Optimizely 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 Optimizely. If you have installed an empty Optimizely site, the Windows Role and Membership provider is the default.

Optimizely 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 Optimizely:

  • 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 Optimizely-specific groups. They provide access to the CMS admin and edit views. The groups are predefined in Optimizely, 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 Optimizely User Guide.


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 Optimizely is an abstraction for writing log messages from the system, and is used internally by Optimizely assemblies for all logging, but can also be used by any third-party product or implementation. See Logging.

Related topics

Next topic in Learning path

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

Last updated: Feb 23, 2018

Recommended reading