V2 관리 API
관리 API는 계정과 접근 통제를 관리하고 조직 및 플랫폼 인스턴스 정보를 조회하는 기능을 제공합니다. 호출할 작업의 OAuth 권한 범위와 실제 리소스 권한을 함께 확인합니다. API 인증에서 토큰과 작업 권한의 관계를 설명합니다.
사용자와 그룹
그룹을 볼 수 있는 조직 범위와 그룹의 구성원 목록은 서로 다른 정보입니다. 사용자 이메일 주소도 사용자 ID나 인증 영역 안에서 고유한 username을 대체하지 않습니다.
소속 관계와 만료
| 리소스 | 조회 방향 또는 역할 |
|---|---|
| GroupMembership | 사용자에서 소속 그룹 조회 |
| GroupMember | 그룹에서 사용자 또는 하위 그룹 조회, 구성원 추가와 제거 |
| GroupMembershipExpirationPolicy | 구성원을 추가할 때 적용할 만료 기간과 절대 시각 제약 |
직접 소속과 간접 소속의 조회 범위는 transitive로 구분합니다. 그룹 구성원의 재귀 조회와 만료 시각 조회에는 조합 제한이 있으므로 각 엔드포인트의 조건을 따릅니다.
인증 제공자와 외부 식별자
| 리소스 | 다루는 정보 |
|---|---|
| AuthenticationProvider | SAML/OIDC 제공자 설정 조회와 첫 로그인 전 사용자 및 그룹 등록 |
| UserProviderInfo | Foundry 사용자와 외부 인증 제공자의 사용자 ID 연결 |
| GroupProviderInfo | Foundry 그룹과 외부 인증 제공자의 그룹 ID 연결 |
userId와 groupId는 Foundry의 식별자입니다. providerId는 외부 제공자가 정한 사용자 또는 그룹 식별자이며, 제공자 설정 리소스를 식별하는 authenticationProviderRid와도 구분합니다. enrollmentRid는 대상 플랫폼 인스턴스의 RID입니다.
미리보기 API는 해당 요청에 preview=true를 지정해야 합니다. 현재 사용자 소속 그룹 조회처럼 특정 OAuth 권한 범위를 요구하지 않는 예외도 있으므로 모든 관리 API에 같은 권한 조건을 일괄 적용하지 않습니다.
보안 표지와 범주
| 리소스 | 다루는 작업 |
|---|---|
| MarkingCategory | 표지 범주 생성, 조회와 이름 및 설명 교체, 초기 범주 권한 |
| Marking | 표지 생성과 조회, 초기 구성원 및 역할, 보안 분류 문자열 파싱 |
| MarkingMember | 보안 표지 구성원 조회, 추가와 제거 |
| MarkingRoleAssignment | 표지 관리, 적용 및 제거 역할 조회와 변경 |
| CbacBanner | 분류 배너 문자열과 글자 및 배경색 조회 |
| CbacMarkingRestrictions | 선택 집합의 유효성, 사용자 표지 자격과 금지 및 필수 조건 조회 |
범주 및 표지 정보의 조회와 해당 표지로 보호한 데이터의 접근은 구분합니다. 보안 분류 파싱은 HTTP 요청이 성공해도 입력 문자열별 오류가 있을 수 있으므로 parsed와 errors를 함께 확인합니다.
보안 표지 구성원 조회는 GET이지만 표지 관리자에게만 허용되므로 api:admin-write가 필요합니다. 역할 할당 조회의 api:admin-read와 구분합니다. 조직 표지의 관리자는 일반 표지 역할 API가 아니라 조직 역할 API로 관리합니다.
조직과 역할
| 리소스 | 다루는 작업 |
|---|---|
| Organization | 조직 생성과 정보 조회, 이름 및 호스트 교체, 할당 가능한 역할 조회 |
| OrganizationRoleAssignment | 실제 역할 ID를 사용한 조직 권한 할당 조회, 추가와 제거 |
조직의 RID와 게스트 접근을 관리하는 기반 markingId를 구분합니다. 조직 역할을 추가하거나 제거할 때는 해당 조직의 사용 가능 역할 조회 결과에서 roleId를 선택합니다.
플랫폼 인스턴스와 호스트
| 리소스 | 다루는 작업 |
|---|---|
| Enrollment | RID 또는 현재 사용자의 기본 조직을 기준으로 플랫폼 인스턴스 조회 |
| EnrollmentRoleAssignment | 인스턴스 수준의 역할 할당 조회, 추가와 제거 |
| Host | 인스턴스에 접속할 수 있는 호스트 이름의 페이지 조회 |
인스턴스 역할과 조직 역할은 관리 대상이 다릅니다. 호스트 목록, 조직의 기본 호스트와 인증 제공자의 지원 호스트도 각각의 계약에 따라 사용합니다.