권한 관리 API 명세

개요

이 문서는 AccessCode 도메인의 권한 관리 API에 대한 세부 명세를 제공합니다. 권한 관리 API는 Access Code 관련 작업을 위한 사용자 권한을 관리하는 기능을 제공합니다.

API 정의

DTO 정의

ValidatePermissionDto

export class ValidatePermissionDto {
  @IsString()
  @ApiProperty({
    description: 'Access Code ID',
    example: 'code_789',
  })
  accessCodeId: string;

  @IsString()
  @ApiProperty({
    description: '수행할 작업',
    example: 'CREATE_CODE',
    enum: ['CREATE_CODE', 'READ_CODE', 'UPDATE_CODE', 'DELETE_CODE', 'USE_CODE'],
  })
  action: string;

  @IsString()
  @ApiProperty({
    description: '권한 범위 (조직 또는 팀 ID)',
    example: 'org_123',
  })
  scope: string;

  @IsString()
  @ApiProperty({
    description: '리소스 유형',
    example: 'access_code',
    enum: ['access_code', 'batch', 'user_registration'],
  })
  resource: string;
}

PermissionValidationResult

export class PermissionValidationResult {
  @ApiProperty({
    description: '권한 허용 여부',
    example: true,
  })
  allowed: boolean;

  @ApiProperty({
    description: '권한 범위',
    example: 'org_123',
  })
  scope: string;

  @ApiProperty({
    description: '보유한 권한 목록',
    example: ['CREATE_CODE', 'READ_CODE'],
    type: [String],
  })
  permissions: string[];
}

AssignPermissionDto

export class AssignPermissionDto {
  @IsString()
  @ApiProperty({
    description: '권한을 부여할 사용자 ID',
    example: 'user_123',
  })
  userId: string;

  @IsString()
  @ApiProperty({
    description: '권한 범위 (조직 또는 팀 ID)',
    example: 'org_123',
  })
  scope: string;

  @IsArray()
  @IsString({ each: true })
  @ApiProperty({
    description: '부여할 권한 목록',
    example: ['CREATE_CODE', 'READ_CODE'],
    type: [String],
  })
  permissions: string[];

  @IsOptional()
  @IsDateString()
  @ApiProperty({
    description: '권한 만료 시간 (13자리 Unix 타임스탬프)',
    example: 1735689599000,
    required: false,
  })
  expiresAt?: string;

  @IsOptional()
  @IsBoolean()
  @ApiProperty({
    description: 'IAM 서비스와 동기화 여부',
    example: true,
    required: false,
    default: false,
  })
  syncWithIam?: boolean;

  @IsString()
  @ApiProperty({
    description: '권한 생성자 ID',
    example: 'admin_456',
  })
  creatorId: string;
}

Permission

export class Permission {
  @ApiProperty({
    description: '권한 ID',
    example: 'perm_456',
  })
  id: string;

  @ApiProperty({
    description: '사용자 ID',
    example: 'user_123',
  })
  userId: string;

  @ApiProperty({
    description: '권한 범위',
    example: 'org_123',
  })
  scope: string;

  @ApiProperty({
    description: '권한 목록',
    example: ['CREATE_CODE', 'READ_CODE'],
    type: [String],
  })
  permissions: string[];

  @ApiProperty({
    description: '권한 부여 시간',
    example: 1711706400000,
  })
  grantedAt: number;

  @ApiProperty({
    description: '권한 만료 시간',
    example: 1735689599000,
    required: false,
  })
  expiresAt?: number;

  @ApiProperty({
    description: '권한 회수 시간',
    example: 1711710000000,
    required: false,
  })
  revokedAt?: number;

  @ApiProperty({
    description: '생성 시간',
    example: 1711706400000,
  })
  createdAt: number;

  @ApiProperty({
    description: '수정 시간',
    example: 1711706400000,
  })
  updatedAt: number;
}

RevokePermissionResult

export class RevokePermissionResult {
  @ApiProperty({
    description: '권한 ID',
    example: 'perm_456',
  })
  id: string;

  @ApiProperty({
    description: '권한 회수 시간',
    example: 1711710000000,
  })
  revokedAt: number;
}

권한 검증 API

요청

• 메서드: POST
• 경로: /v1/access-codes/permissions/validate
• 헤더:
  • Content-Type: application/json
  • Authorization: Bearer {token}
• 본문: ValidatePermissionDto

응답

• 성공 응답 (200 OK): PermissionValidationResult
• 오류 응답:
  • 401 Unauthorized: 인증 실패
  • 403 Forbidden: 권한 없음
  • 400 Bad Request: 잘못된 요청 형식

예시

요청:

POST /v1/access-codes/permissions/validate
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "accessCodeId": "code_789",
  "action": "CREATE_CODE",
  "scope": "org_123",
  "resource": "access_code"
}

응답:

{
  "allowed": true,
  "scope": "org_123",
  "permissions": ["CREATE_CODE", "READ_CODE"]
}

권한 할당 API

요청

• 메서드: POST
• 경로: /v1/access-codes/permissions/assign
• 헤더:
  • Content-Type: application/json
  • Authorization: Bearer {token}
  • X-Admin-Token: {admin_token}
• 본문: AssignPermissionDto

응답

• 성공 응답 (201 Created): Permission
• 오류 응답:
  • 401 Unauthorized: 인증 실패
  • 403 Forbidden: 권한 없음
  • 400 Bad Request: 잘못된 요청 형식
  • 409 Conflict: 중복된 권한

