Backoffice Authentication

Authentication gives you control over who has access to your backoffice.

By default, Ucommerce automatically authenticates as a test administrator account. This is very useful when developing locally, so you do not have to set up authentication from the get-go. When going to production this should be changed, however, so the back office is protected from unverified use, and handle individual user permissions. Ucommerce leverages the built-in ASP.NET Core authorization to restrict access to the back office API. This means that you will have to implement an ASP.NET authorization system yourself.

It is recommended that you integrate a well-known identity provider. We have examples of how it can be done using Microsoft Entra ID and Auth0.

We suggest that you implement an authorization system using OpenID Connect since this will enable you to use single sign-on (SSO), allowing you to share logins between Ucommerce and other OAuth-enabled applications like a CMS.

Add an external identity provider

Ucommerce takes care of the local login session, so you need to set up a scheme that will take care of logging in the user. Additionally, Ucommerce needs an implementation of the IExternalClaimsMapper interface.

Use the options hook when calling AddBackOffice() in program.cs, to configure your scheme:

var ucommerceBuilder = builder.Services.AddUcommerce(builder.Configuration)
    .AddBackOffice(securitySettings =>
        {
            // This method can be called multiple times
            securitySettings.AddExternalIdentityProvider<MyExternalClaimsMapper>(
                "MyExternalScheme",
                authenticationBuilder =>
                {
                ... // Use the AuthenticationBuilder to add your scheme
                });
            // Configure Ucommerce to use your scheme from code
            securitySettings.UseExternalIdentityProvider("MyExternalScheme");
        }
    )
    ...

Since Ucommerce takes care of the session cookie, you should not set cookies in your external authentication scheme.

You can use the ASP.NET configuration to override the external identity provider that Ucommerce will forward to. You can define the scheme by setting the value for Ucommerce:BackOffice:ExternalIdentityProviderScheme to the name of one of the registered schemes. This allows you to change the provider depending on the environment. To use the built-in scheme set the value to ucommerce-test-user.

External Claims Mapper

Ucommerce automatically creates and updates a local user when a user logs in via an external identity provider, so it needs a mapping of the external claims, to the local user in Ucommerce. To create a mapping you implement the IExternalClaimsMapper interface.

The interface consists of a single method MapClaims that must take care of the mapping from the incoming claim to an AuthUser object.

using Ucommerce.Web.BackOffice.Authentication;
...

public class MyExternalClaimsMapper : IExternalClaimsMapper
{
    public Task<AuthUser> MapClaims(ClaimsPrincipal principal)
    {
        var externalId = // A claim value with a unique identifier for the user
        //e.g.
        //var externalId = principal.FindFirstValue(ClaimTypes.NameIdentifier)!;
        var name = // A claim value containing the name of the user
        var isAdmin = // A claim value indicating if the user is to be an admin
        var user = new AuthUser(externalId, name)
        {
            IsAdmin = isAdmin
        };
        return Task.FromResult(user);
    }
}

AuthUser Properties

Property	Description
ExternalId	The identifier from the external provider used to identify the user in Ucommerce
Name	The name of the user
IsAdmin	Indicate if the user should have administrator rights

The default ExternalClaimsMapper

Ucommerce comes with a default claims mapper (Ucommerce.Web.BackOffice.Authentication.ExternalClaimsMapper) that maps claims in the following way. The keys are also defined in the UcommerceClaimTypes constants class.

Property	UcommerceClaimTypes Key	Value
ExternalId	EXTERNAL_IDENTIFIER	ClaimTypes.NameIdentifier
Name	NAME	ClaimTypes.Name
IsAdmin	IS_ADMIN	"IsAdmin"

Related Articles

Introduction to authorization in ASP.NET CoreMicrosoftLearn

OpenID Connect (OIDC) on the Microsoft identity platform - Microsoft Entradocsmsft

Authorize with a specific scheme in ASP.NET CoreMicrosoftLearn

Microsoft Entra ID Example

Auth0 Authentication Example