faysilalshareef/gateway-security

Gateway Security — Authentication & Authorization

Core Principles

• AddJwtAuthentication(configuration) registers JWT Bearer from Jwt config section
• AddPolicies(ApiScope) registers all authorization policies and handlers
• ApiScope enum determines the scope claim value (Consumer, PublicConsumer, Management)
• Policy constants class defines policy names used in [Authorize(Policy = ...)]
• Roles constants class defines role names used in [Authorize(Roles = ...)]
• Custom IAuthorizationRequirement + AuthorizationHandler<T> for complex policies
• Authorization handlers are registered as AddScoped<IAuthorizationHandler, T>()
• Controllers apply [Authorize], [Authorize(Policy = ...)], or [Authorize(Roles = ...)]

Key Patterns

AddJwtAuthentication Extension

Simple extension that configures JWT Bearer using Authority and Audience from the Jwt configuration section.

using Microsoft.AspNetCore.Authentication.JwtBearer;

namespace {Company}.Gateways.Common.ServicesRegistration;

public static class AuthenticationRegistrar
{
    public static void AddJwtAuthentication(
        this IServiceCollection services, IConfiguration configuration)
    {
        services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
            .AddJwtBearer(JwtBearerDefaults.AuthenticationScheme, options =>
            {
                var jwtConfiguration = configuration.GetSection("Jwt");
                options.Authority = jwtConfiguration["JwtAuthority"];
                options.Audience = jwtConfiguration["JwtAudience"];
            });
    }
}

ApiScope Enum

Determines which scope claim value is required for the Consumer policy. Each gateway type passes its own ApiScope at startup.

namespace {Company}.Gateways.Common.Policies;

public enum ApiScope
{
    Consumer = 1,
    PublicConsumer = 2,
    Management = 3
}

AddPolicies Extension with ApiScope

Registers all policies using AddAuthorizationBuilder() fluent API. The Consumer policy scope claim varies by ApiScope. Other policies use custom IAuthorizationRequirement types.

using {Company}.Gateways.Common.Constants;
using {Company}.Gateways.Common.Policies;
using {Company}.Gateways.Common.Policies.Handlers;
using {Company}.Gateways.Common.Policies.Requirements;
using Microsoft.AspNetCore.Authorization;

namespace {Company}.Gateways.Common.ServicesRegistration;

public static class PoliciesRegistrationExtensions
{
    public static void AddPolicies(
        this IServiceCollection services, ApiScope apiScope)
    {
        services.AddAuthorizationBuilder()
            .AddPolicy(Policy.Consumer, p => p.RequireClaim("scope", apiScope switch
            {
                ApiScope.Consumer => "consumer",
                ApiScope.PublicConsumer => "public_consumer",
                ApiScope.Management => "management_scope",
                _ => throw new ArgumentOutOfRangeException(
                    nameof(apiScope), "Invalid api scope selected."),
            }))
            .AddPolicy(Policy.Operator, p =>
                p.AddRequirements(new OperatorRequirement()))
            .AddPolicy(Policy.Reporter, p =>
                p.AddRequirements(new ReporterRequirement()))
            .AddPolicy(Policy.Manager, p =>
                p.AddRequirements(new ManagerRequirement()))
            .AddPolicy(Policy.ManagerOrReporter, p =>
                p.AddRequirements(new ManagerOrReporterRequirement()))
            .AddPolicy(Policy.OperatorOrReporter, p =>
                p.AddRequirements(new OperatorOrReporterRequirement()))
            .AddPolicy(Policy.FinancialManager, p =>
                p.AddRequirements(new FinancialManagerRequirement()));

        services.AddScoped<IAuthorizationHandler, OperatorHandler>();
        services.AddScoped<IAuthorizationHandler, ReporterHandler>();
        services.AddScoped<IAuthorizationHandler, ManagerHandler>();
        services.AddScoped<IAuthorizationHandler, ManagerOrReporterHandler>();
        services.AddScoped<IAuthorizationHandler, OperatorOrReporterHandler>();
        services.AddScoped<IAuthorizationHandler, FinancialManagerHandler>();
    }
}

Policy Constants

String constants used in [Authorize(Policy = ...)] attributes on controllers.

namespace {Company}.Gateways.Common.Constants;

public class Policy
{
    public const string Manager = "Manager";
    public const string Operator = "Operator";
    public const string Reporter = "Reporter";
    public const string ManagerOrReporter = "ManagerOrReporter";
    public const string OperatorOrReporter = "OperatorOrReporter";
    public const string FinancialManager = "FinancialManager";
    public const string Consumer = "Consumer";
    public const string PublicConsumer = "PublicConsumer";
}

