Microsoft Store API를 사용하여 서비스 인증

이 항목에서는 위임된 인증 XSTS 토큰 또는 사용자 저장소 ID를 가져와 사용하여 Microsoft Store 서비스에 인증하는 방법에 대해 설명합니다.

다음 두 가지 방법으로 Microsoft Store API로 인증할 수 있습니다.

• 사용자 저장소 ID 및 Microsoft Entra ID: Microsoft Store 앱에 로그인한 사용자 계정에 인증 및 결과를 연결합니다.
• 위임된 인증 XSTS 토큰: 현재 게임을 하는 사용자의 Xbox 서비스 계정에 인증 및 결과를 연결합니다.

새 타이틀 및 서비스는 PC 타이틀과 Xbox 타이틀 모두에 대해 사용자 스토어 ID 인증 방법을 사용하는 것이 좋습니다. XSTS 토큰은 게임을 하는 사용자로 범위가 지정되며 경우에 따라 PC에서 구매 거래를 수행하는 계정이 아닐 수 있습니다. (자세한 내용은 PC에서 일치하지 않는 스토어 계정 시나리오 처리를 참조하세요.) 또한 XSTS 토큰은 반복 및 구매 서비스와 같은 일부 Microsoft Store 서비스에서 지원되지 않습니다. Microsoft Store의 향후 서비스 및 개발은 XSTS 토큰이 아닌 사용자 저장소 ID를 사용합니다.

플랫폼 간 상거래 솔루션 또는 서비스를 계획 중인 타이틀은 클라이언트 상호 작용 없이 갱신될 수 있으므로 사용자 스토어 ID를 사용해야 합니다. 서비스에 대한 XSTS 인증 흐름의 최대 수명은 활성 클라이언트에 대한 연결이 다시 필요하기 전까지 30일입니다.

다음은 앞에서 언급한 유형에서 적절한 권한을 얻는 방법에 대한 구성 및 리소스입니다.

위임된 인증 XSTS 토큰을 통한 인증

위임된 인증 XSTS 토큰은 요청의 Authorization 헤더를 다음 형식으로 추가하여 서비스 간 호출을 인증하는 데 사용할 수 있습니다.

Authorization: XBL3.0 x=<user hash>;<XSTS token>

XSTS 토큰에 대한 대상 신뢰 당사자는 레거시 Xbox 인벤토리 서비스와 동일하게 https://licensing.xboxlive.com이어야 합니다. 이전 서비스가 Xbox 인벤토리를 호출하도록 설정된 경우 이 끝점에서 동일한 토큰을 재사용할 수 있습니다. 생성된 서명이 지정된 끝점의 서명 정책과 일치하는 경우에는 서명 헤더 또한 필요합니다.

위임된 인증 XSTS 토큰 및 서명을 가져오고, 관리하고, 사용하는 방법에 대한 자세한 내용은 다음 리소스를 참조하세요.

• 게임 서비스 샘플: 클라이언트, 서버 간 인증, 상거래 서비스 등에서 XSTS 토큰의 유효성 검사 및 처리를 보여주는 포괄적인 웹 서비스 샘플입니다. GDK 다운로드 사이트에서 최신 버전을 다운로드합니다. 모든 샘플의 최신 릴리스를 다운로드하세요. 게임 서비스 샘플은 다운로드한 .zip 파일의 samples\Live\GameService 아래에 있습니다.
• Xfest 2019 - XSTS Auth and Server to Server made Easy XSTS 토큰의 개요와 게임 서비스 샘플에서 서비스 간 인증에 대한 작업을 시작하는 데 도움이 될 수 있는 방법에 대해 설명합니다. 프레젠테이션 정보를 다운로드하려면 아카이브 사이트에서 GDK 트랙 다운로드를 선택하세요.
• Xbox 서비스 인증 및 서비스 간 호출(NDA 항목)권한 부여 필요: 인증, XSTS 토큰, Xbox 서비스에 대한 서비스 간 호출을 수행하는 데 필요한 단계 및 호출에 대한 자세한 문서입니다.

위임된 인증 XSTS 토큰이 있는 제품을 보고 관리하려면 추가 구성이 필요합니다.

