메인 콘텐츠로 건너뛰기
XBOX CLI는 Microsoft Entra ID를 통해 개발자 계정으로 로그인합니다. Partner Center 워크플로의 경우 Partner Center 판매자에 대한 액세스 권한이 있는 계정으로 로그인합니다. 판매자를 선택하고 해당 판매자의 게임을 나열하는 방법은 시작하기를 참조하세요. PlayFab은 Partner Center 액세스와 별도로 자체 권한을 확인합니다. xbox playfab 명령에는 작업 대상 타이틀에 대한 Admin 권한이 필요합니다. PlayFab 인증 작동 방식을 참조하세요. 무인 작업은 대신 서비스 주체로 로그인할 수 있습니다. 자동화(서비스 주체) 인증을 참조하세요.

로그인

auth login은 로그인을 위해 시스템 브라우저를 연 다음, 계정과 해당 토큰의 만료 시간을 보고합니다.
CLI는 한 번에 하나의 계정을 사용합니다. 계정을 전환하려면 xbox auth login을 다시 실행하고 다른 계정을 선택합니다. 이후의 모든 명령은 해당 OS 사용자의 다른 터미널을 포함하여 이 계정을 사용합니다. Auth를 참조하세요.

상태 확인

auth status는 캐시된 계정과 해당 토큰을 표시합니다. PlayFab 또는 Partner Center를 사용할 수 있는지는 확인하지 않습니다.
스크립트에서는 --output json을 전달하고 signedIn을 확인합니다. 0이 아닌 종료 코드는 CLI가 설정 또는 토큰 캐시를 읽을 수 없었음을 의미합니다. 판매자 또는 PlayFab 타이틀과 같은 저장된 기본값은 로그인과 별개입니다. 컨텍스트를 참조하세요.

로그아웃

auth logout은 캐시된 계정과 토큰을 제거하여 해당 OS 사용자의 모든 터미널에서 로그아웃합니다. 저장된 컨텍스트는 유지됩니다.

토큰 캐시

명령은 캐시된 토큰을 재사용하고 새로 고치므로, CLI가 요청할 때만 xbox auth login을 다시 실행하세요. 토큰은 Windows 보호된 캐시, macOS 키 집합 또는 Linux Secret Service 키링에 저장됩니다. 헤드리스 컴퓨터처럼 사용 가능한 키링이 없는 Linux에서는 CLI가 경고를 표시하고 파일 권한으로만 보호되는 암호화되지 않은 파일을 사용합니다.

PlayFab 인증 작동 방식

xbox playfab 명령의 경우 CLI가 Entra ID 액세스 토큰을 PlayFab에 보내므로 PlayFab 타이틀 비밀 키를 직접 다룰 필요가 없습니다. PlayFab은 계정에 타이틀에 대한 Admin 권한이 있는지, 또는 playfab service-principal 명령의 경우 스튜디오에 대한 Admin 권한이 있는지 확인합니다. Studio Admin이 PlayFab의 Game Manager에서 기본 제공 Title Admin 역할 등으로 이 권한을 부여합니다. PlayFab 사용자 역할을 참조하세요. 서비스 주체는 사람이 xbox playfab service-principal set으로 권한을 부여한 경우에만 PlayFab 액세스 권한을 얻습니다. 서비스 주체는 권한 부여를 스스로 관리할 수 없습니다. 타이틀을 선택하고 PlayFab API를 호출하는 방법은 PlayFab API 통합을 참조하세요.

Entra ID 설정 재정의

로그인에 사용되는 Entra ID 애플리케이션은 CLI에 기본 제공됩니다. 대부분의 사용자는 이를 변경할 필요가 없습니다. XBOX_AZUREAD__CLIENTID와 같은 XBOX_AZUREAD__ 환경 변수를 사용하거나, 명령 하나에 대해 다음 옵션을 사용하여 AzureAd 설정을 재정의할 수 있습니다. 모든 설정은 구성을 참조하세요.

자동화(서비스 주체) 인증