Roles Constants

String constants used in [Authorize(Roles = ...)] attributes. Multiple roles are combined with commas via string interpolation.

namespace {Company}.Gateways.Common.Constants;

public static class Roles
{
    public const string SuperAdmin = "SuperAdmin";
    public const string Admin = "Admin";
    public const string Manager = "Manager";
    public const string Reporter = "Reporter";
    public const string FinancialManager = "FinancialManager";
    public const string Developer = "Developer";
    public const string LeadDeveloper = "LeadDeveloper";
}

Custom Authorization Requirement + Handler

Requirements are empty marker classes. Handlers resolve services from DI to perform complex authorization logic (e.g., checking subscriptions via gRPC).

namespace {Company}.Gateways.Common.Policies.Requirements;

public class OperatorRequirement : IAuthorizationRequirement { }

using {Company}.Gateways.Common.Constants;
using {Company}.Gateways.Common.Policies.Requirements;
using Microsoft.AspNetCore.Authorization;

namespace {Company}.Gateways.Common.Policies.Handlers;

public class OperatorHandler(
    SomeGrpcService grpcService) : AuthorizationHandler<OperatorRequirement>
{
    private readonly SomeGrpcService _grpcService = grpcService;

    protected override async Task HandleRequirementAsync(
        AuthorizationHandlerContext context, OperatorRequirement requirement)
    {
        if (context.User.IsInRole(Roles.Admin))
        {
            context.Succeed(requirement);
        }
        else
        {
            var isOperator = await _grpcService.HasPermissionAsync(
                userId: context.User.FindFirstValue(ClaimTypes.NameIdentifier));

            if (isOperator)
                context.Succeed(requirement);
        }
    }
}

Controller Authorization — Three Patterns

// Pattern 1: Default [Authorize] — requires authenticated user (from ControllerBaseV1)
[Route(DefaultRoute)]
[Authorize]
public class ProductsController(...) : ControllerBaseV1

// Pattern 2: Policy-based — requires specific policy
[Route(DefaultRoute)]
[Authorize(Policy = Policy.Operator)]
public class OrdersController(...) : ControllerBaseV1

// Pattern 3: Role-based — requires specific roles (comma-separated)
[Route(DefaultRoute)]
[Authorize(Roles = $"{Roles.SuperAdmin},{Roles.Admin}")]
public class AdminController(...) : ControllerBaseV1

Program.cs Usage

builder.Services.AddPolicies(ApiScope.Management);
builder.Services.AddJwtAuthentication(builder.Configuration);

// ...

app.UseAuthentication();
app.UseAuthorization();

appsettings.json

{
  "Jwt": {
    "JwtAuthority": "https://identity.example.com",
    "JwtAudience": "gateway-api"
  }
}

Anti-Patterns

| Anti-Pattern | Correct Approach | |---|---| | Hardcoded roles in [Authorize] strings | Use Roles constants class | | Hardcoded policy names in attributes | Use Policy constants class | | Combining auth setup in one method | Separate AddJwtAuthentication and AddPolicies | | Registering handlers as Singleton | Register as AddScoped (handlers may use scoped services) | | Missing UseAuthentication before UseAuthorization | Order matters in middleware pipeline | | Complex logic in controller actions | Move to AuthorizationHandler<T> |

Detect Existing Patterns

# Find authentication setup
grep -r "AddJwtAuthentication\|AddAuthentication" --include="*.cs"

# Find policy registration
grep -r "AddPolicies\|AddAuthorizationBuilder" --include="*.cs"

# Find Authorize attributes
grep -r "\[Authorize" --include="*.cs" Controllers/

# Find policy/role constants
grep -r "class Policy\|class Roles" --include="*.cs"

# Find authorization handlers
grep -r "AuthorizationHandler<" --include="*.cs"

Adding to Existing Project

1. Check ApiScope passed in AddPolicies to understand the gateway type
2. Add new policy in AddPolicies with a new IAuthorizationRequirement
3. Create handler inheriting AuthorizationHandler<TRequirement>
4. Register handler as AddScoped<IAuthorizationHandler, THandler>()
5. Add constant to Policy class for the new policy name
6. Apply [Authorize(Policy = ...)] on controller or action
7. For role-based: add constant to Roles class and use [Authorize(Roles = ...)]