Loading...
Area: Optimizely Content Delivery API, Optimizely Content Management API, Optimizely Content Definitions API
Applies to versions: 3 and higher

API Authentication with OpenID Connect

Recommended reading 

You should secure requests to the APIs with OpenID Connect and Bearer Tokens (JWT) by either of the following methods.

  • 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/flows:
    • Authorization code. For interactive clients.
    • Client Credentials. For machine-to-machine communication.
    • Resourse Owner Password.This flow is disabled by default and we only recommend this flow for backward compatibility. This flow is less secure.

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

Installation

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

Configuration

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

    services.AddOpenIDConnect<ApplicationUser>(
        useDevelopmentCertificate: true, 
        signingCertificate: null, 
        encryptionCertificate: null, 
        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();
}

In production, provide a certificate in the form of a X509Certificate2 for signing and encrypting tokens. During development, OpenIddict provides one automatically if useDevelopmentCertificate is set to true.

You can extend the Entity Framework entities OpenIddict and ASP.NET Identity uses for managing applications and users. If you chose to do so, you should disable automatic schema creation and rely on migrations directly from Entity Framework instead.

When configuring our APIs, use the OpenIDConnectOptionsDefaults.AuthenticationScheme constant as the authentication scheme.  Authentication scheme is the first parameter in each method that adds the API.

public void ConfigureServices(IServiceCollection services)
{
    services.AddContentDeliveryApi(OpenIDConnectOptionsDefaults.AuthenticationScheme);
}

This scheme can also be used in your own web API endpoints.

[Authorize(OpenIDConnectOptionsDefaults.AuthenticationScheme)]
public class MyApiController : ControllerBase
{
}
Do you find this information helpful? Please log in to provide feedback.

Last updated: Nov 17, 2021

Recommended reading