HomeDev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

Integrate Azure AD using OpenID Connect

Describes 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 middleware.

📘

Note

If you have EPiServer.CMS.UI.AspNetIdentity installed, make sure you are not calling services.AddCmsAspNetIdentity() in startup.cs. Otherwise, the user interface may not look for synchronized users when setting access rights.

About Azure Active Directory and OpenID

Azure Active Directory (Azure AD) 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 is an open standard for authorization also used by Azure AD. OpenID Connect 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 information about how the protocols work, see Authentication Scenarios for Azure AD and Secure your application by using OpenID Connect and Azure AD. 

Prerequisites

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 OnSignedIn event is used to sync the user and group membership to Optimizely. You can also use this event for custom logic (for example, adding custom data to the user profile).

public void ConfigureServices(IServiceCollection services) {
  ...
  services
  .AddAuthentication(options => {
    options.DefaultAuthenticateScheme = "azure-cookie";
    options.DefaultChallengeScheme = "azure";
  })
  .AddCookie("azure-cookie", options => {
    options.Events.OnSignedIn = async ctx => {
      if (ctx.Principal?.Identity is ClaimsIdentity claimsIdentity) {
        // Syncs user and roles so they are available to the CMS
        var synchronizingUserService = ctx
          .HttpContext
          .RequestServices
          .GetRequiredService < ISynchronizingUserService > ();

        await synchronizingUserService.SynchronizeAsync(claimsIdentity);
      }
    };
  })
  .AddOpenIdConnect("azure", options => {
    options.SignInScheme = "azure-cookie";
    options.SignOutScheme = "azure-cookie";
    options.ResponseType = OpenIdConnectResponseType.Code;
    options.CallbackPath = "/signin-oidc";
    options.ClientSecret = "YOUR CLIENT SECRET";
    options.UsePkce = true;

    // If Azure AD is register for multi-tenant
    //options.Authority = "https://login.microsoftonline.com/" + "common" + "/v2.0";
    options.Authority = "https://login.microsoftonline.com/" + "tenant id" + "/v2.0";
    options.ClientId = "client id";

    options.Scope.Clear();
    options.Scope.Add(OpenIdConnectScope.OpenIdProfile);
    options.Scope.Add(OpenIdConnectScope.OfflineAccess);
    options.Scope.Add(OpenIdConnectScope.Email);
    options.MapInboundClaims = false;

    options.TokenValidationParameters = new TokenValidationParameters {
      RoleClaimType = "roles",
        NameClaimType = "preferred_username",
        ValidateIssuer = false
    };

    options.Events.OnRedirectToIdentityProvider = ctx => {
      // Prevent redirect loop
      if (ctx.Response.StatusCode == 401) {
        ctx.HandleResponse();
      }

      return Task.CompletedTask;
    };

    options.Events.OnAuthenticationFailed = context => {
      context.HandleResponse();
      context.Response.BodyWriter.WriteAsync(Encoding.ASCII.GetBytes(context.Exception.Message));
      return Task.CompletedTask;
    };
  });
  ...
}

Add application roles in Azure Active Directory

You must declare application roles in the active directory application, such as WebEditors and WebAdmins. The application owner (developer of the app) or the global administrator of the developer's directory can declare roles for an application.

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

Assign 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 you want to assign users and groups.
  2. Select a user and click Assign on the bottom bar to assign the desired role to the user.