如何基于Postgres通过KeyCloak为应用数据库表单条记录分配访问权限

云上老周

2026-6-26

无需自定义提供者的Keycloak细粒度数据权限解决方案

针对你的场景，不用编写Keycloak自定义提供者，完全可以通过Keycloak内置的用户属性/角色能力 + 应用API层的权限校验来实现特定用户对应用数据库中特定记录的访问控制，以下是具体落地步骤：

核心思路

利用Keycloak给用户标记可访问的资源标识（比如记录ID），然后在API请求时，从用户的JWT令牌中取出这些标识，和请求的业务数据做匹配，或者直接带入数据库查询条件，实现细粒度权限控制。

1. 在Keycloak中配置用户与资源的关联

有两种简单的配置方式，根据你的资源规模选择：

方式一：用户自定义属性（适合资源数量少的场景）

进入Keycloak控制台，找到目标用户的详情页，切换到「属性」标签
添加键值对，比如键为allowed_note_ids，值为该用户可访问的笔记ID列表（用逗号分隔，如1,3,5）
保存后，用户的JWT令牌中会包含这个属性字段

方式二：专属角色（适合资源数量多或需要分组授权的场景）

在Keycloak领域中创建对应资源的专属角色，比如note_viewer_1（表示可查看ID为1的笔记）、note_editor_3（表示可编辑ID为3的笔记）
将这些角色分配给对应的用户
用户的JWT令牌中会包含这些角色的权限信息

2. 在API层实现权限校验

以Spring Boot + OAuth2的场景为例，核心是从认证后的用户信息中提取权限标识，再和请求的业务数据做校验：

单条资源的权限校验（比如查看单篇笔记）

@GetMapping("/notes/{id}")
public ResponseEntity<Note> getSingleNote(@PathVariable Long id, @AuthenticationPrincipal OAuth2User authUser) {
    // 方式一：用用户属性校验
    String allowedIdsStr = authUser.getAttribute("allowed_note_ids");
    List<String> allowedIds = Arrays.asList(allowedIdsStr.split(","));
    if (!allowedIds.contains(id.toString())) {
        return ResponseEntity.status(HttpStatus.FORBIDDEN).body(null);
    }

    // 方式二：用角色校验
    // boolean hasPermission = authUser.getAuthorities().stream()
    //     .anyMatch(auth -> auth.getAuthority().equals("ROLE_note_viewer_" + id));
    // if (!hasPermission) {
    //     return ResponseEntity.status(HttpStatus.FORBIDDEN).body(null);
    // }

    // 从应用数据库查询并返回数据
    Note targetNote = noteRepository.findById(id).orElseThrow(() -> new RuntimeException("笔记不存在"));
    return ResponseEntity.ok(targetNote);
}

批量资源的权限过滤（比如获取用户可访问的笔记列表）

注意不要先查询所有数据再过滤，要把权限条件带入SQL，提升性能：

@GetMapping("/notes")
public ResponseEntity<List<Note>> getUserNotes(@AuthenticationPrincipal OAuth2User authUser) {
    String allowedIdsStr = authUser.getAttribute("allowed_note_ids");
    List<Long> allowedIds = Arrays.stream(allowedIdsStr.split(","))
        .map(Long::parseLong)
        .collect(Collectors.toList());
    
    // 直接用ID列表查询应用数据库
    List<Note> accessibleNotes = noteRepository.findByIdIn(allowedIds);
    return ResponseEntity.ok(accessibleNotes);
}

3. 可选优化：抽离校验逻辑

如果多个API都需要权限校验，可以把逻辑抽成自定义注解或切面，避免代码重复：

自定义权限校验注解

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface CheckNotePermission {}

切面实现统一校验

@Aspect
@Component
public class NotePermissionAspect {
    @Around("@annotation(CheckNotePermission)")
    public Object checkPermission(ProceedingJoinPoint joinPoint) throws Throwable {
        // 从SecurityContext获取当前认证用户
        OAuth2User authUser = (OAuth2User) SecurityContextHolder.getContext().getAuthentication().getPrincipal();
        // 从方法参数中提取笔记ID
        Long noteId = extractNoteIdFromArgs(joinPoint.getArgs());
        
        // 执行权限校验逻辑（复用之前的代码）
        String allowedIdsStr = authUser.getAttribute("allowed_note_ids");
        List<String> allowedIds = Arrays.asList(allowedIdsStr.split(","));
        if (!allowedIds.contains(noteId.toString())) {
            throw new AccessDeniedException("无该笔记的访问权限");
        }
        
        return joinPoint.proceed();
    }

    private Long extractNoteIdFromArgs(Object[] args) {
        // 根据实际参数位置提取ID，这里假设第一个参数是ID
        return (Long) args[0];
    }
}

之后在API方法上加上@CheckNotePermission即可自动触发校验。

方案优缺点

优点：完全基于Keycloak内置能力，无需编写自定义提供者，实现成本低；权限逻辑完全在应用层控制，灵活度高，适配各种业务场景。
缺点：当资源数量极大时（比如上万条记录），用户属性存ID列表会过长，角色数量也会急剧增加，这种场景建议结合数据库存储用户-资源关联关系，但对于中小规模业务，该方案足够实用。

内容的提问来源于stack exchange，提问作者Андрей Дьячков