In web applications, including Episerver applications, leveraging cache properly is crucial to the performance of your site. As a developer, you will have a number of different types of cache available to you. They all have different purposes, lifecycles and storage locations so it's best to know how and when to use them.

## What can be cached In Episerver?
In short, anything can be cached. Cache, although fast, is usually limited by cost or space available.

Commonly cached data:

Data needing to be fetched often from a slower data source
The result of calculations or other operations on a set of data
Static files
Markup/Responses to the end-user
It should be used to store data that would take a significant amount of time/resources for the application to generate when needed and data that does not change very often.

## Where can it be cached?
There's a possibility of caching data at nearly every piece of infrastructure in an environment. Let's take a look at a typical .NET application hosted in Azure:

![cache types overview](//images.ctfassets.net/advboymm7uww/3udJZciZXZ02hEyWDU6pHl/c3f954761ba6d53089f9e3f901d3270b/cache-types-overview.png)

Although the diagram I used above is specific to Azure and includes Redis for Azure, there are many ways of doing the same thing. Information can be stored at any of these places in the environment, including:

1. In a persistent cache layer (shown as Redis for Azure)
2. Within the web application itself (shown as Azure Web App)
3. On the Content Delivery Network (shown as Azure CDN)
4. In the website visitor's browser

## What Are The Types of Caching in Episerver?
Let's look at some common types of cache (this definitely isn't a full list):

1. Output Caching / Request Caching
2. File Caching
3. Object Caching

### Output Cache / Request Cache
An output cache stores the entire result of a request in cache. If you're browsing a website, output cache can store the entire HTML sent to your browser to make it extremely fast to respond if you visit the same page again.

#### Pros
1. Extremely fast
2. Saves processing time
#### Cons
1. Needs to be well-configured
2. Output cache prevents personalizing in real-time without separate calls post-request

### File Caching In Episerver
Some files hosted by the application may not change very often. For these files, you can set response headers when they're requested that will let all downstream cache storage locations: if they can cache it, and if so, for how long before needing to fetch it from the server again.

#### Pros
1. Can provide near-zero latency loading static files
2. Prevents repeated requests for static files to the server
3. Less requests to the server = less servers needed to handle the same amount of web traffic
#### Cons
1. Can lead to inconsistent end-user experiences by using old copies of files/data
2. Cached files do not live on the server, cannot be managed/purged/refreshed until they expire (or cleared intentionally)

