delon-acl

@delon/acl - Access Control List

Trigger patterns: "ACL", "permission", "role", "access control", "@delon/acl", "can", "ability"

Overview

@delon/acl provides a role-based access control (RBAC) system for ng-alain applications, controlling UI element visibility and feature access based on user roles and permissions.

Package: @delon/acl@20.1.0 Integrated with: @delon/auth for authentication

Core Concepts

1. ACLService - Permission Management

import { inject } from '@angular/core';
import { ACLService } from '@delon/acl';

@Component({
  selector: 'app-dashboard',
  standalone: true
})
export class DashboardComponent {
  private aclService = inject(ACLService);
  
  ngOnInit(): void {
    // Set user roles and permissions
    this.aclService.setRole(['admin', 'user']);
    this.aclService.setAbility(['task:create', 'task:edit', 'task:delete']);
    
    // Set full ACL configuration
    this.aclService.set({
      role: ['admin'],
      ability: ['task:create', 'task:edit'],
      mode: 'oneOf' // 'allOf' or 'oneOf'
    });
  }
  
  canEditTask(): boolean {
    return this.aclService.can('task:edit');
  }
  
  isAdmin(): boolean {
    return this.aclService.can({ role: ['admin'] });
  }
}

2. ACL Directives - Conditional UI

*aclIf Directive

import { ACLIfDirective } from '@delon/acl';

@Component({
  imports: [ACLIfDirective],
  template: `
    <!-- Show only if user has admin role -->
    <button *aclIf="'admin'" nz-button nzType="primary">
      管理設定
    </button>
    
    <!-- Show only if user has task:create ability -->
    <button *aclIf="'task:create'" nz-button>
      建立任務
    </button>
    
    <!-- Complex condition: admin OR task:delete permission -->
    <button *aclIf="deletePermission" nz-button nzDanger>
      刪除
    </button>
  `
})
export class TaskListComponent {
  deletePermission = {
    role: ['admin'],
    ability: ['task:delete'],
    mode: 'oneOf'
  };
}

ACL with @if (Angular 20)

@Component({
  template: `
    @if (canCreate()) {
      <button nz-button (click)="createTask()">
        建立任務
      </button>
    }
    
    @if (isAdmin()) {
      <nz-card>
        <h3>管理員面板</h3>
        <!-- admin-only content -->
      </nz-card>
    }
  `
})
export class DashboardComponent {
  private aclService = inject(ACLService);
  
  canCreate = signal(this.aclService.can('task:create'));
  isAdmin = signal(this.aclService.can({ role: ['admin'] }));
}

3. ACL Guards - Route Protection

import { inject } from '@angular/core';
import { CanActivateFn } from '@angular/router';
import { ACLService } from '@delon/acl';
import { Router } from '@angular/router';

// Role-based guard
export const adminGuard: CanActivateFn = () => {
  const aclService = inject(ACLService);
  const router = inject(Router);
  
  if (aclService.can({ role: ['admin'] })) {
    return true;
  }
  
  return router.parseUrl('/403');
};

// Ability-based guard
export const taskCreateGuard: CanActivateFn = () => {
  const aclService = inject(ACLService);
  const router = inject(Router);
  
  if (aclService.can('task:create')) {
    return true;
  }
  
  return router.parseUrl('/403');
};

// Complex permission guard
export const blueprintEditGuard: CanActivateFn = () => {
  const aclService = inject(ACLService);
  const router = inject(Router);
  
  const canEdit = aclService.can({
    role: ['admin', 'owner'],
    ability: ['blueprint:edit'],
    mode: 'oneOf'
  });
  
  return canEdit || router.parseUrl('/403');
};

Route Configuration:

import { Routes } from '@angular/router';

export const routes: Routes = [
  {
    path: 'admin',
    canActivate: [adminGuard],
    loadComponent: () => import('./admin/admin.component')
  },
  {
    path: 'tasks/create',
    canActivate: [taskCreateGuard],
    loadComponent: () => import('./tasks/create.component')
  },
  {
    path: 'blueprints/:id/edit',
    canActivate: [blueprintEditGuard],
    loadComponent: () => import('./blueprints/edit.component')
  }
];

