IBeam.AccessControl 2.9.0

IBeam.AccessControl

IBeam.AccessControl contains the provider-neutral contracts and models for tenant-scoped access grants, permission-to-role mappings, and service-operation authorization. It is intentionally independent from IBeam.Identity so teams can use IBeam access control with their own authentication system.

When To Use This

• You need to describe access to tenant resources such as projects, products, workspaces, modules, or records.
• You want roles to map to stable permission names or IDs.
• You want service operations like pricing.save or coupons.delete to be authorized by configurable rules.
• You need user, API credential, and agent subjects to share one access model.

What This Package Contains

Architecture Fit

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

This package is the model/contract layer. Authorization decisions happen in IBeam.AccessControl.Services. Optional HTTP endpoints live in IBeam.AccessControl.Api. Optional Azure Table persistence lives in IBeam.AccessControl.Repositories.AzureTable.

Quick Start

Most apps should install this package through a service or API package. If you are building your own service layer, consume the contracts directly:

public sealed class ProjectAccessPolicy
{
    private readonly IResourceAccessAuthorizer _authorizer;

    public ProjectAccessPolicy(IResourceAccessAuthorizer authorizer)
    {
        _authorizer = authorizer;
    }

    public async Task RequireProjectEditAsync(Guid tenantId, string projectId, string userId, CancellationToken ct)
    {
        var result = await _authorizer.AuthorizeAsync(
            tenantId,
            "project",
            projectId,
            new AccessSubject(AccessSubjectTypes.User, userId),
            ResourceAccessLevels.Edit,
            ct);

        if (!result.Allowed)
            throw new UnauthorizedAccessException(result.Reason);
    }
}

Configuration

AccessControlOptions is bound from IBeam:AccessControl.

{
  "IBeam": {
    "AccessControl": {
      "EmitResourceAccessClaim": true,
      "MaxResourceAccessClaimsInJwt": 200,
      "AccessLevelRanks": {
        "view": 10,
        "edit": 20,
        "delete": 30,
        "manage": 40,
        "admin": 50,
        "owner": 60,
        "*": 2147483647
      }
    }
  }
}

Service Operations, Auditing, And Permissions

Service operation authorization uses stable operation names created in service-layer code:

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

Rules can then allow or deny names and patterns:

{
  "IBeam": {
    "Services": {
      "Authorization": {
        "Enabled": true,
        "DefaultMode": "require-permission",
        "Rules": [
          {
            "Pattern": "pricing.*",
            "Effect": "allow",
            "RoleNames": [ "Accounting" ]
          },
          {
            "Pattern": "coupons.delete",
            "Effect": "deny",
            "RoleNames": [ "Accounting" ],
            "Priority": 100
          }
        ]
      }
    }
  }
}

Data Storage

This core package does not create tables. It defines store interfaces only.

For Azure Table details, see ../IBeam.AccessControl.Repositories.AzureTable/README.md.

Extension Points

Package Relationships

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
• Roles, permissions, and grants: ../docs/roles-permissions-and-grants.md
• Core extraction review: ../docs/core-access-control-extraction-review.md
• Consuming API migration prompt: ../IBeam.AI.Enablement/examples/consuming-api-migration-prompt.md

Agents should read the AI prompt before adding permissions, grants, or service operation authorization behavior.

Troubleshooting

Version Notes

• Targets net10.0.
• Designed to support bring-your-own-auth.
• Package version is assigned by the repository release workflow.