위임된 인증 XSTS 토큰은 파트너 센터의 비즈니스 파트너에 연결되므로 확인하거나 관리하려는 제품은 XSTS 토큰도 연결된 비즈니스 파트너에 연결되어야 합니다. 이 작업은 항목을 제품으로 구성하고 파트너 센터의 게임의 Xbox 설정 페이지에서 대상 비즈니스 파트너가 선택되도록 하여 수행됩니다. 제품 그룹은 파트너 센터에 정의된 Studio ID에 연결되어 있습니다. Studio ID는 XSTS 토큰이 연결될 비즈니스 파트너와 동일한 ID를 가져야 합니다.

제품이 XSTS 토큰의 비즈니스 파트너 ID에 제대로 연결되지 않은 경우의 가장 일반적인 증상은 Collections에 대한 호출은 성공하지만 결과에 항목이 없는 것입니다. (자세한 내용은 포럼 게시물 Collections LicensePreview 서비스에 대한 B2B 호출이 빈 결과를 반환함(파트너 센터 구성 게임)을 참조하세요.)

파트너 센터에서 제품 및 웹 서비스를 올바르게 구성하려면

1. 웹 서비스의 인증서 생성 링크를 사용하여 비즈니스 파트너 인증서를 생성합니다. (개발자 설정>Xbox Live>웹 서비스를 선택합니다) 신뢰 당사자가 연결된 웹 서비스 행에서 링크를 선택합니다.

2. 비즈니스 파트너 관리 UI(개발자 설정>Xbox Live>비즈니스 파트너 선택)로 이동하여 위에서 사용한 웹 서비스에서와 일치하는 비즈니스 파트너 ID를 복사합니다. (예시 비즈니스 파트너 ID: 12345678-9012-3456-7890-123456789012)

3. 제품의 파트너 센터 개요 페이지에서 새로 만들기를 선택한 다음 제품 그룹을 선택합니다.

4. 이 제품 그룹을 Dev Studio에 할당하거나 아직 없는 경우 새 개발자 스튜디오 만들기를 선택합니다.

5. 선택하거나 생성한 Dev Studio는 Studio ID가 이 지침의 2단계에서 검색한 비즈니스 파트너 ID와 일치해야 합니다. 이 값을 Dev Studio ID(선택 사항) 텍스트 상자에 복사합니다. 이 상자에 이미 값이 있는 경우 새 Dev Studio를 만들고 기존 값을 변경하지 않는 것이 좋습니다. 값이 변경되었지만 기존 타이틀에서 이미 사용 중인 경우 이 변경으로 인해 기존 서비스 및 B2B 호출이 실패할 수 있습니다.

6. 비즈니스 파트너의 일치하는 ID로 Dev Studio를 구성한 후 생성한 제품 그룹으로 돌아갑니다. 게임과 모든 제품을 이 제품 그룹에 포함됨 목록에 추가합니다.

7. 저장을 선택하여 제품 그룹 생성을 완료합니다.

8. 게임의 Xbox 설정 UI로 이동하여 연결된 비즈니스 파트너가 위의 단계에서 사용한 것과 동일한지 확인합니다.

9. 제품 그룹의 모든 항목을 샌드박스 또는 개발자 환경의 Microsoft Store에 다시 게시합니다.

게시 프로세스가 완료되면 서비스 호출에서 적절한 항목이 반환되는 것을 볼 수 있습니다.

Microsoft Entra ID 및 사용자 저장소 ID를 통해 인증

모든 Microsoft Store 서비스 API는 Microsoft Entra ID(이전의 Azure Active Directory) 및 사용자 저장소 ID를 통한 인증을 지원합니다. 이 인증 유형을 사용하려면 사용자(또는 조직)에게 Microsoft Entra ID 테넌트가 있어야 하며 그 아래에 애플리케이션 ID를 등록해야 합니다. 애플리케이션을 등록하려면 계정에 테넌트 아래에 전역 관리자 역할이 필요합니다. 이미 Microsoft Office 365 또는 Microsoft의 다른 비즈니스 서비스를 사용하는 경우 Azure Portal에서 관리할 수 있는 Microsoft Entra ID 테넌트가 이미 있습니다.

이 인증 유형에 필요한 사용자 저장소 ID를 가져오는 방법에 대한 지침은 서비스 대 서비스 인증을 위해 사용자 저장소 ID 요청을 참조하세요.

참고 항목

PC에서 자격은 현재 타이틀을 재생 중인 사용자 대신 Microsoft Store 앱에 로그인한 사용자와 연결됩니다. 이로 인해 계정이 다를 수 있으므로 PC 타이틀은 PC에서 일치하지 않는 매장 계정 시나리오 처리의 정보를 검토하는 것이 좋습니다.