Real-World Blueprint Integration

Permission Structure for ng-events(GigHub)

import { Injectable, inject } from '@angular/core';
import { ACLService } from '@delon/acl';
import { AuthService } from '@core/services/auth.service';
import { BlueprintMemberRepository } from '@core/data-access/blueprint-member.repository';

/**
 * ng-events(GigHub) permission format:
 * - Roles: 'owner', 'admin', 'member', 'viewer'
 * - Abilities: 'module:action' format
 *   Examples: 'task:create', 'task:edit', 'task:delete'
 *             'blueprint:edit', 'member:invite'
 */
@Injectable({ providedIn: 'root' })
export class PermissionService {
  private aclService = inject(ACLService);
  private authService = inject(AuthService);
  private memberRepo = inject(BlueprintMemberRepository);
  
  /**
   * Initialize permissions for a blueprint
   */
  async initBlueprintPermissions(blueprintId: string): Promise<void> {
    const userId = this.authService.currentUserId();
    if (!userId) {
      this.aclService.set({ role: [], ability: [] });
      return;
    }
    
    // Get user's membership
    const member = await this.memberRepo.findByUserAndBlueprint(
      userId,
      blueprintId
    );
    
    if (!member || member.status !== 'active') {
      this.aclService.set({ role: [], ability: [] });
      return;
    }
    
    // Set roles and permissions
    this.aclService.set({
      role: [member.role],
      ability: member.permissions || [],
      mode: 'oneOf'
    });
  }
  
  /**
   * Check if user can perform action
   */
  can(ability: string): boolean {
    return this.aclService.can(ability);
  }
  
  /**
   * Check if user has role
   */
  hasRole(role: string | string[]): boolean {
    return this.aclService.can({ role: Array.isArray(role) ? role : [role] });
  }
  
  /**
   * Check if user can edit task
   */
  canEditTask(task: Task): boolean {
    // Owner or admin can always edit
    if (this.hasRole(['owner', 'admin'])) {
      return true;
    }
    
    // Member can edit if they have permission AND are assigned
    return this.can('task:edit') && 
           task.assignedTo === this.authService.currentUserId();
  }
  
  /**
   * Check if user can delete task
   */
  canDeleteTask(): boolean {
    return this.hasRole(['owner', 'admin']) || this.can('task:delete');
  }
}

Component with Blueprint Permissions

import { Component, signal, computed, inject, OnInit } from '@angular/core';
import { ActivatedRoute } from '@angular/router';
import { PermissionService } from '@core/services/permission.service';
import { TaskService } from '@core/services/task.service';
import { ACLIfDirective } from '@delon/acl';

@Component({
  selector: 'app-task-detail',
  standalone: true,
  imports: [ACLIfDirective],
  template: `
    <nz-card>
      <h2>{{ task()?.title }}</h2>
      
      <!-- Show edit button if user can edit -->
      @if (canEdit()) {
        <button nz-button (click)="editTask()">
          編輯任務
        </button>
      }
      
      <!-- Show delete button if user can delete -->
      @if (canDelete()) {
        <button nz-button nzDanger (click)="deleteTask()">
          刪除任務
        </button>
      }
      
      <!-- Alternative: Using *aclIf directive -->
      <button *aclIf="'task:edit'" nz-button>
        編輯
      </button>
      
      <!-- Show admin panel if user is owner/admin -->
      @if (isOwnerOrAdmin()) {
        <nz-card>
          <h3>管理面板</h3>
          <!-- admin features -->
        </nz-card>
      }
    </nz-card>
  `
})
export class TaskDetailComponent implements OnInit {
  private route = inject(ActivatedRoute);
  private taskService = inject(TaskService);
  private permissionService = inject(PermissionService);
  
  task = signal<Task | null>(null);
  
  canEdit = computed(() => {
    const t = this.task();
    return t ? this.permissionService.canEditTask(t) : f