IBeam.AccessControl.Services 2.9.1

IBeam.AccessControl.Services

IBeam.AccessControl.Services implements the service-layer access-control behavior for IBeam: resource grant management, resource authorization, permission-to-role mapping, service-operation allow/deny rules, and the bridge into IServiceOperationExecutor.

When To Use This

• You need runtime authorization for service operations such as pricing.save.
• You want to grant users, API credentials, or agents access to tenant resources.
• You need configurable role-to-permission mappings.
• You want access-control services without requiring IBeam.Identity.
• You want in-memory stores for tests/local hosts, with optional replacement stores for production.

What This Package Contains

Architecture Fit

API <-- DTO/model object --> Service <-- Entity --> Repository

This is the service layer. It owns access-control rules and authorization decisions. API projects should call these services rather than implementing access logic in controllers. Repository packages should persist grants/rules only and not decide whether access is allowed.

Quick Start

using IBeam.AccessControl.Services;

builder.Services.AddIBeamAccessControlServices(builder.Configuration);

Enable service-operation authorization:

{
  "IBeam": {
    "Services": {
      "Authorization": {
        "Enabled": true,
        "DefaultMode": "require-permission",
        "Rules": [
          {
            "Pattern": "transactions.*",
            "Effect": "allow",
            "RoleNames": [ "Accounting" ]
          }
        ],
        "EmergencyOverrides": [
          {
            "Pattern": "referralcodes.delete",
            "Effect": "deny",
            "RoleNames": [ "Accounting" ],
            "Priority": 1000
          }
        ]
      }
    }
  }
}

Dynamic permission management is optional:

builder.Services.AddIBeamServiceOperationPermissionManagement();

Common Usage

Grant resource access:

await resourceAccess.GrantAccessAsync(
    tenantId,
    new GrantResourceAccessRequest
    {
        ResourceType = "project",
        ResourceId = "platform",
        Subject = new AccessSubject(AccessSubjectTypes.User, userId.ToString("D")),
        AccessLevel = ResourceAccessLevels.Edit
    },
    createdByUserId,
    ct);

Map a permission to a role:

await permissionMaps.UpsertByPermissionNameAsync(
    tenantId,
    "pricing.save",
    new UpsertPermissionRoleMapRequest
    {
        RoleNames = [ "Accounting" ]
    },
    ct);

Add an operation rule:

await operationPermissions.UpsertRuleAsync(
    tenantId,
    new UpsertServiceOperationPermissionRequest
    {
        Pattern = "sales.*",
        Effect = ServiceOperationPermissionEffects.Deny,
        RoleNames = [ "Accounting" ],
        Priority = 100
    },
    updatedByUserId,
    ct);

Service Operations, Auditing, And Permissions

The management services in this package are tagged with IBeamOperation and routed through IServiceOperationExecutor.

Consuming services should use operation names that describe business actions:

[IBeamOperation("purchases.archive")]
public Task ArchiveAsync(Guid tenantId, Guid purchaseId, CancellationToken ct = default)
    => _operations.ExecuteAsync(
        this,
        token => ArchiveCoreAsync(tenantId, purchaseId, token),
        new ServiceOperationExecutionOptions
        {
            TenantId = tenantId,
            EntityId = purchaseId
        },
        ct);

Configuration

Data Storage

The default stores are in-memory. They are useful for local development and tests but should be replaced for production.

For Azure Table storage and schema, see ../IBeam.AccessControl.Repositories.AzureTable/README.md.

Extension Points

Extended Docs And Agent Guidance

• AI prompt: .agent/prompt.md
• Root implementation guide: ../.agent/implementation-guide.md
• Service operation permissions: ../docs/service-operation-permissions.md
• Service logging and audit: ../docs/service-logging-and-audit.md
• Roles, permissions, and grants: ../docs/roles-permissions-and-grants.md
• Consuming API migration prompt: ../IBeam.AI.Enablement/examples/consuming-api-migration-prompt.md

Troubleshooting

Version Notes

• Targets net10.0.
• Uses IBeam.Services operation/audit infrastructure.
• Package version is assigned by the repository release workflow.