Authenticate the API

Using the following methods, you can secure requests to the APIs with OpenID Connect and Bearer Tokens (JWT) with our library EPiServer.OpenIDConnect. You are not limited to using this library, any authentication scheme is supported.

• Configure the application to use an external login provider and enable the JWT Bearer token middleware.
• Use the implementation based on OpenIddict, ASP.NET Identity, and Entity Framework. The Optimizely implementation gives you the basic OpenID Connect support and the following grant types or flows:
  • Authorization code – For interactive clients.
  • Client Credentials – For machine-to-machine communication.
  • Resource Owner Password – This flow is turned off by default, and you should only use this flow for backward compatibility. This flow is less secure.

Optimizely supports the user info endpoint for retrieving additional user claims.

Install

Install the EPiServer.OpenIDConnect NuGet package from the NuGet feed. You can optionally install EPiServer.OpenIDConnect.UI to get access to a UI where you can revoke authorizations.

Configure

public void ConfigureServices(IServiceCollection services) {
  // ASP.NET Identity needs to be configured before OpenID Connect
  services.AddCmsAspNetIdentity<ApplicationUser>();

  services.AddOpenIDConnect<ApplicationUser>(
    useDevelopmentCertificate: true,
    createSchema: true,
    options => {
      // Sample interactive JavaScript application 
      options.Applications.Add(new OpenIDConnectApplication {
        ClientId = "frontend",
          Scopes = {
            "openid",
            "offline_access",
            "profile",
            "email",
            "roles"
          },
          PostLogoutRedirectUris = {
            new Uri("http://localhost:8080")
          },
          RedirectUris = {
            new Uri("http://localhost:8080/login-callback"),
            new Uri("http://localhost:8080/login-renewal"),
          },
      });

      // Sample application using Client Credentials to make
      // machine-to-machine API calls
      options.Applications.Add(new OpenIDConnectApplication {
        ClientId = "cli",
          ClientSecret = "cli",
          Scopes = {
            ContentDefinitionsApiOptionsDefaults.Scope
          }, // Default scope from Content Definitions API
      });
    });

  // If you have installed EPiServer.OpenIDConnect.UI
  services.AddOpenIDConnectUI();
}

After that, configure Content Delivery API in startup.cs:

services.AddContentDeliveryApi(OpenIDConnectOptionsDefaults.AuthenticationScheme, options => {
    options.SiteDefinitionApiEnabled = true;
    options.DisableScopeValidation = false; //default value = true
})
   .WithFriendlyUrl()
   .WithSiteBasedCors();

If DisableScopeValidation = true, Content Delivery API will accept anonymous requests.

In production, provide X509Certificate2 certificates for signing and encrypting tokens in the configuration method. During development, OpenIddict provides one automatically if useDevelopmentCertificate is set to true in the configuration method. If the application runs in DXP, Optimizely will provide certificates automatically through the EPiServer.CloudPlatform.Cms package in version 1.6.1 or later and EPiServer.ContentDeliveryApi.Cms 3.11.3 or later.

📘

Manually provide signing and encrypting certificates

If you are using EPiServer.CloudPlatform.Cms prior to 1.6.1 and EPiServer.ContentDeliveryApi.Cms prior to 3.11.3, manually provide the certificates:

C#

var certificates = EPiServer.CloudPlatform.Cms.Certificates.CertificatesProvider.Get(_configuration);

services.AddOpenIDConnect<ApplicationUser>(
    useDevelopmentCertificate: false,
    certificates.SigningCertificate,
    certificates.EncryptionCertificate,
    createSchema: true);

Extending the entities

You can extend the Entity Framework entities OpenIddict and ASP.NET Identity is using for managing applications and users. Then you should turn off automatic schema creation and rely on Entity Framework migrations instead.

Authorize other endpoints

You can use the authentication scheme provided by this library in your own web API endpoints.

[Authorize(OpenIDConnectOptionsDefaults.AuthenticationScheme)]
public class MyApiController : ControllerBase {
}