> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 서비스 주체

> 스튜디오와 해당 타이틀에 대한 Entra 서비스 주체의 PlayFab 액세스 권한을 부여, 검사 및 취소합니다.

`playfab service-principal` 명령 패밀리는 실험적 기능입니다. CLI 인터페이스는 피드백에 따라 변경되거나 제거될
수 있습니다.

CI(연속 통합) 파이프라인 또는 기타 무인 작업은 Microsoft Entra ID 서비스 주체로 로그인합니다.
[자동화(서비스 주체) 인증](https://docs.xbox.com/ko/tools/xbox-cli/authentication.md#automation-service-principal-authentication)을
참조하세요. PlayFab은 사람이 PlayFab 스튜디오에서 서비스 주체에 액세스 권한을 부여한 후에만 서비스 주체를
허용합니다. 이러한 명령은 해당 권한 부여를 관리합니다.

스튜디오에 대한 **Admin** 권한이 있는 로그인한 사람만 이러한 명령을 실행할 수 있습니다.
`XBOX_AUTHENTICATION__MODE`가 서비스 주체 모드를 선택하면 이러한 명령은 실행을 거부하므로, 대신
`xbox auth login`으로 로그인하세요.

| 명령 | PlayFab API 경로 | 설명 |
| - | - | - |
| `playfab service-principal list` | `/Studio/ListServicePrincipals` | 스튜디오에 등록된 서비스 주체를 나열합니다. |
| `playfab service-principal get` | `/Studio/GetServicePrincipalAccess` | 서비스 주체 하나의 권한 부여를 표시합니다. |
| `playfab service-principal set` | `/Studio/SetServicePrincipalAccess` | 필요한 경우 서비스 주체를 등록하고, 해당 권한 부여를 모두 **대체**합니다. |
| `playfab service-principal revoke` | `/Studio/DeleteServicePrincipalAccess` | 스튜디오에서 서비스 주체와 해당 권한 부여를 모두 제거합니다. 먼저 묻습니다. [안전 및 파괴적 작업](https://docs.xbox.com/ko/tools/xbox-cli/safety.md)을 참조하세요. |

| 명령 | 옵션 |
| - | - |
| `service-principal list` | `--studio-id`(필수), `--limit`(1-100), `--continuation-token`. |
| `service-principal get` | `--studio-id`, `--principal-tenant-id`, `--principal-object-id`(모두 필수). |
| `service-principal set` | `--studio-id`, `--principal-tenant-id`, `--principal-object-id`, `--display-name`, `--grants-file`(모두 필수), `--expected-version`. |
| `service-principal revoke` | `--studio-id`, `--principal-tenant-id`, `--principal-object-id`(모두 필수). |

`list`는 `--output table`을 허용하며, 다른 명령은 허용하지 않습니다. `list`는 한 페이지를 반환합니다. 더 많은
항목이 있으면 응답의 `ContinuationToken`이 설정되며, `--continuation-token`을 해당 값으로 설정하여 `list`를
다시 실행하면 다음 페이지를 가져옵니다.

## 식별자

* `--studio-id`는 권한 부여를 소유한 스튜디오를 지정합니다. 이러한 명령은 PlayFab 타이틀을 사용하지 않으므로
  `--playfab-title-id`와 저장된 컨텍스트가 적용되지 않습니다.
* `--principal-tenant-id`와 `--principal-object-id`는 서비스 주체를 식별합니다. 각각 서비스 주체의 Entra ID
  테넌트와, 앱 등록이 아닌 엔터프라이즈 애플리케이션의 개체 ID입니다. 서비스 주체로 로그인하면
  `xbox auth status`가 이를 `objectId`로 보고합니다.
* 애플리케이션(클라이언트) ID는 전달하지 않습니다. PlayFab은 서비스 주체의 첫 번째 토큰에서 이를 기록하며,
  `list`와 `get`은 이를 `ClientId`로 보고합니다.
* 전역 `--tenant-id` 및 `--client-id` 옵션은 액세스 권한을 부여하려는 서비스 주체가 아니라 자신의 로그인을
  구성합니다.

## 권한 부여 파일

> [!WARNING]
>
> `set`은 서비스 주체의 모든 권한 부여를 `--grants-file`의 내용으로 대체하며, 파일에서 생략된 스튜디오 권한이나
> 타이틀을 모두 제거합니다.

파일을 처음부터 작성하지 말고 현재 권한 부여에서 시작하세요. `get`의 출력을 저장하고, `StudioPermissions`와
`TitleGrants`를 편집한 다음, 해당 `Version`을 `--expected-version`으로 지정하여 `set`에 전달하세요.

```bash theme={null}
xbox playfab service-principal get \
  --studio-id 1234567890ABCDEF \
  --principal-tenant-id 22222222-3333-4444-5555-666666666666 \
  --principal-object-id 33333333-4444-5555-6666-777777777777 \
  > grants.json
```

권한 부여 파일은 `get`의 전체 출력, 그 `data`, 그 안의 `ServicePrincipal` 개체 또는 권한 부여만일 수 있습니다.

```json theme={null}
{
  "StudioPermissions": [],
  "TitleGrants": [
    { "TitleId": "ABC123", "Permissions": ["Admin"] }
  ]
}
```

* 두 속성 모두 필수입니다. 빈 목록은 해당 종류의 권한을 부여하지 않습니다.
* 각 타이틀에는 권한이 하나 이상 필요합니다. 타이틀의 권한 부여를 제거하려면 해당 타이틀을 생략하세요.
* 속성 이름은 대/소문자를 구분하지 않습니다. 인식할 수 없는 속성은 오류이므로, 철자가 틀린 `TitleGrants`로
  인해 모든 타이틀 권한 부여가 제거되는 일은 없습니다.
* 파일에 `TenantId`, `ObjectId`, `DisplayName`이 있으면 각각 `--principal-tenant-id`, `--principal-object-id`,
  `--display-name`과 일치해야 합니다. 서비스 주체의 이름을 바꾸려면 파일의 `DisplayName`도 변경하거나
  제거하세요.

### 예상 버전

서비스 주체의 권한 부여가 변경될 때마다 새 `Version`이 부여되며, `get`과 `set`이 이를 반환합니다.
`--expected-version`을 사용하면 권한 부여가 여전히 해당 버전인 경우에만 `set`이 변경하므로, 권한 부여를 읽은
후 다른 사람이 변경한 내용을 되돌릴 수 없습니다. `--expected-version 0`은 서비스 주체에 아직 액세스 권한이
없어야 함을 요구합니다. `--expected-version`이 없으면 `set`은 현재 상태와 관계없이 권한 부여를 대체합니다.

권한 부여 파일에 `Version`이 있으면 `--expected-version`이 필요하며 그 값과 같아야 합니다. 값이 다르면
`get`을 다시 실행하고 해당 출력에서 편집을 다시 수행하세요. 어떤 경우든 권한 부여를 대체하려면 파일에서
`Version`을 제거하고 `--expected-version`을 생략하세요.

### `set`이 실패하는 경우

> [!WARNING]
>
> `set`이 실패하면 `set`이 성공할 때까지 서비스 주체에 스튜디오 액세스 권한이 없을 수 있으며, 이로 인해
> 파이프라인이 중단될 수 있습니다.

실패는 권한 부여가 변경되었는지 알려 주지 않으므로, 이전 버전으로 `set`을 다시 실행하지 마세요. `get`을
실행하여 권한 부여와 `Version`을 확인하고, 설정하려던 내용과 다르면 해당 출력을 편집하여 그 `Version`을
`--expected-version`으로 지정해 `set`에 전달하세요.

## 예제

스튜디오의 서비스 주체를 나열하고, 그중 하나의 권한 부여를 표시합니다.

```bash theme={null}
xbox playfab service-principal list \
  --studio-id 1234567890ABCDEF

xbox playfab service-principal get \
  --studio-id 1234567890ABCDEF \
  --principal-tenant-id 22222222-3333-4444-5555-666666666666 \
  --principal-object-id 33333333-4444-5555-6666-777777777777
```

`get`에서 저장하여 편집한 `grants.json`의 권한 부여로 서비스 주체의 권한 부여를 대체합니다.

```bash theme={null}
xbox playfab service-principal set \
  --studio-id 1234567890ABCDEF \
  --principal-tenant-id 22222222-3333-4444-5555-666666666666 \
  --principal-object-id 33333333-4444-5555-6666-777777777777 \
  --display-name "Nod Publishers build" \
  --grants-file grants.json \
  --expected-version 3
```

스튜디오에서 서비스 주체와 해당 권한 부여를 제거합니다.

```bash theme={null}
xbox playfab service-principal revoke \
  --studio-id 1234567890ABCDEF \
  --principal-tenant-id 22222222-3333-4444-5555-666666666666 \
  --principal-object-id 33333333-4444-5555-6666-777777777777 \
  --confirm
```

`revoke` 후에는 스튜디오에서 서비스 주체의 다음 PlayFab 요청이 실패합니다. `revoke`는 서비스 주체에 이미
액세스 권한이 없는 경우에도 성공합니다. 액세스 권한을 복원하려면 전체 권한 부여 집합으로 `set`을 실행하세요.


## Related topics

- [알려진 문제](https://docs.xbox.com/ko/tools/xbox-cli/known-issues.md)
- [인증](https://docs.xbox.com/ko/tools/xbox-cli/commands/auth.md)
- [첫 번째 플레이테스트](https://docs.xbox.com/ko/tools/xbox-cli/first-playtest.md)
- [컨텍스트](https://docs.xbox.com/ko/tools/xbox-cli/commands/context.md)
- [Nintendo 서비스 계정 주체 연결](https://docs.xbox.com/ko/services/playfab/api-references/rest/server/account-management/link-nintendo-service-account-subject.md)
