Try our conversational search powered by Generative AI!

Area: Optimizely CMS
Applies to versions: 12 and higher
Other versions:
ARCHIVED This content is retired and no longer maintained. See the version selector for other versions of this topic.

Integrate Azure AD using OpenID Connect

Recommended reading 
Note: This documentation is for the preview version of the upcoming release of CMS 12/Commerce 14/Search & Navigation 14. Features included here might not be complete, and might be changed before becoming available in the public release. This documentation is provided for evaluation purposes only.

This topic explains how to use OpenID Connect to integrate with Azure Active Directory. It also describes how an Optimizely application can use the OpenID Connect to sign in users from a single/multi-tenant environment, using the ASP.Net OpenID Connect OWIN middleware.

Note: If you have EPiServer.CMS.UI.AspNetIdentity installed, you need to uninstall it from your environment. Otherwise, the user interface may not look for synchronized users when setting access rights.
If you also have EPiServer.CMS installed, you have to uninstall that too, to stop EPiServer.CMS.UI.AspNetIdentity from being re-installed at the next upgrade. You may have to force-uninstall the packages.

About Azure Active Directory and OpenID

Azure Active Directory (Azure AD) external-link.png is Microsoft's multi-tenant cloud-based directory and identity management service. Azure AD provides single sign-on (SSO) access to many cloud-based SaaS applications, and includes a full suite of identity management capabilities.

OAuth external-link.png is an open standard for authorization also used by Azure AD. OpenID Connect external-link.png is built on top of OAuth and extends this so you can use it as an authentication protocol rather than just an authorization protocol.

For more information about how the protocols works, see Authentication Scenarios for Azure AD and Secure your application by using OpenID Connect and Azure AD external-link.png. For role-based access control, see Adding application roles in Azure AD.


You can replace virtual roles with roles defined in the manifest to delegate this control from the application to Azure, see Adding application roles in Azure Active Directory.

Install NuGet packages

Open Package Manager in Visual Studio and install the following package:

Install-Package Microsoft.AspNetCore.Authentication.OpenIdConnect

Configure OpenID Connect

To configure the OpenID Connect, add the following code in the startup class. The SecurityTokenValidated event is used to synchronize the user and group membership to Episerver. You can also use this event for custom logic (for example, adding custom data to the user profile).

public class Startup
  public void ConfigureServices(IServiceCollection services)
    .AddAuthentication(options =>
      options.DefaultAuthenticateScheme = CookieAuthenticationDefaults.AuthenticationScheme;
      options.DefaultChallengeScheme = OpenIdConnectDefaults.AuthenticationScheme;
    options =>
      options.SignInScheme = CookieAuthenticationDefaults.AuthenticationScheme;
      options.ClientId = "client id";
      options.Authority = "" + "tenant id" + "/v2.0";
      // if the azure AD is register for multi-tenant
      //options.Authority = "" + "common" + "/v2.0";
      options.CallbackPath = "/signin-oidc";
      options.TokenValidationParameters = new TokenValidationParameters
        ValidateIssuer = false,
        RoleClaimType = ClaimTypes.Role,
        NameClaimType = ClaimTypes.Email
      options.Events.OnAuthenticationFailed = context =>
        return Task.FromResult(0);
      options.Events.OnTokenValidated = (ctx) =>
        var redirectUri = new Uri(ctx.Properties.RedirectUri, UriKind.RelativeOrAbsolute);
        if (redirectUri.IsAbsoluteUri)
          ctx.Properties.RedirectUri = redirectUri.PathAndQuery;
        //Sync user and the roles to EPiServer in the background
        ServiceLocator.Current.GetInstance<ISynchronizingUserService>().SynchronizeAsync(ctx.Principal.Identity as ClaimsIdentity);
        return Task.FromResult(0);

Adding application roles in Azure Active Directory

By default, you need to declare application roles in the active directory application such as WebEditors and WebAdmins. Either the application owner (developer of the app) or the global administrator of the developer’s directory can declare roles for an application.

  1. In the Azure Management Portal, navigate to the Active Directory node and go to the Applications tab.
  2. Click to open the application for which you wish to declare application roles.
  3. Click App roles.
  4. Create WebAdmins, WebEditors and Administartors app role: This is an example of app roles that declare WebAdmins and WebEditors. You can modify it according to your application roles.

Assigning users and groups to application roles

When a global administrator of the customer’s organization has installed your application, they (or a user accounts administrator) can assign users and groups to your application:

  1. Go to the Users tab under the application to which you would like to assign users and groups.
  2. Select a user and click on the Assign action on the bottom bar to assign the desired role to the user.
Do you find this information helpful? Please log in to provide feedback.

Last updated: Jul 02, 2021

Recommended reading