Entra ID 흐름을 사용하여 Microsoft Store API를 호출하면 다음과 같이 요청 헤더에 Authorization Entra 액세스 토큰이 사용됩니다.

Authorization: Bearer <Entra ID access token>  

샌드박스에서 작업하는 경우 요청의 JSON 본문에 다음 클레임을 추가하여 샌드박스를 지정해야 합니다. 이 값이 없으면 결과의 샌드박스 범위는 기본적으로 RETAIL로 설정됩니다.

예:

  "sbx": "XDKS.1"

또한 클라이언트에서 가져온 사용자 저장소 ID를 사용하여 요청의 JSON 본문에 다음 표에 표시된 대로 매개 변수를 추가해야 합니다.

매개 변수	형식	설명	필수
identityType	string	문자열 값 b2b을 지정합니다.	예
identityValue	string	소모성 제품을 처리됨으로 보고할 사용자의 ID를 나타내는 사용자 Microsoft Store ID 키.	예
localTicketReference	string	반환된 응답에 대해 요청된 식별자입니다. User Store ID 키의 userIdclaim과 동일한 값을 사용하는 것이 좋습니다.	예

예:

  "beneficiaries": [
    {
        "identitytype" : "b2b",
        "identityValue" : "eyJ0eXAiOiJ...",
        "localTicketReference" : "testReference"
    }
  ],

User Store ID 인증을 받고, 관리하고, 사용하는 방법에 대한 자세한 내용은 다음 리소스를 참조하세요.

• Microsoft.StoreServices(GitHub): 자체 백엔드 서비스에서 Microsoft Store 서비스를 인증하고 호출하는 프로세스를 단순화하는 데 도움이 되는 소스 코드 및 라이브러리입니다. 이러한 서비스를 사용하면 Microsoft Store(Xbox 콘솔 포함) 내에서 앱이나 게임에 대한 사용자 구매를 확인하고 관리할 수 있습니다.
• Microsoft.StoreServices 샘플(GitHub): Microsoft.StoreServices 라이브러리를 사용하여 자체 백엔드 서비스에서 Microsoft Store 서비스를 인증하고 호출하는 프로세스를 단순화하는 웹 서비스 샘플입니다. 이 샘플은 또한 소모성 제품을 관리하고 환불된 구매를 Clawback 서비스로 조정하기 위한 예제 논리를 제공합니다.
• 서비스 간 인증을 위한 사용자 Microsoft Store ID 요청
• 사용자 Microsoft Store ID 키 갱신
• 서비스에서 제품 권한 관리

Microsoft Store API 호출 다이어그램

다음 다이어그램에서는 귀하의 서비스에서 사용자 Microsoft Store ID를 사용하는 Microsoft Store API를 호출하는 프로세스를 설명합니다.

사용자 저장소 ID/Microsoft Entra ID 인증을 사용하여 제품을 보고 관리하는 데 필요한 추가 구성

Microsoft Entra ID 인증 및 사용자 저장소 ID를 사용하도록 서비스를 설정할 때 파트너 센터의 게임 제품 컬렉션 및 구매 목록에 Entra 애플리케이션 클라이언트 ID를 추가해야 합니다. 컬렉션 및 구매 서비스를 호출할 때 제품과 추가 기능을 볼 수 있는 두 개의 개별 클라이언트 앱 ID를 설정할 수 있습니다. 제품이 Entra 애플리케이션 클라이언트 ID에 제대로 연결되지 않은 경우 가장 일반적인 증상은 컬렉션에 대한 호출이 성공하지만 결과에 항목이 없다는 것입니다.

Microsoft Entra ID 및 사용자 저장소 ID를 통해 서비스에 표시되도록 제품 구성

1. 게임의 파트너 센터 페이지 왼쪽 패널에서 제품 컬렉션 및 구매를 선택합니다.

2. 서비스를 인증하는 데 사용하는 Entra 애플리케이션의 클라이언트 ID를 입력합니다.

3. 저장 버튼을 클릭합니다.

4. 게임 제품 및 제품 아래의 모든 추가 기능을 샌드박스 또는 개발자 환경의 Microsoft Store에 다시 게시합니다.

게시 프로세스가 완료되면 서비스 호출에서 적절한 항목이 반환되는 것을 볼 수 있습니다.

참고 항목

Microsoft Store Service API

서비스 간 인증을 위한 사용자 Store ID 요청

사용자 Microsoft Store ID 키 갱신