서비스 주체는 로그인할 수 있고 auth status는 유효한 토큰을 보고하지만, 서비스가 서비스 주체를 수락할 때까지 해당 호출은 권한 부여 오류로 실패합니다. PlayFab은 사람이 xbox playfab service-principal set으로 액세스 권한을 부여한 후에 서비스 주체를 수락합니다. xbox game 및 xbox xbl처럼 온라인 서비스를 호출하는 다른 명령은 아직 서비스 주체를 수락하지 않습니다. 알려진 문제를 참조하세요.
CI(연속 통합) 파이프라인 및 기타 무인 작업은 브라우저 로그인을 완료할 수 없습니다. 대신 XBOX_AUTHENTICATION__MODE를 서비스 주체 모드로 설정하면, 각 명령은 구성된 앱 등록 또는 관리 ID로 앱 전용 Entra ID 토큰을 받습니다. 아무것도 캐시되지 않으며, auth login 및 auth logout은 실패합니다. 서비스 주체에는 저장된 컨텍스트가 없으므로 해당 옵션이나 XBOX_ 변수로 판매자와 타이틀을 전달합니다. 컨텍스트를 참조하세요.
  • TENANTID는 common, organizations 또는 consumers가 아니라 테넌트 GUID 또는 확인된 도메인이어야 합니다. CLIENTID는 GUID여야 합니다.
  • 이러한 설정은 환경 변수에서만 가져옵니다. 서비스 주체 모드에서는 --client-id 및 --tenant-id가 거부되지만, --scopes는 계속 적용됩니다.
  • azurecli 모드에서는 Azure CLI에 로그인하여 ID를 선택합니다. managedidentity 모드에서는 ID가 테넌트를 결정합니다.
  • CLI는 다른 모드나 캐시된 사용자 로그인으로 대체하지 않습니다. 알 수 없는 모드, 누락된 설정, 해당 모드에서 사용하지 않는 설정 또는 읽을 수 없는 자격 증명 파일은 해당 변수 이름을 명시하는 오류와 함께 실패합니다.
비밀은 파일로만 전달하고, 프로세스 목록과 로그를 통해 유출될 수 있는 환경 변수나 인수로는 절대 전달하지 마세요. 각 파일은 CLI를 실행하는 계정만 액세스할 수 있도록 제한하고, 작업이 끝나면 삭제하세요.

예

Linux 또는 macOS에서 파일에서 읽은 클라이언트 암호입니다. $RUNNER_TEMP는 GitHub Actions의 임시 폴더입니다. 다른 환경에서는 작업만 읽을 수 있는 파일을 사용하세요.
워크로드 ID 페더레이션을 사용하는 GitHub Actions 작업입니다. Entra ID 및 GitHub 설정은 GitHub Actions 설정을 참조하세요.
Azure CLI의 서비스 주체입니다(예: az login --service-principal 실행 후).
Azure CLI 로그인은 해당 OS 사용자의 모든 터미널에서 공유되므로, 서로 다른 ID로 로그인하는 동시 작업에는 각각 고유한 AZURE_CONFIG_DIR을 지정하세요. Azure Pipelines에서는 Azure Resource Manager 서비스 연결(가급적 워크로드 ID 페더레이션을 사용하는 연결)과 함께 AzureCLI@2 작업 내에서 xbox를 실행합니다. 서비스 연결이 테넌트와 ID를 선택하므로 XBOX_AUTHENTICATION__TENANTID 또는 XBOX_AUTHENTICATION__CLIENTID를 설정하지 마세요. 서비스 연결 이름을 사용자의 이름으로 바꾸세요.

GitHub Actions 설정

