Authorization (RBAC)

The @ithena-one/mcp-governance SDK provides a flexible Role-Based Access Control (RBAC) system integrated into its processing pipeline.

Enabling RBAC

To enable authorization checks, set the enableRbac option to true in the GovernedServerOptions.

const options: GovernedServerOptions = {
    // ... other options
    enableRbac: true,
    identityResolver: myIdentityResolver, // REQUIRED for RBAC
    roleStore: myRoleStore,             // REQUIRED for RBAC
    permissionStore: myPermissionStore,   // REQUIRED for RBAC
    // derivePermission: myPermissionDeriver, // Optional: Defaults work often
};
 
const governedServer = new GovernedServer(baseServer, options);

RBAC Pipeline Steps

When RBAC is enabled, the following steps occur during the request pipeline (after Identity Resolution):

(See Core Concepts for the full pipeline diagram)

Components

RBAC relies on these key interfaces:

• IdentityResolver: Resolves the caller’s UserIdentity. Must return non-null for RBAC checks. (See Interfaces)
• RoleStore: Maps a UserIdentity to a list of role strings (string[]). (See Interfaces)
• PermissionStore: Determines if a role grants a permission. (See Interfaces)

Permission Strings

Permissions are simple strings representing actions, generated by the derivePermission function.

• Default Logic (defaultDerivePermission): Generates strings based on MCP methods and parameters (e.g., tool:call:cleanup, resource:read:db://orders/123). Certain methods like ping return null to skip checks.
• Custom Logic: Provide your own derivePermission function in GovernedServerOptions for more granular control based on request details or context.

// Example Custom derivePermission
function myDerivePermission(request: Request, transportCtx: TransportContext): string | null {
    if (request.method === 'tools/call') {
        const toolName = request.params?.name;
        // Add extra check based on IP for a specific tool
        if (toolName === 'internal_admin_tool' && transportCtx.remoteAddress !== '192.168.1.10') {
             // Let PermissionStore handle the actual grant/deny based on role,
             // but derive a specific permission for internal access.
             return `internal:tool:call:${toolName}`;
        }
        // Fallback to default-like logic for other tools
        return toolName ? `tool:call:${toolName}` : null;
    }
    // Use default for other methods (or add more custom logic)
    return defaultDerivePermission(request, transportCtx);
}
 
const options: GovernedServerOptions = {
    // ...
    enableRbac: true,
    derivePermission: myDerivePermission,
    // ... other RBAC stores
};

Error Handling

Denied Request Auditing

By default (auditDeniedRequests: true), requests denied by RBAC are still logged by the AuditLogStore.

• AuditRecord.outcome.status will be 'denied'.
• AuditRecord.outcome.error and AuditRecord.authorization will contain details.
• Set auditDeniedRequests: false to disable auditing for denied requests.