Mahta.Utilities.Auth.ApiAuthorization 10.0.0

Mahta.Utilities.Auth.ApiAuthorization

Shared API authorization contracts for services that ask Access for authorization decisions.

Current scope:

• Runtime enforcement for services that ask Access for authorization decisions.
• References Mahta.Utilities.Auth.ApiAuthorization.Abstractions for decision contracts, enums, targets, and IRequestAuthorization.
• IAuthorizationSubjectAccessor for resolving the current authenticated caller as a human user or machine client.
• HttpContextAuthorizationSubjectAccessor as the default ASP.NET Core subject accessor.
• IAuthorizationActingAsAccessor for resolving the current UI-selected actor mode from request context.
• HttpContextAuthorizationActingAsAccessor as the default header-based acting-mode accessor.
• IAuthorizationDecisionRequestFactory for combining request metadata and current subject into an Access decision request.
• IApiAuthorizationEnforcer for executing the end-to-end decision flow without MVC/filter coupling.
• Global MVC authorization filter for actions whose request DTO has an IRequestAuthorizationRule<TRequest> or implements IRequestAuthorization.
• AllowUnauthorizedAttribute for explicitly skipping Mahta API authorization on an action or controller.
• IAuthorizationDecisionClient and ApiAuthorizationOptions for the future Access decision HTTP client boundary.
• HttpAuthorizationDecisionClient for posting decision requests to Access with the package OAuth token.
• Access decision HTTP client uses Steeltoe service discovery, so AccessServiceName may be a logical service name.
• OAuth settings are grouped under ApiAuthorizationOptions.OAuth for the Access decision call.
• OAuth uses Authority plus MetadataAddress; the token endpoint is discovered from the OpenID Connect metadata document.
• OAuth IgnoreSSL affects only the discovery/token HTTP client and should be treated as a temporary local or internal transition setting.
• Duende AccessTokenManagement owns client-credentials token acquisition, token caching, and bearer-token attachment.
• AddMahtaApiAuthorization(...) for registering options, request-building services, authorization rules, and the global MVC filter.
• Options are validated during registration/startup when authorization is enabled.

Endpoint enforcement is automatic for MVC actions that receive a request DTO with a registered authorization rule. The older IRequestAuthorization DTO style is still supported as a fallback.

Host configuration

Register the package from the host service. Prefer the config-section plus project base-name style:

builder.Services.AddMahtaApiAuthorization(
    builder.Configuration,
    "ApiAuthorization",
    "Access");

This scans runtime assemblies matching Access for IRequestAuthorizationRule<TRequest> implementations.

For tests or explicit setup, use the delegate overload:

builder.Services.AddMahtaApiAuthorization(
    options =>
    {
        options.Enabled = true;
        options.AccessServiceName = "Access";
        options.DecisionEndpoint = "/api/v2/Authorization/Decide";
    },
    "Access");

Example configuration:

{
  "ApiAuthorization": {
    "Enabled": true,
    "AccessServiceName": "Access",
    "DecisionEndpoint": "/api/v2/Authorization/Decide",
    "DecisionTimeoutSeconds": 10,
    "OAuth": {
      "Authority": "https://auth.mahtaengine.ir",
      "MetadataAddress": "https://auth:8443/.well-known/openid-configuration",
      "IgnoreSSL": true,
      "ClientId": "platform-internal",
      "ClientSecret": "...",
      "Scopes": [ "mahta_api" ]
    }
  }
}

Authority is the trusted token issuer. MetadataAddress is where the service can reach Auth discovery. The discovered token_endpoint is then used by Duende AccessTokenManagement to request and cache the package token.

Request rule usage

Keep request DTOs clean:

public class GetOrdersRequest : IQuery<PagedData<OrderDto>>
{
    public Guid TenantId { get; set; }
    public Guid CenterId { get; set; }
}

Put the authorization requirement in a small rule class:

public class GetOrdersAuthorizationRule
    : IRequestAuthorizationRule<GetOrdersRequest>
{
    public ValueTask<RequestAuthorizationRequirement> GetRequirementAsync(
        GetOrdersRequest request,
        CancellationToken cancellationToken = default)
        => ValueTask.FromResult(
            RequestAuthorizationRequirement.Require(
                AuthorizationTargets.Center(request.TenantId, request.CenterId),
                "orders.read"));
}

The global MVC filter protects the action automatically:

[HttpPost("orders/search")]
public Task<IActionResult> Search([FromBody] GetOrdersRequest request)
    => Query<GetOrdersRequest, PagedData<OrderDto>>(request);

The filter resolves IRequestAuthorizationRule<GetOrdersRequest>, builds an Access decision request from the current authenticated subject, and calls Access before the action body continues.

Request DTO fallback

API request DTOs declare authorization metadata by implementing IRequestAuthorization:

public class GetOrdersRequest : IRequestAuthorization
{
    public Guid TenantId { get; set; }
    public Guid CenterId { get; set; }

    public AuthorizationTarget AuthorizationTarget
        => AuthorizationTargets.Center(TenantId, CenterId);

    public IReadOnlyCollection<string> AuthorizationPermissions
        => [ "orders.read" ];
}

This style is still supported, but the rule style keeps DTOs cleaner:

[HttpPost("orders/search")]
public Task<IActionResult> Search([FromBody] GetOrdersRequest request)
    => Query<GetOrdersRequest, PagedData<OrderDto>>(request);

The filter builds an Access decision request from the current authenticated subject and the DTO metadata.

Use [AllowUnauthorized] to skip Mahta API authorization for a specific action or controller. This does not skip authentication or other ASP.NET authorization policies.

The UI/runtime supplies the human acting mode through a standard header, not through every request DTO:

X-Authorization-Acting-As: TenantMember

Valid values are TenantMember, PlatformMember, and PlatformSupport. Machine callers or requests without a UI mode can omit the header; the package sends Unspecified.