githuboidc 모드는 저장하거나 교체할 비밀 없이 GitHub Actions 작업을 Entra ID 테넌트의 서비스 주체로 로그인시킵니다. CLI가 GitHub에 작업의 OIDC 토큰을 요청하고, Entra ID는 해당 토큰이 앱 등록의 페더레이션 자격 증명과 일치하면 액세스 토큰으로 교환합니다. 페더레이션 자격 증명은 로그인할 수 있는 작업을 결정할 뿐, API에 대한 액세스 권한을 부여하지는 않습니다. 앱 등록, 해당 서비스 주체 및 리포지토리를 신뢰하는 페더레이션 자격 증명을 만들려면 Azure에서 OpenID Connect 구성 및 앱과 외부 ID 공급자 간의 트러스트 관계 만들기를 따르세요. CLI가 토큰을 직접 요청하고 Azure Resource Manager를 호출하지 않으므로, 해당 가이드의 azure/login 단계와 Azure 역할 할당은 건너뛰세요. 설정은 다음 요구 사항을 충족해야 합니다.
  • 페더레이션 자격 증명은 발급자 https://token.actions.githubusercontent.com 및 대상 그룹 api://AzureADTokenExchange를 사용합니다.
  • 해당 주체가 GitHub이 작업의 환경에 대해 발급하는 주체와 일치합니다. 이전 기본값은 repo:<OWNER>/<REPO>:environment:<ENVIRONMENT>입니다. GitHub.com에서 2026년 7월 15일 이후에 생성, 이름 변경 또는 이전된 리포지토리는 repo:<OWNER>@<OWNER-ID>/<REPO>@<REPO-ID>:environment:<ENVIRONMENT>를 사용합니다. GitHub의 변경 불가능한 주체 지침을 참조하세요. 조직과 리포지토리는 주체를 사용자 지정할 수도 있습니다.
  • 작업이 해당 환경과 permissions: id-token: write를 선언합니다. 환경이 없으면 GitHub이 분기 또는 끌어오기 요청 주체를 제시하며, Entra ID는 이를 거부합니다.
  • 작업이 XBOX_AUTHENTICATION__MODE, XBOX_AUTHENTICATION__TENANTID 및 XBOX_AUTHENTICATION__CLIENTID를 설정합니다. 예를 참조하세요. 테넌트 ID와 클라이언트 ID는 비밀이 아니므로 환경 변수로 저장하고 vars를 통해 읽으세요.
주체는 분기가 아니라 환경을 지정하므로, 환경의 보호 규칙이 로그인할 수 있는 사용자를 제어합니다. 프로덕션 환경은 보호된 분기로 제한하고 승인을 요구하세요. 환경 설정에서 해제하지 않는 한 관리자는 이러한 규칙을 우회할 수 있습니다. pull_request_target 워크플로는 기본 리포지토리의 권한으로 실행되며, 포크에서 온 끌어오기 요청에 대해서도 OIDC 토큰을 요청할 수 있습니다. 서비스 주체로 로그인할 수 있는 작업에서 신뢰할 수 없는 끌어오기 요청 코드를 체크아웃하거나 실행하지 마세요. 주체가 일치하지 않으면 Entra ID가 AADSTS700213(“No matching federated identity record found for presented assertion subject ’…’”)으로 토큰을 거부합니다. 오류에는 GitHub이 보낸 주체가 인용되므로 이를 자격 증명의 주체와 비교하세요. 각 환경의 설정을 해당 환경과 함께 보관하려면 XBOX_AUTHENTICATION__CLIENTID처럼 CLI의 변수 이름을 딴 GitHub 환경 변수로 저장하고, 변경하지 않고 그대로 CLI에 전달하세요.

ID 확인

서비스 주체 모드에서 auth status는 토큰을 받아 모드, 주체 유형, 테넌트, 앱 ID, 개체 ID, 대상 그룹 및 앱 역할을 보고합니다. 토큰은 출력하지 않습니다. 토큰을 받을 수 없으면 1로 종료되므로 이를 실행하는 파이프라인 단계가 실패합니다. Auth를 참조하세요. objectId는 앱 등록의 개체 ID가 아니라 서비스 주체의 개체 ID입니다. 서비스 주체에 PlayFab 액세스 권한을 부여하려면 이 값을 xbox playfab service-principal set에 --principal-object-id로 전달하세요.
마지막 수정일 2026년 11월 19일