예시

요청:

POST /v1/access-codes/permissions/assign
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
X-Admin-Token: admin-token-xyz

{
  "userId": "user_123",
  "scope": "org_123",
  "permissions": ["CREATE_CODE", "READ_CODE"],
  "expiresAt": 1735689599000,
  "syncWithIam": true,
  "creatorId": "admin_456"
}

응답:

{
  "id": "perm_456",
  "userId": "user_123",
  "scope": "org_123",
  "permissions": ["CREATE_CODE", "READ_CODE"],
  "grantedAt": 1711706400000,
  "expiresAt": 1735689599000,
  "createdAt": 1711706400000,
  "updatedAt": 1711706400000
}

권한 회수 API

요청

• 메서드: DELETE
• 경로: /v1/access-codes/permissions/{permissionId}
• 헤더:
  • Authorization: Bearer {token}
  • X-Admin-Token: {admin_token}
• 파라미터:
  • permissionId: 회수할 권한 ID

응답

• 성공 응답 (200 OK): RevokePermissionResult
• 오류 응답:
  • 401 Unauthorized: 인증 실패
  • 403 Forbidden: 권한 없음
  • 404 Not Found: 권한 없음

예시

요청:

DELETE /v1/access-codes/permissions/perm_456
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
X-Admin-Token: admin-token-xyz

응답:

{
  "id": "perm_456",
  "revokedAt": 1711710000000
}

권한 조회 API

요청

• 메서드: GET
• 경로: /v1/access-codes/permissions
• 헤더:
  • Authorization: Bearer {token}
• 쿼리 파라미터:
  • userId (선택): 사용자 ID로 필터링
  • scope (선택): 권한 범위로 필터링
  • page (선택, 기본값: 1): 페이지 번호
  • size (선택, 기본값: 10): 페이지 크기

응답

• 성공 응답 (200 OK): Permission 목록과 페이지네이션 정보
• 오류 응답:
  • 401 Unauthorized: 인증 실패
  • 403 Forbidden: 권한 없음

예시

요청:

GET /v1/access-codes/permissions?userId=user_123&scope=org_123&page=1&size=10
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

응답:

{
  "items": [
    {
      "id": "perm_456",
      "userId": "user_123",
      "scope": "org_123",
      "permissions": ["CREATE_CODE", "READ_CODE"],
      "grantedAt": 1711706400000,
      "expiresAt": 1735689599000,
      "createdAt": 1711706400000,
      "updatedAt": 1711706400000
    }
  ],
  "metadata": {
    "totalCount": 42,
    "currentPage": 1,
    "pageSize": 10,
    "totalPages": 5
  }
}

권한 레벨

Access Code 도메인에서는 다음과 같은 권한 레벨을 정의합니다:

권한	설명	가능한 작업
CREATE_CODE	Access Code 생성 권한	새 Access Code 생성
READ_CODE	Access Code 조회 권한	Access Code 목록 조회, 상세 조회
UPDATE_CODE	Access Code 수정 권한	Access Code 활성화/비활성화, 상태 변경
DELETE_CODE	Access Code 삭제 권한	Access Code 삭제
USE_CODE	Access Code 사용 권한	Access Code 검증, 사용 처리
MANAGE_BATCH	일괄 작업 관리 권한	대량 코드 생성, 일괄 비활성화
VIEW_REPORTS	보고서 조회 권한	사용 통계, 상태 보고서 조회
ADMIN	관리자 권한	모든 작업 가능, 권한 관리 포함

오류 코드

권한 관련 오류 코드

HTTP 상태 코드	오류 코드	메시지	설명	대응 방법
403	2001	INVALID_PERMISSION	요청한 작업에 대한 권한이 없음	권한을 확인하거나 관리자에게 문의
403	2002	PERMISSION_EXPIRED	권한이 만료됨	권한을 갱신하거나 관리자에게 문의
400	2003	INVALID_SCOPE	권한 범위가 유효하지 않음	권한 범위를 확인하고 다시 시도
404	2004	SCOPE_NOT_FOUND	요청한 권한 범위가 존재하지 않음	권한 범위를 확인하고 다시 시도
404	2005	PERMISSION_NOT_FOUND	요청한 권한을 찾을 수 없음	권한 ID를 확인하고 다시 시도
409	2006	PERMISSION_ALREADY_EXISTS	동일한 권한이 이미 존재함	기존 권한을 확인하고 중복 제거
400	2007	INVALID_PERMISSION_FORMAT	권한 형식이 유효하지 않음	권한 형식을 확인하고 다시 시도

권한 문서화

권한 설명

각 API 엔드포인트는 필요한 권한을 명확히 문서화해야 합니다:

POST /v1/access-codes
필요 권한: CREATE_CODE
권한 범위: 해당 조직(scope)

액세스 제어 포인트

액세스 제어가 적용되는 주요 지점:

1. API 게이트웨이 레벨:

   • 인증 토큰 검증
   • 기본적인 역할 기반 접근 제어

2. 서비스 레벨:

   • 세분화된 권한 검증
   • 조직/팀 범위 검증
   • 리소스 소유권 검증

3. 데이터 레벨:

   • 행 수준 보안
   • 필드 수준 접근 제어

변경 이력

버전	날짜	작성자	변경 내용
0.1.0	2025-04-01	bok@weltcorp.com	최초 작성