### Object Caching In Episerver
Last (that I'll write about) but definitely not least is object caching. Object caching can store any type of of objects, allowing for the most versatility. Object cache can have any number of implementations, but it common two are:

1. Memory Cache
2. Persistent Cache

Each of these types of caching have their own pros and cons and can be used in combination with eachother. So how are they different?

#### Memory Cache
The most common layer of cache, memory cache. Exactly as it sounds, you can leverage the memory that your application runs with to store any data you wish. There's a number of ways to access memory cache, the most straightforward of which is either IMemoryCache or the MemoryCache class in System.Runtime.Caching.

#### Pros
1. Very fast
2. Extremely flexible

#### Cons
1. Tied to your application lifecycle: If the application is restarted, memory cache is cleared. Needs to be rebuilt. If heavy cache is used, site startups can be slow until cache is built.
2. App pool specific: If you host many instances of your site to scale, use Episerver DXC or run with autoscale in Azure, each memory cache is independent of the others

#### Persistent Cache
In direct response to Memory Cache's cons, persistent cache addresses the volatility and independence of direct memory cache. Persistent caches are normally backed by memory cache in some way. For example, Redis is "an in-memory data structure store, used as a database, cache and message broker" and "has built-in replication, transactions and different levels of on-disk persistence". It's a framework on top of a combination of memory cache and disk cache that provides for a persistent, shared, fast cache.

### Memory Cache and Episerver
Memory cache is the most common type of cache available to an Episerver application. If you are on Azure or DXC, depending on the amount of traffic to your website, you could be scaling up the amount of instances to support the load. Each of these instances is it's own virtual environment and therefore each one has it's own memory cache. A common issue with memory cache in a scaled environment like that is where one instance removes an item from it's memory cache, but it still exists in the other instances' cache. When caches get out of sync it's possible that two visitors hitting two different instances of your site are shown different data and debugging this can be a painful experience.

Persistent cache, alike Redis, is the best solution for this. On Episerver DXC-Standard, Redis Cache is not included, but I believe it is an addon. Without Redis or another persistent cache offering, you need to take measures to ensure your instance caches stay in line with eachother. Episerver has provided an interface called [ISynchronizedObjectInstanceCache](https://world.episerver.com/documentation/Items/Developers-Guide/Episerver-CMS/9/Caching/Object-caching/). This cache, as the name describes, attempts to synchronize the object cache of running instances.

This synchronization library is built to notify the other running instances of cache removal events for them to also remove from their cache and hopefully prevent them from containing invalid data. Let's look at the code quickly, it's short:

Code from ISynchronizedObjectInstanceCache
```csharp
public void Insert(string key, object value, CacheEvictionPolicy evictionPolicy)
{
     this._localCache.Insert(key, value, evictionPolicy);
}

public object Get(string key)
{
     return this._localCache.Get(key);
}

public void Remove(string key)
{
     this.RemoveLocal(key);
     this.RemoveRemote(key);
}
```
Based on the code, we see that *ISynchronizedObjectInstanceCache* does __not__ synchronize insertions, only removals. It will only help keep caches valid by removal, but __not__ identical. Since it only inserts cache values locally it means that each app instance will need to build it's own cache, and will need to do so each time the application starts up or recycles.

## Wrapping Up
I highly recommend leveraging cache where you are able to. If you are using Episerver DXC (or another .NET web application in a scaled environment), you should look into cache synchronization options to keep your cache valid on all instances. If you're able to leverage it, you could greatly benefit from a persistent caching option alike Redis. 

Please leave a comment below if you found any of this helpful or find a mistake, I'd greatly appreciate it!

If you heavily use cache and your application sees poorer performance when cache is not ready, I strongly recommend you consider a persistent option alike Redis.

Cache can greatly improve the responsiveness of your website, especially when running in the cloud. On Episerver? On Episerver DXC? Running a .NET site in Azure? This might be helpful for you!

Two devs sitting in a conference room in front of a monitor

two-devs-in-conference-room

Episerver website running slow? Memory usage too high? Long warmup times? Need to restart your site often? Here's the different types of cache and how to leverage them to speed up your website in Azure or on Episerver DXC.

Using Cache Effectively on Episerver

Over the past years working with Episerver, a common conversation I've found myself in is where someone is having trouble reliably deploying their application. 

## Common Issues With Episerver Azure Deployments
It can be represented in a number of ways, but it usually comes down to:

1. Long Deployment Routines
2. Unexpected Behavior
3. Slow Deployment Cycles
4. Interruption in Availbility to end-user

### Long Deployment Routines
If you've gone through the launch of a site before, there's often a larger team sitting on a call as the deployment or final adjustments are made to direct traffic to their newly launched website or microsite, but that should be a one-time occurrence. Deployments to add new features or improve existing user experience should be as painless and as "set it and forget it" as possible. Normally, long deployment routines always come down to some kind of human interaction needed in a deployment routine.

### Unexpected Behavior
Let's just start by saying that bugs are unavoidable. They ARE going to happen, what matters is your ability to catch them during testing and respond quickly to those that slip through testing. If you update your application and see inconsistent behavior either in parts of the application you didn't intend to change or even the new functionality you built is working differently once it's deployed and live, it can be tough to wonder what went wrong. There's nothing more frustrating than wondering why an issue arises after it was tested and worked before it was deployed.

### Slow Deployment Cycles
A slow development and deployment cycle can leave users wondering when a new feature or an issue they're seeing is going to be release or fixed. You need to be able to deploy often to make small adjustments and tweaks to make the application better, or you'll risk your users or stakeholders getting frustrated by seemingly very little being done to resolve their needs and concerns.

![page offline error](//images.ctfassets.net/advboymm7uww/BgFbMyMEMpFLHP2UcHEmp/2225d123c5b9e073d2cf0964536a152c/page-offline-error.png)

### Interruption in Availability
If during a deployment your application is offline, your business is impacted. If you sell anything (even not directly on your website), the sale or purchasing decision can be impacted by this interruption by leaving a bad impression on the user who may see some kind of broken experience while researching the product.

## Common Causes
Almost all of the issues above come down to a common set of causes:

1. Source Control Strategy
2. Code Quality / Confidence
3. Inaccurate / Incomplete Testing
4. Deployment Strategy / Process

If you're having trouble with any of these issues, feel free to reach out via email. If you're willing to take on the challenge, here's what you need to know.

Let's take a look at each of these briefly and talk about how you can avoid them.

![pull request screenshot](//images.ctfassets.net/advboymm7uww/7fEaYMfknp7AfADPF3GlPV/2b7c5dcede6656e9ee2bfb839c66c5fe/pull-request-mockup.png)

### Source Control Strategy
Starting at the very core, the code. Before even talking about the actual quality of the code, __how__ and __where__ you are changing your code makes a difference. Your application can have a varying number of developers and stakeholders working on a variety of features and adjustments that need to fit together when they're finished.

Let's invision for a moment a small application team and some common scenarios:

- An application's stakeholders have decided to work on a new large feature for the application and after working with a small (2-3 developers) development team have found it will take two months to complete.
- Everything can't be put on hold while the feature is developed, so during this time, the stakeholders also want some updates to existing features/user experience.
- The development team needs to work together on the new feature and contribute to the smaller changes __*and*__ be prepared that they'll need to get the smaller changes out to the world before the bigger feature is complete.
- During this time, stakeholders want to review progress towards the larger feature alongside testing the smaller changes.

The development team needs to properly separate code for the larger feature(s) from the smaller adjustments and have the ability to create a deployment that combines one or many of the features without significant effort. If that isn't done, it's possible that unintended behavior pops up due to code conflicts or unfinished development being included in a deployment accidentlaly before being finalized.

I'll dive into source control strategies my team has used on projects recently on another blog post in the near future.

### Code Quality / Confidence
Looking again at your application's code, aside from glaringly obvious bugs that should be caught during testing, there is a possibility for small bugs/quirks/conflicts to happen even if the code was intended to be released. Lack of confidence in the code being deployed can have a significant effect on the ability to rapidly respond to issues if they arise once deployments. This is only compounded again for larger teams where developers can work independently on tasks and all of that code is combined into a single application. So how do you combat this? There's a number of ways, but the best option I've found, by far, is code reviews.

![code review screenshot](//images.ctfassets.net/advboymm7uww/4qenIhwtdCppXNRK49Jc0b/3522e16b5bcef00d912ffab4abd97b78/code-review-mockup.png)

#### Code Reviews
Reviewing code can significantly reduce issues in code. It's even more effective when the person reviewing code has not written it as a fresh pair of eyes or different perspective can find issues. Even more effective is having code reviewed by someone with a broader knowledge of the code in the application, as they may be able to provide insight as to how two seemingly independent areas of an application could be effected by a code change. Reviewing code as a team, as long as the team understand it's for the betterment of __*everyone*__ and isn't meant to call out one another on development choices, can spread the knowledge of the application itself as well as serve as an amazing opportunity to learn from eachother's code and maybe find a new pattern/feature to use later down the line.

These should be short, informal sessions where the primary focus is to review for quality control purposes before a deployment.

__What not to do__

It __*is*__ possible to go overboard with code reviews. "Hindsight is 20/20" applies to code; Everything can be optimized or refactored, but it doesn't necessarily always need to be, especially when working on a timeline. Picking on every development decision, or requiring mandatory code reviews to make trivial changes, can lead to the appearance of lack of trust and confidence in the team which is far from the desired effect. If you feel the need to have that level of oversight in someone's work output, you should probably address it another way.

I'll dive into code reviews and how they can fit nicely into your source control process in another blog post.

### Inaccurate/Incomplete Testing
Let me preface this by saying: I'm not talking about testing inaccuracies caused by the person doing the testing, that's a more 'human' mistake anyone can make and something that's resolved by more experience/training; Even an amazing tester can miss things. I'm talking about testing inaccuracies caused by:

1. Regression
2. Insufficient test cases
3. Inaccurate testing environments

#### Regression & Insufficient Test Cases
Let's pretend you're launching an updated search page for Google. Prior to the code changes, it wasn't displaying pictures of cats when you typed "kitty". So you made some changes and verified that it is in fact displaying pictures of cats when you search "kitty". Purrfect, test passed! Not quite, did you test if it stopped returning pictures of cats when you search "cat", even though it worked before? Did you test if it's returning cats when you search "categories" because it has "cat" in it? 

You can't just test the expected outcome and be confident it works as expected. I always say "try to break it" instead of test it. I won't dive into how to create proper test cases, as frankly I think I'm unqualified and there's plenty of articles on Google that would do better justice to the topic than I ever could.

#### Inaccurate Testing Environments
Even if you have perfect test cases, it's possible that you aren't testing accurately. This normally comes down to where you're testing. If you have typical web application infrastructure there are usually multiple environments. Using Episerver DXC as an example:

You have three DXC-provided environments hosted in Azure and each developer's local machine. These environments can differ in both data and infrastructure. If you're using an outdated or incomplete set of data, you're not accurately testing what your code will do in production. If the infrastructure differs, you may be testing against an environment without a CDN or with 1 app instance whereas your production environment is accessed through a CDN and is likely scaled out to increase traffic capabilities. These kinds of environment-related differences can cause inconsistencies in memory, cache, or performance giving you an inaccrurate test result.

I would highly recommend determining exactly what infrastructure you have in production and replicating that as best as possible for lower environments and ensure your team knows how portions of their code may execute differently based on the infrastructure in place.

### Deployment Strategy / Process
Alright, now let's pretend you aren't effected by any of the above: You know exactly what code is being deployed, you have confidence it's going to work, and you've tested as accurately as possible. Is something still wrong? Well, it likely comes down to deployment strategy.

How your deployments are executed are just as important as the quality of the code itself. It normally comes down to the human factor. If any steps are performed by a person aside from clicking a button to start a deployment or approve a deployment, you're asking for something to go wrong. It's not just steps that can be forgotten or done incorrectly, it's possible for tools used during the deployment to fail. Copying files? Maybe one doesn't transfer, or another isn't deleted when it should be. It's important to standardize and automate this process to eliminate those possibilities.

I highly recommend Azure DevOps. Azure DevOps provides build automation and release management to reliably create code packages in the same manner each time as well as deploy the code in the same manner each time. There's a number of alternatives to Azure DevOps, but it's by far the easiest solution I have used in a long time. In the past I've used TeamCity + Octopus and a few other combinations, but none really match up to Azure DevOps. In my opinion, Azure DevOps is also the easiest to configure and nearly zero effort to maintain. Just a few years ago the amount of time that was spent ensuring our TeamCity and Octopus services were functional, I can't believe the amoiunt of time saved. Especialy since we hosted teamcity+octopus on-premesis,  we had to manage Windows updates, TeamCity/Octopus software updates, pay licenses for Octopus and TeamCity, install specific .NET Framework and NodeJS versions on the machines ourselves and update the build and release tenants on the target machines. The list goes on and on.

Let's look at a plain Azure DevOps build and release pipeline for a typical .NET Framework web application alike Episerver, deploying to Azure (or Episerver DXC):

1. Configuration
2. Automated Builds
3. Release Management & Deployment

#### Configuration
Connecting to source control is as simple as clicking your source control provider:

![build pipeline source configuration](//images.ctfassets.net/advboymm7uww/2KI5VSzZj9oDAkmGbYA8r3/b163e71aa9633f27528700a11ac319ca/build-pipeline-source-configuration.png)

In my example (this blog) I am building from a "release" branch in GitHub. Depending on your source control strategy, choose your appropriate branch to build from.

#### Automated Builds
Create a new build pipeline: and use one of the built-in ASP.NET templates:

![devops build template](//images.ctfassets.net/advboymm7uww/2LKj7gfhTM3i8zV8YyWOyq/463021bd6ef50f341be5099f3805a76b/devops-build-template.png)

You'll see the following setup created for you:

![devops default template build pipeline](//images.ctfassets.net/advboymm7uww/6wE0fBYWVPAtK7hKqR3TG2/73ea7801fca287b5a610aef9a308c014/devops-default-template-build-pipeline.png)

This will build your entire solution and generate an artifact from the build. You can add additional steps if you wish to identically model your local build process, or perform specific build steps for your deployable code package. One example is to add a front-end build tool to the process. For our work it's often Gulp or Webpack, both of which are supported in Azure DevOps just by adding a new step:

![add webpack build step](//images.ctfassets.net/advboymm7uww/5HSCcr8EWEC9VgJ9Y6RN9/89c1e2445ad8c167520b15b4ccd1dce3/webpack-build-step-add.png)
![add gulp build step](//images.ctfassets.net/advboymm7uww/60Z5LVAgOnw88DCGxqsXCa/00d53a716d00bb7622f3da81973bbe95/gulp-build-step-add.png)

Using these, in combination with yarn or npm (also configurable steps), you can execute your prepared scripts the same as your developers would do locally.

Additionally, you can ensure all unit tests pass before allowing a build to continue using the built-in testing capabilities or even third party services for code validation (code coverage, etc).

Once you run your build, you'll see that each build has an associated artifact that contains a zip file ready to be deployed in your release pipeline.

![artifact download animated](//images.ctfassets.net/advboymm7uww/7571ILYv6XOShxUeYgsi1J/a89d362a899af36cafaf4fe708045c54/artifact-download-animated.gif)

This zip file contains the directory that will be extracted when you deploy your code package.

#### Release Management
Now that we have an artifact containing our code, we have a consistent code package ready for deployment. Similar to build pipelines, create a new release pipeline and use a template to get started. As an example, we'll deploy our code package to an Azure Web App.

![azure release pipeline template](//images.ctfassets.net/advboymm7uww/3ZpCv09hnxllGV0hgKf40R/1012c1a31db500ccae11a3d8bd050fd0/azure-release-pipeline-template.png)

You can configure multiple stages for your deployment if you control multiple environments and wish to use Azure DevOps as a full deployment suite for promoting code packages.

![release pipeline stages animated](//images.ctfassets.net/advboymm7uww/X2u5RJa93MQN5p352n4vi/b29db1e4333207c378b009a94fa0d7b1/release-pipeline-stages-animated.gif)

If you're on Episerver DXC, you may only have one deployment stage which is deploying to your Episerver DXC Integration environment, meant to be used as a continuous integration environment.

![release pipeline dxc integration](//images.ctfassets.net/advboymm7uww/31RFMm9f1apW3Fahpf1nRj/f14effce302807f6037ab1bc32ed3f68/release-pipeline-dxc-integration.png)

You can configure your continuous deployments to run each time you build/commit to a specific branch:

![release pipeline ci trigger](//images.ctfassets.net/advboymm7uww/3ctWUK0nnmfFOYdHAzQsgm/fe310957e42455a5338d1103c89d5cd8/release-pipeline-ci-trigger.png)

You can also schedule deployments and configure approvals that are required before completing deployments, including hooks into other services alike Slack or Microsoft Teams for deployment approvals through your team's communication platforms.

If you found this helpful or found issues, please leave a comment below or get in contact with me via the social and email links above. Thanks for reading!

Are you having issues with your Episerver website? Experiencing bugs, slow development cycles, long deployment interruptions? Here's how to improve the reliability and confidence in your Episerver website with automated deployments via Azure DevOps.

Two devs sitting in a conference room watching a screen with Nansen logo

two-devs-in-conference-room-blue

Are you having issues with your Episerver website? Experiencing bugs, slow development cycles, long deployment interruptions? Here&#x27;s how to improve the reliability and confidence in your Episerver website with automated deployments via Azure DevOps.

Fast & Reliable Deployments on Episerver with Azure DevOps

It's no secret that security is vital for different areas of an Episerver website, especially the editing and admin interfaces. If you use Azure Active Directory to login to organization infrastructure already, why not use it to secure your website? Optionally, you can use Azure AD to shield non-production environments from public view entirely, allowing you to develop new features and content without the public's eye on them.

## How To Secure an Episerver With Azure Active Directory
We'll be taking a look at a few different purposes for Azure AD authentication on an Episerver website which are:

1. Restricting visibility of your application from the public
2. Using Azure AD connected to your organization to provide access only to your organization
3. Granting certain teams access to Episerver's editing and administrative interfaces

#### Controlling Visibility
There are a number of reasons to secure the visibility of an entire application. Some common examples are:

1. A lower environment with content that may not be as updated as production, which may cause for legal concerns if outdated information is shown
2. You're working on a new version of a feature or application redesign you do not want the public to see early
3. You're hosting an application for a targeted group, i.e. portal for agents or intranet

#### Securing Episerver UI
You'll want to control access to your episerver content editing and administration via AD. You can get very specific with roles and access rights, or you can just give everyone in your directory access to edit mode.

## How to Setup Azure Active Directory With Episerver
So, we need to connect the authentication process for the website to Azure AD.  Here's the high level process:

1. Creating an Azure AD Application
2. Configuring the OIDC Connector for Azure AD on your site
3. Configuring Editor and Administrator application roles
4. Adding existing AD-driven security groups to application roles

### Creating an Azure AD Application
To start off, we assume that you already have an Azure Active Directory and permissions to add applications. So let's login to https://portal.azure.com and Select "Azure Active Directory" either in the left panel of favorites or via "All Services" search.

![azure portal ad](//images.ctfassets.net/advboymm7uww/1AQAFBcZM9PFfRd7YZfZRN/ece6f27232af18402a61ec6f16e22d86/azure-portal-ad.png)

You should see a screen similar to this, with "App Registrations" down a few options on the left side.

![azure ad applications](//images.ctfassets.net/advboymm7uww/4O81hFVsTDJbC2GGzEvKso/fa4418900cdb4db620dd87507c02c20d/azure-ad-applications.png)

Click into that, and create a new app registration that represents your website's connection with your directory.

![azure ad register application](//images.ctfassets.net/advboymm7uww/46U3TcPHmQNugF4yQRiL7P/52850013598cdd8c1d0e8bfec5fc8730/azure-ad-register-application.png)

I selected to only allow accounts in my organization's directory to use the application. This will grant both members of your directory as well as guests basic ability to authenticate with the application, but it will not grant them any permissions to Episerver's edit or admin mode just yet.

After creation, you should see a page that looks like this containing information you'll need for the configuration in code coming up:

![azure ad connection info](//images.ctfassets.net/advboymm7uww/6buSEfNa6LpA6mhh2JE3V1/fd4c9951419aa3aa3b7c61dac2341a1e/azure-ad-connectioninfo.png)

### Configuring OIDC
For this post, I'm assuming you already have an Episerver application that uses ASP.NET Identity. If you are not using Identity with Episerver yet, see Episerver's [blog post on disabling the membership providers and leveraging ASP.NET Identity with OWIN](https://world.episerver.com/documentation/developer-guides/CMS/security/episerver-aspnetidentity/). You will only need to execute the top three steps on:

1. Disabling <authentication mode="Forms">
2. Disabling <membership> provider
3. Disabling <roleManager> provider
4. Add a basic OwinStartup class that enables Episerver's Identity integration

When working with Azure AD, or just about any other authentication-as-a-service provider, you can OIDC (OpenID Connect) libraries to handle communication between your source of authentication and your application. Install the following NuGet packages:

1. Microsoft.Owin.Security.Cookies
2. Microsoft.Owin.Security.OAuth
3. Microsoft.Owin.Host.SystemWeb
4. Microsoft.Owin.Security.OpenIdConnect
5. Microsoft.IdentityModel.Protocols.OpenIdConnect

#### In your Authentication Config (OwinStartup)
This file can be named a few things, but it refers to which file that Owin will execute a method on to configure auth. If you can't find this file, search for:

1. An AppSetting of: "owin:appstartup". It should have a value that directs it to your startup file. In my case, it's:
```xml
<add key="owin:appStartup" value="CommerceSite.Web.Business.AuthenticationStartup" />
```
or

2. Search your solution for some variation of "assembly: OwinStartup(". It has the same purpose as above, but it's an attribute-based version that decorates the class instead of the app setting.

If you followed Episerver's post on setting up Identity, you'll find it's a class called "Startup". In that class, you should see something that looks similar to:
```csharp
public void Configuration(IAppBuilder app)
{
   app.AddCmsAspNetIdentity<ApplicationUser>();   

   app.UseCookieAuthentication( ... something ... );
}
```
You'll need to modify this Configuration method to be similar to:
```csharp
public void Configuration(IAppBuilder app)
{
    app.AddCmsAspNetIdentity<ApplicationUser>();

    app.SetDefaultSignInAsAuthenticationType(CookieAuthenticationDefaults.AuthenticationType);

    app.UseCookieAuthentication(new CookieAuthenticationOptions());

    var clientId = ConfigurationManager.AppSettings["AzureAD:ClientId"];
    var tenant = ConfigurationManager.AppSettings["AzureAD:Tenant"];
    var redirectUri = ConfigurationManager.AppSettings["AzureAD:RedirectUri"];

    app.UseOpenIdConnectAuthentication(new OpenIdConnectAuthenticationOptions
    {
        ClientId = clientId,
        Authority = tenant,

        TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = false,
            RoleClaimType = ClaimTypes.Role
        },

        Notifications = new OpenIdConnectAuthenticationNotifications
        {
            RedirectToIdentityProvider = context =>
            {
                context.ProtocolMessage.RedirectUri = context.Request.Uri.GetLeftPart(UriPartial.Authority) + redirectUri;

                if (context.OwinContext.Response.StatusCode == 401 && context.OwinContext.Authentication.User.Identity.IsAuthenticated)
                {
                    context.OwinContext.Response.StatusCode = 403;
                    context.HandleResponse();
                }

                return Task.FromResult(0);
            },
            AuthenticationFailed = context => {
                context.HandleResponse();
                context.Response.Redirect("/?Error=" + context.Exception.Message);

                return Task.FromResult(0);
            },
            SecurityTokenValidated = (ctx) =>
            {
                var redirectLoc = new Uri(ctx.AuthenticationTicket.Properties.RedirectUri, UriKind.RelativeOrAbsolute);

                if (redirectLoc.IsAbsoluteUri)
                {
                    ctx.AuthenticationTicket.Properties.RedirectUri = redirectLoc.PathAndQuery;
                }

                ServiceLocator.Current.GetInstance<ISynchronizingUserService>().SynchronizeAsync(ctx.AuthenticationTicket.Identity);

                return Task.FromResult(0);
            }
        },
    });

    app.UseStageMarker(PipelineStage.Authenticate);

}  
```
 Now that's a bit of code, but here's what it's doing for you:

- Configuring OIDC authentication with app settings for:
-- Client ID (Application ID)
-- Tenant
-- A Redirect Uri (relative path)
- Handling for redirection to Azure AD with support for multi-site or multi-domain
- Synchronizing Roles back to Episerver via Episerver's [ISynchronizingUserService](https://world.episerver.com/Search?sectionFilter=&searchQuery=ISynchronizingUserService)

Now, in your application settings, add:
```xml
<add key="AzureAD:ClientID" value="<your client id from step 1 of creating your azure ad application>" />
<add key="AzureAD:Tenant" value="https://login.microsoftonline.com/<your azure tenant id>" />
<add key="AzureAD:RedirectUri" value="/callback" />
```
With any luck, you should be able to just run your project right away with these settings. For a test, visit /episerver and try to access the Episerver CMS interface and see if you are redirected to Microsoft's login page. If you get an error, don't worry, you likely need to update a couple settings. On your Azure AD Application's "Authentication" tab, add your site's URL (with /callback, or your redirect URI from app settings) and enable "id token".

![azure ad app redirecturi token](//images.ctfassets.net/advboymm7uww/ms1vfFmLptimOS5EIccfJ/8531744328ea09cee531b8c021439567/azure-ad-app-redirecturi-token.png)

Try hitting /episerver on your application again. You should successfully see your login configuration:

![azure ad authorize application](//images.ctfassets.net/advboymm7uww/2pvfh5WzIBafPxTDx7N4Q1/a9797470430a96062081ef2c812bf936/azure-ad-authorize-application.png)

Once you accept, don't worry if you see this message:

![auth callback 403](//images.ctfassets.net/advboymm7uww/WzKlh7oerNimPC6PTU5os/3eef561eabf092c2687ee49ef8520ef2/auth-callback-403.png)

It's expected! At this point, you've:

1. Hit a page that requires authentication
2. Authenticated via Azure AD
3. Been returned to your website and are logged in with your remote identity

If you had been trying to access a page/section of your application that only required that you were logged in (no specific roles) you would see the page! If you want to do this, you can check out the next section on securing your entire website behind AD authentication without a specific role. Otherwise, skip to [Securing Episerver UI](https://episerver.dev/blog/securing-episerver-website-with-azure-ad#securing-episerver-ui).

#### Intranets / Internal Portals
If working on an intranet/internal portal, you could use Episerver's Access Rights dialog (once you have access to the CMS) to set that "Everyone" does not have permissions to read content and grant the "Authenticated" role access to Read all content. Here's what that may look like:

![access rights authenticated](//images.ctfassets.net/advboymm7uww/4MUod8MAdgrmTFm5HSkPle/de36aba3e9a9ff006ec6f18a2bd24311/access-rights-authenticated-2.png)

### Securing Episerver UI
If you would like to secure your Episerver CMS Editing and Administration interfaces with Azure AD, you're in luck because that's our next step. There is nearly unlimited ways to configure this, but we'll take a look at the most common two options:

1. Allow anyone who authenticates through Azure AD permission to Episerver UI  (Easiest option for a controlled AD where only employees have accounts)
2. Create an application role in Azure AD and assign an AD security group to that role (Allows for just about any configuration of roles and security groups)

__Allow all users in Active Directory to access Episerver__

I'd recommend doing this via virtual roles as long as you are not providing a method of authentication other than Azure AD throughout your application. In your configuration element for <episerver.framework>, find the <virtualRoles> element. With a fresh installation, you may see something like this:

```xml
<virtualRoles addClaims="true">
        <providers>
            <add name="Administrators" type="EPiServer.Security.WindowsAdministratorsRole, EPiServer.Framework" />
            <add name="Everyone" type="EPiServer.Security.EveryoneRole, EPiServer.Framework" />
            <add name="Authenticated" type="EPiServer.Security.AuthenticatedRole, EPiServer.Framework" />
            <add name="Anonymous" type="EPiServer.Security.AnonymousRole, EPiServer.Framework" />
            <add name="CmsAdmins" type="EPiServer.Security.MappedRole, EPiServer.Framework" roles="WebAdmins, Administrators" mode="Any" />
            <add name="CmsEditors" type="EPiServer.Security.MappedRole, EPiServer.Framework" roles="WebEditors" mode="Any" />
            <add name="Creator" type="EPiServer.Security.CreatorRole, EPiServer" />
        </providers>
    </virtualRoles>
```
modify that section, we'll just change the CmsAdmins and CmsEditors to use the other virtual role, "Authenticated".
```xml
<add name="CmsAdmins" type="EPiServer.Security.MappedRole, EPiServer.Framework" roles="Authenticated" mode="Any" />
<add name="CmsEditors" type="EPiServer.Security.MappedRole, EPiServer.Framework" roles="Authenticated" mode="Any" />
```
now you're all set, you should be able to access Episerver's CMS and Admin areas as any authenticated user in your AD. If you run into issues, ensure your <location path="episerver"> and <location path="episerver/cms/admin"> nodes in your web.config still have access for CmsAdmin/CmsEditors:
```xml
<location path="EPiServer">
    <system.web>
        <authorization>
            <allow roles="CmsAdmins, CmsEditors" />
            <deny users="*" />
        </authorization>
    </system.web>
</location>
<location path="EPiServer/CMS/admin">
    <system.web>
        <authorization>
            <allow roles="CmsAdmins, CmsEditors" />
            <deny users="*" />
        </authorization>
    </system.web>
</location>  
```
__Allow specific users/groups in Active Directory to access Episerver roles__

So, let's pretend you want to secure your Episerver CMS UI with a special security group. There's advantages of this, mainly not having to manage access rights in the CMS and allowing your organization's existing IT processes to handle control of access to properties.

To start, we'll make some new application-specific roles in your Azure AD application. There is not, at the time of writing this post, a GUI interface for this, so you'll need to use the "Manifest" tab of your azure ad application, seen here:

![azure ad manifest](//images.ctfassets.net/advboymm7uww/5jpHNNVrSK32scwCi1HiTs/87d94d8adfd7f5d8121b3a9c80873329/azure-ad-manifest.png)

In the manifest, you'll see the "appRoles" section is empty. We'll just be adding a json-respresentation for a role there: (Replace the generic GUIDs with a new generated GUID)

```csharp
"appRoles": [
    {
        "allowedMemberTypes": [
            "User"
        ],
        "description": "CMS Editor with access to Episerver UI",
        "displayName": "SiteEditors",
        "id": "00000000-0000-0000-0000-000000000001",
        "isEnabled": true,
        "value": "SiteEditors"
    },
    {
        "allowedMemberTypes": [
            "User"
        ],
        "description": "CMS Admin with access to Episerver UI",
        "displayName": "SiteAdmins",
        "id": "00000000-0000-0000-0000-000000000002",
        "isEnabled": true,
        "value": "SiteAdmins"
    }
]  
```
This will create two roles that you can assign individual users or entire AD security groups (limited to paid Azure AD tiers) to via the Azure Portal:

![ad add group to role](//images.ctfassets.net/advboymm7uww/1banKNso4IBqyOjm8FxOoN/94225a804a8b8c2eb058eea1bfa6e0e8/ad-add-group-to-role.png)

Once that's complete and you log out/back into your application, you should have your synchronized roles for "SiteAdmins" or "SiteEditors". You would just need to modify your web.config virtual roles once more to pull your "CmsAdmin" and "CmsEditors" roles from the new AD roles (SiteAdmins and SiteEditors) instead of the "Authenticated" virtual role for all logged in users:

```xml
<add name="CmsAdmins" type="EPiServer.Security.MappedRole, EPiServer.Framework" roles="SiteAdmins" mode="Any" />
<add name="CmsEditors" type="EPiServer.Security.MappedRole, EPiServer.Framework" roles="SiteAdmins, SiteEditors" mode="Any" />  
```
## Wrapping Up
Azure AD is a no-brainer because of the ease of access control it provides to your application. It can be configured in almost endless different ways to provide you detailed access control both in and outside of Episerver.

Find this helpful? Find a bug? Need help with your own Azure AD or Azure B2C providers or any other kind of managed identity provider? Leave a comment or email me with the contact information on the right. Thanks for reading!

It's no secret that security is vital all websites. If you use Azure Active Directory to login to organization infrastructure already, why not use it to secure your website? Here's how to implement it.

Two devs sitting at a computer with Nansen logo

two-devs-at-computer

It's no secret that security is vital all websites. If you use Azure Active Directory to login to organization infrastructure already, why not use it to secure your website? Here's how:

Using Azure AD to Secure an Episerver Website

Have tons of Episerver content? Can't easily distinguish content types from eachother in the page tree? Here's how to leverage some episerver-provided icons that look great!

## Where do the icons come from?
Giving credit where credit is due, Eric ([https://ericceric.com/2017/06/07/use-episervers-content-icons-as-site-tree-icons/](https://ericceric.com/2017/06/07/use-episervers-content-icons-as-site-tree-icons/)) has a great blog post on the built-in icons in Episerver's UI. These icons give us a large amount of well-designed icons at our disposal, without having to load in custom CSS or images.

Eric's blog post also has an example of how you could implement the content icons using an interface, but I wanted to take this one step further. Maybe I'm weird, but I want to be able to leverage every single one of those icons without having to make an interface that implements the icon class, so here's what I did:

## The code
![icon code files](//images.ctfassets.net/advboymm7uww/2rcPw1iNNZ5nPCkIyyG0nu/674a487e485e0cfb1401c22250ca9bee/icon-code-3-files.png)

I will likely release this functionality via a Nuget package in the near future, so I created a class library that contains all of the code required. It's just three files:

1. An enum of all the different icon names
2. An attribute that I can apply to any content type I want
3. An initialization module that does the magic

### ContentIcon.cs
As mentioned, this is an enum of all of the different icon names from Eric's blog post (link above) except I modified the enum names to be exactly the icon's class without the "epi-icon" prefix.

``` csharp
public enum ContentIcon
{
    Clock,
    Checkmark,
    Stop,
    Versions,
    Revert,
    Undo,
    Redo,
    Pen,
    PenDisabled,
    DuplicatePage,
    Primary,
    Trash,
    Users,
    Search,
    Plus,
    Minus,
    Star,
    Settings,
    Lock,
    Pin,
    Page,
    Folder,
    SharedBlock,
    Up,
    Down,
    Reload,
    Share,
    Download,
    DnD,
    ContextMenu,
    Rename,
    Left,
    Right,
    User,
    Hidden,
    NewWindow,
    Catalog,
    Category,
    Product,
    SKU,
    Package,
    Bundle,
    Boxes,
    References,
    Bubble,
    Location,
    Mail,
    Telephone,
    Website,
    Link,
    Upload,
    Error,
    Warning,
    Info,
    Pricing,
    Cut,
    Copy,
    Paste,
    Detach,
    List,
    Thumbnails,
    Tiles,
    Project,
    Published,
    PreviouslyPublished,
    Truck,
    Cart,
    Sort,
    Campaign,
    PublishProject,
    Promotion,
    Layout,
    SortAscending,
    SortDescending,
    Edited,
    Bell,
    Help,
    Segments,
    Guides,
    ObjectRoot,
    ObjectTrash,
    ObjectStart,
    ObjectPage,
    ObjectContainer,
    ObjectInternalLink,
    ObjectExternalLink,
    ObjectNoLink,
    ObjectFetchContent,
    ObjectContainerFetchContent,
    ObjectSharedBlock,
    ObjectFolder,
    ObjectFolderOpen,
    ObjectCatalog,
    ObjectCategory,
    ObjectProduct,
    ObjectVariation,
    ObjectPackage,
    ObjectBundle,
    ObjectUnknown,
    ObjectImage,
    ObjectFolderAllSites,
    ObjectFolderThisSite,
    ObjectPageContextual,
    ObjectSharedBlockContextual,
    ObjectOptimizingBlockContextual,
    ObjectProductContextual,
    ObjectContainerContextual,
    ObjectVideo,
    ObjectExternalFolder,
    ObjectExternalFolderOpen,
    ObjectItem,
    ObjectCart,
    ObjectTruck,
    ObjectCampaign,
    ObjectPromotion,
    ObjectProject,
    Success,
    Danger
}
```

Sweet, so now we have the ability to use ContentIcon.<any icon name>. What's next?

### ContentIconAttribute.cs

We'll make a custom attribute with a constructor that takes a ContentIcon enum value to put on top of any content type we want.

```csharp
public class ContentIconAttribute : Attribute
{
    public ContentIcon Icon { get; set; }

    public ContentIconAttribute(ContentIcon icon)
    {
        Icon = icon;
    }
}
```  
Sweet, so now we can decorate classes with "[ContentIcon(ContentIcon.<icon-name>)]". What's next?

### Initializer.cs
On startup, we need to modify the UIDescriptors for classes that have the [ContentIcon] attribute on them. Now, I'm going to drop the entire code file here, but I'll break it down right below.

```csharp
[InitializableModule]
[ModuleDependency(typeof(InitializableModule))]
public class Initializer : IInitializableModule
{
    public void Initialize(InitializationEngine context)
    {
        var registry = context.Locate.Advanced.GetInstance<UIDescriptorRegistry>();
        var classes = GetDescriptorClasses();

        foreach (var descriptor in registry.UIDescriptors)
        {
            if (classes.ContainsKey(descriptor.ForType))
            {
                descriptor.IconClass += " " + classes[descriptor.ForType];
            }
        }
    }

    public void Uninitialize(InitializationEngine context)
    {
    }

    private Dictionary<Type, string> GetDescriptorClasses()
    {
        var typesWithAttribute = GetTypesWithAttribute();

        var descriptors = new Dictionary<Type, string>();

        foreach (var type in typesWithAttribute)
        {
            var iconAttribute = (ContentIconAttribute)Attribute.GetCustomAttribute(type, typeof(ContentIconAttribute));

            descriptors.Add(type, $"epi-icon{iconAttribute.Icon.ToString()}");
        }

        return descriptors;
    }

    private List<Type> GetTypesWithAttribute()
    {
        var validAssemblies = AppDomain.CurrentDomain.GetAssemblies().Where(x => !x.IsDynamic);
        var typesWithAttribute = new List<Type>();

        foreach (var assembly in validAssemblies)
        {
            typesWithAttribute.AddRange(assembly.GetTypes().Where(type => type.IsDefined(typeof(ContentIconAttribute), false)));
        }

        return typesWithAttribute;
    }
}  
```
As promised, here's what the initializer is doing in general:

1. On Startup, scanning all assemblies for types that have the [ContentIcon] attribute
2. Finding the UI Descriptors that apply to those types from Episerver's UIDescriptorRegistry
3. Setting the IconClass on the UI Descriptor, using the pattern I mentioned above, "epi-icon" + <icon name>.

Alright, now assuming you've either implemented the above or pulled the nuget package for this, how do you use it?

```csharp

[ContentIcon(ContentIcon.Settings)]
[ContentType(GUID = "DC417FE5-A405-43C3-8F9C-868A841E3DE1", DisplayName = "Global Settings Page")]
public class GlobalSettingsPage : PageData
{
    ... Your properties ...
}  
```

Pretty easy, right? Now you can make beautiful and self-explanatory page tree icons in just a couple minutes for all your content types.

![episerver page tree screenshot example](//images.ctfassets.net/advboymm7uww/1DPCPiyMYJL3SyVmqzSnVi/d5dd7ae7c006b94b6f7f344fd713badf/epi-page-tree-example.png)

If you found this helpful, had trouble with any of the code provided, or found a bug, please let me know via the contact information available in the right bar or in the comments.

## Edit #1: Coloring your Icons
Thank you again to Eric, who shared a link to his post on coloring content icons ([https://ericceric.com/2017/07/09/colorize-your-site-icons/](https://ericceric.com/2017/07/09/colorize-your-site-icons/)). Adding colors is a great idea, it can add tons of new icons just by switching up the colors. In the same vein, I extended the [ContentIcon] attribute to support colors. Here's how!

### ContentIconColor.cs
```csharp
public enum ContentIconColor
{
    Default,
    Inverted,
    Active,
    Success,
    Danger,
    Warning,
    Info
}
```
### ContentIconAttribute.cs
```csharp
public class ContentIconAttribute : Attribute
{
    public ContentIcon Icon { get; set; }
    public ContentIconColor Color { get; set; }

    public ContentIconAttribute(ContentIcon icon, ContentIconColor color = ContentIconColor.Default)
    {
        Icon = icon;
        Color = color;
    }
}
```
### Initializer.cs
Modify the method to optionally apply the style if it's not the default icon.
```csharp
private Dictionary<Type, string> GetDescriptorClasses()
{
    var typesWithAttribute = GetTypesWithAttribute();

    var descriptors = new Dictionary<Type, string>();

    foreach (var type in typesWithAttribute)
    {
        var iconAttribute = (ContentIconAttribute)Attribute.GetCustomAttribute(type, typeof(ContentIconAttribute));

        var iconClass = $"epi-icon{iconAttribute.Icon.ToString()}";

        if(iconAttribute.Color != ContentIconColor.Default)
        {
            iconClass += $" epi-icon--{iconAttribute.Color.ToString().ToLower()}";
        }

        descriptors.Add(type, iconClass);
    }

    return descriptors;
}
```
And there you go! You can apply new colors with an optional variable in the [ContentIcon] attribute.
```csharp
[ContentIcon(ContentIcon.User, ContentIconColor.Active)]
[ContentType(GUID = "DC417FE5-A405-43C3-8F9A-868A841E3DE1", DisplayName = "Job Page")]
public class JobPage : PageData
{
    ... Your properties ...
}
```
here's what it looks like:
![content icon colors](//images.ctfassets.net/advboymm7uww/2saCbP0LfuXF2jtFlkhlSe/d86d80b753313bbcee9cdfd6a6ec95fd/content-icon-colors.png)

Have tons of Episerver content? Can't easily distinguish content types from eachother in the page tree? Here's how to add some episerver-supported icons that look great!

Two devs sitting in front of a computer with the Nansen logo

two-devs-at-computer-orange

Have tons of Episerver content? Can't easily distinguish content types from eachother in the page tree? Here's how to leverage some episerver-provided icons that look great!

Posts by Chris Magee

Using Cache Effectively on Episerver

Fast & Reliable Deployments on Episerver with Azure DevOps

Using Azure AD to Secure an Episerver Website

Adding Episerver Content Type Icons in 2 minutes!