사용자 지정 권한 규칙 정의
일부 사용 사례에서는 플러그인이 제공하는 규칙 외에 사용자 지정 규칙을 정의하고 싶을 수 있어요. 이전 섹션에서는 isEntityOwner 규칙을 사용해 카탈로그 엔티티에 대한 접근을 제어했어요. 이제 이 정책을 엔티티가 어떤 시스템의 일부인지 확인하는 사용자 지정 규칙으로 확장해 보겠어요.
출처: 문서
본문
일부 사용 사례에서는 플러그인이 제공하는 규칙 외에 사용자 지정 규칙을 정의하고 싶을 수 있어요. 이전 섹션에서는 isEntityOwner 규칙을 사용해 카탈로그 엔티티에 대한 접근을 제어했어요. 이제 이 정책을 엔티티가 어떤 시스템의 일부인지 확인하는 사용자 지정 규칙으로 확장해 보겠어요.
사용자 지정 규칙 정의
플러그인은 플러그인의 백엔드와의 호환성을 보장하는 타입 안전성을 제공하는 규칙 팩토리를 내보내야 해요. catalog 플러그인은 이를 위해 @backstage/plugin-catalog-backend/alpha에서 createCatalogPermissionRule을 내보내요. 참고: /alpha 경로 세그먼트는 이 API가 안정적으로 표시될 때까지 임시예요. 이 예시에서는 새 파일 permissionRules.ts에 규칙을 정의하고 조건을 만들 거예요. 이 파일을 권한 정책 모듈(Getting Started 섹션에서 yarn new로 스캐폴딩한 패키지)의 src/ 디렉터리에 만드세요.
권한 규칙 파라미터 스키마는 Standard Schema를 구현하고, 동기적으로 검증하며, JSON Schema 변환을 지원하는 라이브러리를 받아들여요. Async 정제와 변환은 지원되지 않아요. 아래 예시에서는 Zod v4와 @backstage/catalog-model을 사용해요. 설치하려면 Backstage 루트 디렉터리에서 다음을 실행하세요.
yarn --cwd plugins/permission-backend-module-custom add zod@4 @backstage/catalog-model
plugins/permission-backend-module-custom/src/permissionRules.ts
import type { Entity } from '@backstage/catalog-model';import { catalogEntityPermissionResourceRef } from '@backstage/plugin-catalog-node/alpha';import { createConditionFactory, createPermissionRule,} from '@backstage/plugin-permission-node';import * as z from 'zod';export const isInSystemRule = createPermissionRule({ name: 'IS_IN_SYSTEM', description: 'Checks if an entity is part of the system provided', resourceRef: catalogEntityPermissionResourceRef, paramsSchema: z.object({ systemRef: z .string() .describe('SystemRef to check the resource is part of'), }), apply: (resource: Entity, { systemRef }) => { if (!resource.relations) { return false; } return resource.relations .filter(relation => relation.type === 'partOf') .some(relation => relation.targetRef === systemRef); }, toQuery: ({ systemRef }) => ({ key: 'relations.partOf', values: [systemRef], }),});const isInSystem = createConditionFactory(isInSystemRule);...
규칙 정의에 대한 더 자세한 설명은 플러그인 작성자용 문서를 참고하세요.
규칙을 권한 정책 모듈의 src/ 디렉터리에 정의했으므로, 정책 클래스에서 조건을 직접 import할 수 있어요.
...import { isInSystem } from '../permissionRules';export class CustomPolicy implements PermissionPolicy { constructor(private readonly userInfo: UserInfoService) {} async handle( request: PolicyQuery, user?: PolicyQueryUser, ): Promise<PolicyDecision> { if (isResourcePermission(request.permission, 'catalog-entity')) { const ownershipRefs = user ? (await this.userInfo.getUserInfo(user.credentials)).ownershipEntityRefs : []; return createCatalogConditionalDecision( request.permission, catalogConditions.isEntityOwner({ claims: ownershipRefs, }), { anyOf: [ catalogConditions.isEntityOwner({ claims: ownershipRefs, }), isInSystem({ systemRef: 'interviewing' }), ], }, ); } return { result: AuthorizeResult.ALLOW }; }}
플러그인 설정 중 규칙 제공
이제 사용자 지정 규칙을 정의하고 정책에 추가했으니, 그것을 catalog 플러그인에 제공해야 해요. 이 단계는 중요해요. catalog 플러그인이 조건부 인가 결과를 평가하는 동안 규칙의 toQuery와 apply 메서드를 사용할 것이기 때문이에요. catalog와 permission 백엔드가 같은 서버에서 실행된다는 보장이 없으므로, 런타임에 사용할 수 있도록 규칙을 명시적으로 연결해야 해요.
경고
PermissionsRegistryService는 비교적 새로운 추가 사항이며, 아직 확장할 수 없는 이전의 createPermissionIntegrationRouter를 사용하고 있을 수 있는 모든 플러그인이 지원하는 것은 아니에요. 플러그인에 사용자 지정 규칙을 설치할 때 오류가 발생하면, 그 플러그인을 먼저 PermissionsRegistryService를 사용하도록 전환해야 할 수 있어요.
플러그인에 사용자 지정 규칙을 설치하려면 PermissionsRegistryService를 사용해야 해요. 위에서 만든 isInSystemRule을 catalog에 추가하기 위해 취해야 할 단계는 다음과 같아요.
isInSystemRule을 모듈의src/index.ts에 추가해 권한 정책 모듈에서 내보내기:
export { isInSystemRule } from './permissionRules';export { permissionModuleCustom as default } from './module';
packages/backend/src/extensions폴더에 다음 내용으로catalogPermissionRules.ts파일 만들기:
packages/backend/src/extensions/catalogPermissionRules.ts
import { coreServices, createBackendModule,} from '@backstage/backend-plugin-api';import { isInSystemRule } from '@internal/backstage-plugin-permission-backend-module-custom';export default createBackendModule({ pluginId: 'catalog', moduleId: 'permission-rules', register(reg) { reg.registerInit({ deps: { permissionsRegistry: coreServices.permissionsRegistry }, async init({ permissionsRegistry }) { permissionsRegistry.addPermissionRules([isInSystemRule]); }, }); },});
- 다음으로 다음 줄을 추가해 이것을 백엔드에 추가해야 해요:
packages/backend/src/index.ts
// catalog pluginbackend.add(import('@backstage/plugin-catalog-backend'));backend.add( import('@backstage/plugin-catalog-backend-module-scaffolder-entity-model'),);backend.add(import('./extensions/catalogPermissionRules'));
- 이제 Backstage 인스턴스를 실행하면 —
yarn start— 규칙이 catalog 플러그인에 추가돼요.
갱신된 정책은 다음 중 하나라도 참이면 카탈로그 엔티티 리소스 권한을 허용해요.
- 사용자가 대상 엔티티를 소유함
- 대상 엔티티가 'interviewing' 시스템의 일부임