Asp.Net Core simple role authorization with Windows Authentication

Readme.md

Asp .Net Core simple role authorization with Windows Authentication

What's this all about ?

The idea is to use good old fashioned role based authorization with Windows Authentication.

The default behavior of WindowsAuthentication is to load the claims and roles from the windows authorization pipeline (AD, local rights, etc...). This results in the roles or claims to be based on the user groups.

If this behavior does not suit you and you would prefer loading the user roles from a custom storage (database, configuration file, etc...), continue on reading.

To make this happend, you need to implement a class that loads the roles for a user, enable windows authentication and register the role management services.

Note that this implementation is based on simple roles authorization. You can still use the same principle of registering a IClaimsTransformation that sets up claims that are not used as roles and then define access policies based on these claims.

How to use

Configure windows authentication with IIS or HTTP.sys

First enable the windows authentication option in IIS, IIS Express or HTTP.sys (see link below if you don't know how to do it).

Then, if you are using ASP.Net Core 2.x you must register extra services to perform the authentication challenge. To do so, add one of the following line in the ConfigureServices method.

Using IIS:

// IISDefaults requires the following import:
// using Microsoft.AspNetCore.Server.IISIntegration;
services.AddAuthentication(IISDefaults.AuthenticationScheme);

Using HTTP.sys

// HttpSysDefaults requires the following import:
// using Microsoft.AspNetCore.Server.HttpSys;
services.AddAuthentication(HttpSysDefaults.AuthenticationScheme);

In addition, Do not forget to add app.UseAuthentication(); to the Configure method of your Startup class.

For detailled instructions, please refer to the documentation page provided by microsoft: Configure Windows Authentication in ASP.NET Core

Including the library code

Include the three files into your projetc (don't forget to fix the namespaces):

• ISimpleRoleProvider.cs
• SimpleRoleAuthorizationTransform.cs
• SimpleRoleAuthorizationServiceCollectionExtensions.cs

Implement the class that will load the user roles

To provide the roles for a given user, you must implement a class inheriting from ISimpleRoleProvider. The GetUserRolesAsync method receives the full windows user name including the domain or machine name (eg. MyDomain\Myuser). Beware that it will be called for each request so keep in mind that it might affect performance.

The example below has hard-coded roles for two users. But feel free to load the roles from any data source like a database or the configuration files. Also note that we defined constants for role names. These are not mandatory but can help avoid typos when restricting access to routes later. As constants, they can be used as parameter to the Routes property of the AuthorizeAttribute attribute.

public class DemoSimpleRoleProvider : ISimpleRoleProvider
{
    public const string ADMIN = "Admin";
    public const string BASIC_USER = "BasicUser";

    public Task<ICollection<string>> GetUserRolesAsync(string userName)
    {
        ICollection<string> result = new string[0];

        // Here, John is a basic user and Arnold an admin user
        // Feel free to load roles from any source you like.
        if (!string.IsNullOrEmpty(userName))
        {
            if (userName.EndsWith("john", StringComparison.OrdinalIgnoreCase))
                result = new[] { BASIC_USER };
            else if (userName.EndsWith("arnold", StringComparison.OrdinalIgnoreCase))
                result = new[] { BASIC_USER, ADMIN };
        }

        return Task.FromResult(result);
    }
}

Register the simple role authentication and enable your role provider

The last step to enable simple role authentication is to register the simple role transform and the simple role provider you implemented.

In the ConfigureServices method, add the following code:

// Setup the custom simple role authorization with
// "DemoSimpleRoleProvider" implementation to provide the roles for a user.
services.AddSimpleRoleAuthorization<DemoSimpleRoleProvider>();

Declaring required roles on the Controllers and controller routes

To restrict access to certain roles on your controller and controller routes, you must use the AuthorizeAtribute and set it's Roles property to the roles that allowed to access the controller or method.

Here is an example of a controller restricting access. Note that, as we defined constants for role names in our DemoSimpleRoleProvider, we can use the same constants here:

[Route("api/[controller]")]
[ApiController]
public class DemoController : ControllerBase
{
    [HttpGet]
    public ActionResult<string> Get()
    {
        return "Congrats ! Anyone can access this !";
    }

    [HttpGet("Admin")]
    [Authorize(Roles=DemoSimpleRoleProvider.ADMIN)]
    public ActionResult<string> GetAdmin()
    {
        return "Congrats ! You just made an admin call !";
    }

    [HttpGet("Basic")]
    [Authorize(Roles = DemoSimpleRoleProvider.BASIC_USER)]
    public ActionResult<string> GetBasic()
    {
        return "Congrats ! You just made a basic user call !";
    }
}

ISimpleRoleProvider.cs

using System.Collections.Generic;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Authorization;

namespace DamienBraillard.AspNetCoreSimpleRoleAuthorization
{
    /// <summary>
    /// Defines the base functionality of the class used to provide applicative roles for a user when using the simple role
    /// authorization.
    /// </summary>
    public interface ISimpleRoleProvider
    {
        #region Public Methods

        /// <summary>
        /// Loads and returns the role names for a given user name.
        /// </summary>
        /// <param name="userName">The login name of the user for which to return the roles.</param>
        /// <returns>
        /// A collection of <see cref="string" /> that describes the roles assigned to the user;
        /// An empty collection of no roles are assigned to the user.
        /// </returns>
        /// <remarks>
        ///     <para>Beware that this method is called for each controller call. It might impact performance.</para>
        ///     <para>
        ///     If Windows authentication is used, the passed <paramref name="userName" />
        ///     is the full user name including the domain or machine name (e.g "CostroDomain\JohnDoe" or
        ///     "JOHN-WORKSTATION\JohnDoe").
        ///     </para>
        ///     <para>
        ///     The returned roles names can be used to restrict access to controllers using the <see cref="AuthorizeAttribute" />
        ///     (<c>[Authorize(Roles="...")]</c>
        ///     </para>
        /// </remarks>
        Task<ICollection<string>> GetUserRolesAsync(string userName);

        #endregion
    }
}

SimpleRoleAuthorizationServiceCollectionExtensions.cs

using Microsoft.AspNetCore.Authentication;
using Microsoft.Extensions.DependencyInjection;

namespace DamienBraillard.AspNetCoreSimpleRoleAuthorization
{
    /// <summary>
    /// Provides the extension methods to enable and register the simple role authentication on an Asp.Net Core web site.
    /// </summary>
    public static class SimpleRoleAuthorizationServiceCollectionExtensions
    {
        #region Public Static Methods

        /// <summary>
        /// Activates simple role authorization for Windows authentication for the ASP.Net Core web site.
        /// </summary>
        /// <typeparam name="TRoleProvider">The <see cref="Type"/> of the <see cref="ISimpleRoleProvider"/> implementation that will provide user roles.</typeparam>
        /// <param name="services">The <see cref="IServiceCollection"/> onto which to register the services.</param>
        public static void AddSimpleRoleAuthorization<TRoleProvider>(this IServiceCollection services)
            where TRoleProvider : class, ISimpleRoleProvider
        {
            services.AddSingleton<ISimpleRoleProvider, TRoleProvider>();
            services.AddSingleton<IClaimsTransformation, SimpleRoleAuthorizationTransform>();
        }

        #endregion
    }
}

SimpleRoleAuthorizationTransform.cs

using System;
using System.Linq;
using System.Security.Claims;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Authentication;

namespace DamienBraillard.AspNetCoreSimpleRoleAuthorization
{
    /// <summary>
    /// Implements a <see cref="IClaimsTransformation" /> that uses a <see cref="ISimpleRoleProvider" /> to fetch and apply
    /// applicative roles
    /// for a user.
    /// <para>
    /// To use, you need to implement a class that inherit from <see cref="ISimpleRoleProvider" /> and use the
    /// <see cref="SimpleRoleAuthorizationServiceCollectionExtensions.AddSimpleRoleAuthorization{TRoleProvider}" /> extension
    /// method
    /// in the <c>ConfigureServices</c> method of the <c>Startup</c> class to enable the simple role authorization and
    /// associate your simple role provider implementation.
    /// </para>
    /// </summary>
    public class SimpleRoleAuthorizationTransform : IClaimsTransformation
    {
        #region Private Fields

        private static readonly string RoleClaimType = $"http://{typeof(SimpleRoleAuthorizationTransform).FullName.Replace('.', '/')}/role";
        private readonly ISimpleRoleProvider _roleProvider;

        #endregion

        #region Public Constructors

        public SimpleRoleAuthorizationTransform(ISimpleRoleProvider roleProvider)
        {
            _roleProvider = roleProvider ?? throw new ArgumentNullException(nameof(roleProvider));
        }

        #endregion

        #region Public Methods

        public async Task<ClaimsPrincipal> TransformAsync(ClaimsPrincipal principal)
        {
            // Cast the principal identity to a Claims identity to access claims etc...
            var oldIdentity = (ClaimsIdentity)principal.Identity;

            // "Clone" the old identity to avoid nasty side effects.
            // NB: We take a chance to replace the claim type used to define the roles with our own.
            var newIdentity = new ClaimsIdentity(
                oldIdentity.Claims,
                oldIdentity.AuthenticationType,
                oldIdentity.NameClaimType,
                RoleClaimType);

            // Fetch the roles for the user and add the claims of the correct type so that roles can be recognized.
            var roles = await _roleProvider.GetUserRolesAsync(newIdentity.Name);
            newIdentity.AddClaims(roles.Select(r => new Claim(RoleClaimType, r)));

            // Create and return a new claims principal
            return new ClaimsPrincipal(newIdentity);
        }

        #endregion
    }
}

is it working on .net8?