XperienceCommunity.SitePartitioning

Description

This package allows for the simple partitioning of an Xperience by Kentico site into separate Admin and Frontend installations.

It achieves a similar result to decoupling the admin without the limitations and complexity associated with that approach.

Library Version Matrix

Xperience Version	Library Version
>= 30.0.0	1.0.0

Dependencies

• ASP.NET Core 8.0
• Xperience by Kentico

Package Installation

Install the XperienceCommunity.SitePartitioning package via nuget or run:

Install-Package XperienceCommunity.SitePartitioning

From package manager console.

Quick Start

Configuration

Include the following section within your appsettings.json file:

"XperienceSitePartitioning": {
   "SiteRole": "Frontend"
}

Register services

Add the following code to your Program.cs file:

var builder = WebApplication.CreateBuilder(args);

// ...

builder.Services.AddXperienceSitePartitioning();

And include app.UseXperienceSitePartitioning() before app.InitKentico():

app.UseXperienceSitePartitioning();
app.InitKentico();

And that should be enough to get going. Read on for more info.

Full Instructions

Configuring Site Roles

To make use of this package, you must specify a SiteRole for your running application.

List of possible roles:

• Single
  • Default option. No separation. Useful during local development.
• Frontend
  • Specifies that the running instance should act as a Frontend only. All admin functionality and routing is disabled.
• Admin
  • Specifies that the running instance should act as an Admin only. Access to frontend routes is blocked unless via Page builder etc..

Deployment

This setting can be configured as part of a build and transformation pipeline to deploy a 'separate' Admin and Frontend application, based on the defined SiteRole setting.

Routing

The package uses middleware to intercept requests and inspects path segments to determine whether a frontend or admin route was requested. The request will then be rejected with a 404 based on the current site role.

Default status code

The default rejection status code (404) can be configured via settings:

"XperienceSitePartitioning": { 
   "SiteRole": "Frontend",
   "RejectionStatusCode": 403 // Forbidden
}

External Auth / SSO

If you're using External Authentication and you have configured a custom OIDC admin path e.g. not /admin-oidc then you must provide this path as options:

"XperienceSitePartitioning": { 
   "SiteRole": "Frontend",
   "AdminOidcPath": "/your-custom-admin-oidc"
}

This will ensure that the OIDC path is safely whitelisted.

Role Retriever

The package provides an ISiteRoleRetriever service which can be used to fetch the current site role of the running application:

public class FooService : IFooService
{
    private readonly ISiteRoleRetriever siteRoleRetriever;

    public FooService (ISiteRoleRetriever siteRoleRetriever)
    {
        this.siteRoleRetriever = siteRoleRetriever;
    }
    
    public void RunOnAdminOnly()
    {
        var role = this.siteRoleRetriever.CurrentRole;

        if (role == SiteRole.Admin)
	{
            // Run some code for the admin site only...
        }
    }
}

The service can be used to perform logic specific to either the Admin or Frontend applications.

Full configuration

See below for a list of all possible configuration options:

Option	Description	Example	Default
SiteRole	Sets the current application Site Role. Possible options are Single, Frontend, and Admin.	"Frontend"	"Single"
AdminOidcPath	Allows for specifying a custom Admin OIDC path to be whitelisted, if using SSO/External Authentication.	"/admin-oidc-path"	"/admin-oidc"
AdditionalAdminPaths	Allows for specifying of additional path segments to be whitelisted when running as Admin site role.	["/foo-path"]	[]
RejectionStatusCode	Allows for customizing of the default rejection status code.	"403"	"404"

Contributing

To see the guidelines for Contributing to Kentico open source software, please see Kentico's CONTRIBUTING.md for more information and follow the Kentico's CODE_OF_CONDUCT.

License

Distributed under the MIT License. See LICENSE.md for more information.