Dev GuideAPI ReferenceUser Guide
HomeDev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunityDoc feedbackLog In
GitHubNuGetDev CommunityDoc feedback

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 more information about how the protocols works, see [Authentication Scenarios for Azure AD](🔗) and [Secure your application by using OpenID Connect and Azure AD](🔗). For role-based access control, see [Adding application roles in Azure AD](🔗).

## Prerequisites

### Disable Role and Membership Providers

Disable the built-in Role and Membership providers in _web.config._

Leave the profile system enabled since edit and admin views use this system for language settings, it is possible to use another profile system on the website.


### Configure Optimizely to support claims
Enable claims on virtual roles by setting the **addClaims** property. Also, add the provider **SynchronizingRolesSecurityEntityProvider** for security entities, which is used by the set access rights dialog box, content approval, impersonating users among other things.
Users and groups are synchronized to custom Optimizely tables in the database when a user is authenticated (see ISynchronizingUserService in the code example below). There is no background synchronization so for a role change to take affect the user have to login to the site again.

You can replace virtual roles with roles defined in the manifest to delegate this control from the application to Azure, see [Virtual roles](🔗).
Install NuGet packages
Open Package Manager in Visual Studio and install the following packages:
  • Install-Package Microsoft.Owin.Security.Cookies
  • Install-Package Microsoft.Owin.Security.OpenIdConnect
  • Install-Package Microsoft.Owin.Host.SystemWeb
  • Update-Package Microsoft.IdentityModel.Protocol.Extensions -Safe
Note
Always use _Microsoft.IdentityModel.Protocol.Extensions_ package version 1.0.2 or later. Previous versions contain a critical bug that might cause threads to hang.
### Configure OpenID Connect
To configure the OpenID Connect, add the following code in the startup class for OWIN middleware. 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).

## Add 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 the **Manage Manifest** action button on the bottom bar and select **Download Manifest**.
  4. Open the manifest file in a JSON editor of your choice.
  5. Locate the **appRoles** setting and insert the appRole definitions in the array.  
This is an example of approles that declare WebAdmins and WebEditors. You can modify it according to your application roles. Note that you need to generate new Guid for each role declaration.  
    
<!----->
  1. After declaration of the application roles, you need to upload the manifest to Azure Active Directory application. See [Role-based access control](🔗) for more information.
### 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 to which you would like to assign users and groups.
  2. Select a user and click on the **Assign** action on the bottom bar. Here you can assign the desired role to the user.
### Known issues
  • If you are using System.IdentityModel.Tokens.Jwt version 4.0.0 or lower, it is required to set **RoleClaimType = "roles"** in the TokenValidationParameters.
  • If the application throws an antiforgerytoken exception like “AntiForgeryToken: A Claim of Type NameIdentifier or IdentityProvider Was Not Present on Provided ClaimsIdentity”, set **AntiForgeryConfig.UniqueClaimTypeIdentifier = ClaimTypes.NameIdentifier.**