S2S 구성
이 섹션에서는 타이틀에 대한 XBOX 서비스의 S2S 호출 액세스에 대한 개요를 제공합니다. S2S 액세스는 각 타이틀에 대해 기본적으로 활성화되어 있지 않습니다. 액세스는 먼저 Partner Center에서 게시자 및 타이틀 수준에서 구성해야 합니다.비즈니스 파트너 인증서 설정
XBOX 서비스에 액세스하려면 타이틀 서비스에 XBOX 서비스에 등록된 자격 증명이 있어야 합니다. 이 액세스에는 비즈니스 파트너 인증서가 사용됩니다. 이 인증서는 XBOX 서비스 인증 기관(CA)에서 발급한 X509 인증서입니다. 비즈니스 파트너 인증서는 Partner Center의 XBOX 서비스 웹 서비스 페이지를 통해 게시자 수준에서 모든 샌드박스에 대해 구성됩니다. 자세한 구성 단계는 Partner Center에서 Single Sign-On 구성을 참조하세요.비즈니스 파트너 인증서 만료
다른 인증서와 마찬가지로 비즈니스 파트너 인증서는 만료됩니다. 만료 전에 업데이트해야 합니다. 현재 비즈니스 파트너 인증서는 생성 날짜로부터 약 18개월의 수명으로 생성됩니다. 향후 비즈니스 파트너 인증서의 수명이 변경될 수 있습니다. 만료된 비즈니스 파트너 인증서는 만료 날짜 이후 작동하지 않습니다. 이러한 인증서와 관련된 서비스 토큰(S 토큰) 또는 XSTS 토큰을 얻으려고 하면 오류가 발생합니다. 개발자는 사용 중인 비즈니스 파트너 인증서의 만료 날짜를 추적하고 만료되기 전에 Partner Center를 통해 새로 고쳐야 합니다. 비즈니스 파트너 인증서 만료 날짜 1주일 전에 새로 고침 및 새 인증서 배포를 위한 캘린더 알림을 설정하는 것이 좋습니다.비즈니스 파트너 인증서로 XBOX 서비스 액세스 구성
비즈니스 파트너 인증서가 있는 서버가 XBOX 서비스에 액세스할 수 있도록 하려면 각 타이틀이 비즈니스 파트너 인증서가 생성된 웹 서비스에 대한 액세스 권한을 부여해야 합니다. 이 구성은 Partner Center에서 타이틀별로 수행됩니다. 자세한 내용은 액세스 정책 개요를 참조하세요.위임된 S2S 구성
사용자를 대신하여 XBOX 서비스에 S2S 호출을 하려면 서비스 인증 및 신뢰 당사자에 대해 서비스가 이미 구성되어 있어야 합니다. 자세한 내용은 타이틀 서비스에 대한 XBOX 서비스 인증을 참조하세요. 위임된 S2S 호출 액세스의 경우 신뢰 당사자에 대한 토큰 정의에는DelegationToken 클레임도 포함되어야 합니다. 이 클레임에는 XSTS가 사용자를 대신하여 토큰을 발급하는 데 필요한 정보가 포함되어 있습니다.
사용자에 대한 위임 토큰은 발급된 후 30일 후에 만료됩니다. 이 토큰은 사용자가 로그인되어 있거나 사용자에 대한 요청이 필요한 동안에만 사용해야 합니다. 타이틀은 더 이상 필요하지 않은 위임 토큰을 삭제해야 합니다.
이 문서 상단으로 돌아가기.
서비스 인증 흐름
다음 다이어그램은 XBOX 서비스로 타이틀 서비스를 인증하는 세 가지 단계를 나타냅니다.
-
타이틀 서비스는 먼저 요청 본문에 샌드박스, 증명 키 및 토큰 유형을 명시하여 XBOX 서비스 인증 서비스(XSAS)에 인증 POST 요청을 수행합니다. 이전에 획득한 비즈니스 파트너 인증서는 클라이언트 TLS 인증서로 사용해야 합니다. 성공하면 XSAS는 기본 수명이 2주인 S 토큰을 반환합니다.
XSAS:
https://service.auth.xboxlive.com/service/authenticate -
그런 다음 S 토큰을 XSTS에 POST 요청을 하여 X 토큰이라는 인증 토큰으로 교환할 수 있습니다. 다음 매개 변수, 즉 S 토큰, 액세스하려는 샌드박스의 ID 및 대상 신뢰 당사자의 이름이 요청 속성으로 필요합니다.
XSTS:
https://xsts.auth.xboxlive.com/xsts/authorize -
필요에 따라 해당 클레임을 획득한 사용자를 대신하여 호출을 수행해야 하는 경우 요청에
DelegationToken클레임을 추가할 수 있습니다. 이 시나리오에서 제공된SandboxId는DelegationToken클레임의 사용자가 액세스할 수 있어야 합니다. 이런 식으로 획득한 X 토큰을 사용하여 서비스는 다양한 XBOX 서비스에 인증된 호출을 할 수 있습니다.
증명 키
증명 키를 사용하면 공격자가 토큰을 캡처하고 실제 토큰 소유자를 대신하여 메시지를 작성할 수 있는 중간자 공격을 방지할 수 있습니다. 증명 키 및 서명 생성의 전체 코드 샘플은 XBOX 개발자 다운로드에서 다운로드할 수 있는 GameService 콘솔 샘플을 참조하세요. 보다 구체적으로 보안 토큰을 획득할 때 호출자는 먼저 공개/개인 키 쌍을 생성합니다. 그런 다음 호출자는 개인 키를 자체적으로 보관하고 보안 토큰 요청과 함께 공개 키를 보냅니다(이 문서의 서비스 토큰 획득 섹션에서 나중에 설명함). 그런 다음 공개 키가 토큰에 포함됩니다. 호출자가 서비스에 요청을 보낼 때마다 토큰을 서비스에 전달하고 개인 키로 메시지에 서명합니다. 호출자만 개인 키를 가지고 있습니다. 메시지를 수신하는 서비스는 토큰의 유효성을 확인한 다음 토큰에 포함된 공개 키를 사용하여 요청의 서명 유효성을 검사합니다. 요청 서명이 검증되면 호출자에게 개인 키가 있음이 입증됩니다. 호출자가 개인 키를 안전하게 보관한다고 가정하면 이는 호출자가 보안 토큰 서비스에 공개 키를 제공한 당사자와 동일함을 증명합니다. 키 자체는 https://tools.ietf.org/html/draft-ietf-jose-json-web-key-08의 IETF(Internet Engineering Task Force) 사양에 정의된 JSON 웹 키(JWK)입니다. URL, 경로, 쿼리 문자열,Authorization 헤더 및 타임스탬프는 항상 서명됩니다. 결과적으로 이들은 요청 서명에 사용될 서명 정책에 암시적으로 포함됩니다. 인증 엔드포인트를 노출하는 각 서비스는 서명 정책에 포함되어야 하는 추가 헤더도 요구할 수 있습니다. 또한 서명될 요청 본문의 최대 크기(바이트)를 지정할 수도 있습니다. 각 서비스는 지원하는 서명 알고리즘 집합을 정의합니다.
서명 정책은 JSON 형식으로 다음과 같이 표시됩니다.
HTTP 헤더를 통해 전송되며 다음 세 부분으로 구성됩니다.
- 서명 정책 버전. 네트워크 바이트 순서(빅 엔디안)의 4바이트 정수 값으로 표현됩니다.
- 네트워크 바이트 순서의 64비트 Windows 파일 시간.
- 결과 서명 바이트.
Signature 헤더로 요청과 함께 전송됩니다.
서명은 HTTP 헤더로 전송되므로 본문의 해시를 포함하는 모든 메시지는 본문의 바이트가 요청 스트림에 기록되기 전에 메모리에서 해시되어야 합니다. 서명은 실제로 전송된 바이트에 대해 계산됩니다. 서명은 모든 요청 본문 변환 후에 계산되어야 합니다.
서명할 데이터 스트림을 만드는 정확한 프로세스는 다음과 같습니다. 헤더 및 URL과 같은 모든 문자열 데이터는 ASCII로 인코딩됩니다. 본문은 불투명한 blob이며 있는 그대로 서명됩니다.
이러한 요소의 값은 다음과 같이 설명됩니다.
- 네트워크 바이트 순서의 4바이트 부호 없는 정수로서의 정책 버전, 그 뒤에 null 바이트.
-
네트워크 바이트 순서의 타임스탬프(
Signature헤더에서), 그 뒤에 null 바이트. -
대문자의
HTTP메서드(예: GET 또는 POST), 그 뒤에 null 바이트. - 절대 경로 및 쿼리 문자열, 그 뒤에 null 바이트.
-
Authorization헤더의 값(있는 경우), 그 뒤에 null 바이트. - 서명 정책에 지정된 기타 헤더, 헤더를 추가하는 경우 각각 그 뒤에 null 바이트. 추가 헤더가 없으면 바이트를 추가하지 않아야 합니다.
-
호출할 엔드포인트에 대한 서명 정책에 지정된 대로 서명할 본문의 최대 바이트 수를
N이라고 합시다. 압축되지 않은 본문의 크기를M이라고 합시다.M \> N이면 압축되지 않은 본문의 첫 번째N바이트를 사용합니다.M \<= N이면 압축되지 않은 전체 본문(패딩 없음)을 사용합니다. null 바이트가 추가됩니다(요청 본문이 없더라도 null 바이트는 추가되어야 함).
HTTP 요청이 됩니다.
절대 경로와 쿼리 문자열은 서명된 요청의 URI에서 가져옵니다. 요청의 URI가 “https://service.xbox.com/service1/foo?q0=v0&q1=v1\#frag,”인 경우 절대 경로와 쿼리 문자열은 “/service1/foo?q0=v0&q1=v1\#frag”입니다. 절대 경로는 슬래시(/)로 시작해야 합니다.
정책에 지정된 요청의 헤더는 서명 정책에 나타나는 순서와 동일한 순서로 서명에 포함되어야 합니다. Authorization 헤더는 항상 서명됩니다. 정책이 요청에 없는 헤더를 지정하는 경우 서명에 포함할 필요가 없습니다. 예를 들어, 정책이 헤더 \[ H~1~, H~2~, H~3~ \]을 지정하고 요청에 H~1~ 및 H~2~만 포함되어 있으면 H~3~은 생략할 수 있습니다. 이는 전역 정책이 POST 요청에 적용되지 않는 Range와 같은 헤더를 지정하는 경우 필요합니다.
그러나 헤더가 누락된 경우에도 해당 null 바이트는 여전히 포함되어야 합니다. 이는 헤더가 지정되지 않은 경우에도 적용됩니다. H~2~가 누락된 경우 서명할 데이터 스트림에는 H~1~과 H~3~ 헤더 사이에 두 개의 null 바이트가 포함됩니다. 이를 다른 방식으로 생각하는 방법은 누락된 헤더를 빈 문자열로 간주하는 것입니다.
이 문서 상단으로 돌아가기.
서비스 토큰 획득
이 섹션에서는 서비스 토큰 획득과 관련된 요청, 응답 및 오류 처리에 대한 세부 정보를 다룹니다. 서비스 토큰 요청 및 관리의 전체 샘플 코드 구현은 XBOX 개발자 다운로드에서 다운로드할 수 있는 GameService 콘솔 샘플을 참조하세요.서비스 토큰 요청
XSAS는 서비스 인증을 처리하기 위해 다음 REST 엔드포인트를 제공합니다.https://service.auth.xboxlive.com/service/authenticate
이 엔드포인트에는 TLS 1.2(이상)와 요청에서 클라이언트 SSL 인증서로 사용되는 유효한 비즈니스 파트너 인증서가 필요합니다.
엔드포인트에 대한 연결이 끊긴 경우 일반적으로 이전 항목이 요청에서 누락되었거나 잘못 구성된 결과입니다.
서비스는 다음 XSASRequest 데이터 계약을 따르는 본문으로 POST를 수행합니다.
XSASRequest의 PropertyBag에서 유일한 필수 속성은 ProofKey입니다. 이 문서의 증명 키 섹션에 표시된 대로 JWK여야 합니다.
이 S 토큰에 대한 증명 키를 캐시하거나 기록해 두세요. S 토큰으로 얻은 토큰을 사용하여 XBOX 서비스에 대한 호출에 대한 서명을 생성하려면 해당 증명 키를 사용하세요.
다음은 샘플 요청에 대한 코드입니다.
x 및 y를 십진수 표현에서 16진수 표현으로 변환할 때 짝수 길이인지 확인하세요. 그렇지 않으면 잘못된 변환 길이가 발생하여 서비스에서 거부될 수 있습니다.
원시 형식은 r과 s가 단순히 연결되는 형식입니다. 이 형식에서 r 및 s는 먼저 어떤 규칙(일반적으로 빅 엔디안)을 사용하여 바이트 시퀀스로 표시되어야 하며, 값이 0x00인 추가 패딩 바이트가 있을 수 있습니다. 이렇게 하면 r 및 s 인코딩이 동일한 크기를 갖게 됩니다. r과 s 인코딩의 동일한 크기는 검증자가 이 데이터를 분할할 위치를 알기 위해 중요합니다.
DER 대신 원시 형식이 필요합니다. 이 원시 형식의 경우에도 0x00 패딩을 적용해야 합니다.
서비스 토큰 응답
응답에 대한 데이터 계약은 다음과 같습니다.서비스 토큰 오류 처리
증명 키 서명이 유효하지 않으면 서버는 403 오류를 반환합니다.SSL 채널이 성공적으로 설정되려면 비즈니스 파트너 인증서에 대한 전체 신뢰 인증서 체인이 클라이언트에 설치되어야 합니다. 인증서 체인이 게시됩니다. 비즈니스 파트너 인증서를 열고 인증 경로 탭을 선택한 다음 필요한 개별 인증서를 보거나 다운로드하여 적절한 인증서를 다운로드할 수 있습니다.
S2S 호출을 위한 XSTS 토큰 획득
이 섹션에서는 X 토큰 획득과 관련된 요청, 응답 및 오류 처리에 대한 세부 정보를 제공합니다. S2S 호출에 대한 XSTS 토큰 요청, 관리 및 사용의 전체 샘플 코드 구현은 XBOX 개발자 다운로드에서 다운로드할 수 있는 GameService 콘솔 샘플을 참조하세요. XBOX 서비스에 서비스를 인증하는 데 다음 두 가지 유형의 XSTS 토큰을 사용할 수 있습니다.- 서비스 인증 XSTS 토큰: 서비스의 ID만 포함하고 생성된 서비스 토큰을 사용하여 만들어집니다. 이 토큰은 문자열 확인, 멀티플레이어 및 삭제된 계정 서비스로 인증하는 데만 사용할 수 있습니다.
- 위임된 인증 XSTS 토큰: 사용자 클레임을 포함하며 대부분의 XBOX 서비스 및 Microsoft Store 서비스 인증에 필요합니다.
요청
XSTS 서비스는 인증을 처리하기 위해 다음 REST 엔드포인트를 제공합니다.https://xsts.auth.xboxlive.com/xsts/authorize
서비스는 다음 XSTSRequest 데이터 계약을 따르는 본문으로 POST를 수행합니다.
[!NOTE]
서비스 인증 XSTS 토큰을 획득할 때는 S 토큰만 제공합니다.
위임된 인증 XSTS 토큰의 경우 DelegationToken 값도 포함합니다. 여기에는 호출을 대신하는 사용자의 ID가 포함됩니다.
RelyingParty 속성
토큰은 특정 신뢰 당사자에 대해 발급(및 암호화)됩니다. 주어진 신뢰 당사자에 대해 구성된 서비스는 해당 신뢰 당사자에 대해 발급된 토큰만 사용할 수 있습니다. 따라서 호출해야 하는 XBOX 서비스에 따라 필요한 토큰을 검색할 때마다 관련된 신뢰 당사자를 지정하여 다른 토큰을 검색해야 할 수도 있습니다. 다음 표는 각 XBOX 서비스에 성공적으로 액세스하기 위해 어떤 신뢰 당사자에 대한 토큰을 가져와야 하는지 나타냅니다.
타이틀 엔드포인트에 대해 지정된 사용자 지정 신뢰 당사자(예: https://example.com/ 또는 rp://example.com/)에 대한 토큰을 검색할 수도 있습니다. XBOX 서비스 신뢰 당사자 이름과 달리 사용자 지정 신뢰 당사자 이름에는 후행 슬래시(/)가 있습니다.
PropertyBag 속성
XSTS에 대한PropertyBag 데이터 계약은 다음과 같습니다.
ServiceToken 속성에는 XSAS의 응답에서 Token 값이 포함됩니다.
SandboxId 속성에는 액세스하려는 샌드박스의 이름(예: “ABCD.1”)이 포함됩니다. 모든 소매 사용자 및 콘텐츠에 대한 기본 샌드박스의 이름은 “RETAIL”입니다. (이름은 대문자이며 대소문자를 구분합니다.) 서비스와 함께 클라이언트를 인증하는 데 사용되는 클라이언트 측 XSTS 토큰의 샌드박스 클레임을 찾아 언제든지 이를 동적으로 설정할 수 있습니다.
사용 중인 비즈니스 파트너 인증서가 특정 샌드박스에 대해 발급된 경우 여기에서도 동일한 값을 사용해야 합니다.
DelegationToken 속성은 이 시나리오에서 선택 사항이며 사용자를 대신하여 XBOX 서비스를 호출하는 경우에만 사용해야 합니다. 여기에서 이전에 XBOX One 콘솔이나 다른 클라이언트에서 받은 X 토큰에서 추출된 DelegationToken 클레임의 값을 포함해야 합니다. DelegationToken 클레임은 이 문서 앞부분의 위임된 S2S 구성 섹션에 자세히 설명된 대로 XSTS 토큰에 추가할 수 있습니다.
UserTokens 속성은 웹 서버가 비즈니스 파트너 인증서로 인증되고 사용자가 사용자 인증을 위한 Microsoft 계정 OAuth 흐름을 사용하여 웹사이트에 인증되는 웹사이트에서 XBOX 서비스에 호출을 하는 경우에만 사용해야 합니다. 이 경우 UserTokens 속성은 Microsoft 계정에서 검색된 사용자의 액세스 토큰을 XBOX 사용자용 인증 서비스(XASU) 서비스에서 사용자(U) 토큰으로 교환하여 검색된 토큰을 포함하는 하나의 요소 배열이어야 합니다.
헤더
서비스 인증 XSTS 토큰 요청 예제
다음은 샘플 요청에 대한 코드입니다.위임된 인증 XSTS 토큰 요청 예제
다음은 샘플 요청에 대한 코드입니다.위임된 인증 XSTS 토큰 응답
XSTS 응답에 대한 데이터 계약은 다음과 같습니다.DelegationToken 또는 UserTokens 속성이 지정되지 않은 경우 응답에는 표시 클레임이 포함되지 않습니다.
그렇지 않으면 응답의 DisplayClaims 속성에는 이전 데이터 계약에 정의된 사용자에 대한 정보 집합이 포함됩니다.
- Agegroup: Child, Teen 또는 Adult일 수 있습니다.
- Gamertag: 사용자의 게이머태그.
- Privileges: 사용자가 가지고 있는 권한 집합. (권한에 대한 자세한 내용은 XBOX 서비스 보안 토큰 클레임을 참조하세요.)
-
Xuid: 사용자의 XUID.
[!IMPORTANT] Microsoft(개발자 계정 관리자(DAM)를 통해)로부터 명시적 동의를 받지 않은 한 데이터베이스에 사용자 XUID를 저장하지 마세요.
-
UserHash: XBOX 서비스에 대한 요청에 대한
Authorization헤더를 구성할 때 사용할 사용자의 고유 식별자. 자세한 내용은 XBOX 서비스 엔드포인트 호출을 참조하세요.
DisplayClaims를 노출하는 것은 아닙니다. 모든 클레임 멤버를 받으려면 https://xboxlive.com 신뢰 당사자 이름을 사용하세요.
다음은 “https://xboxlive.com” 신뢰 당사자에 대한 샘플 응답에 대한 코드입니다.
위임된 인증 오류 처리
XSTS 토큰 요청이 거부되면 응답에는 경우에 따라 요청이 거부된 이유를 나타내는 데이터가 포함됩니다.Identity 및 Message 속성은 무시할 수 있습니다.
XErr 속성은 다음 값을 가질 수 있습니다.
이 문서 상단으로 돌아가기.
XBOX 서비스 엔드포인트 호출
이 섹션에서는 XBOX 서비스 호출을 위해 인증을 수행하는 방법을 설명합니다. XSTS 서비스에서 X 토큰을 획득하는 목적은 다양한 XBOX 서비스에 인증된 호출을 하는 것입니다. 호출이 성공하려면 이러한 서비스를 호출할 때Authorization 헤더와 Signature 헤더를 지정해야 합니다.
Authorization 헤더는 다음 구조를 취합니다.
authorization: XBL3.0 x=<userHash>;<XToken>
해당 헤더의 userHash 부분은 다음과 같이 설정해야 합니다.
-
XSTS 요청에서
DelegationToken또는UserTokens속성이 설정된 경우 XSTS 응답의DisplayClaims요소의UserHash속성을 사용해야 합니다.예:
XBL3.0 x=1077552597660441275;eyJlbmMiO...(truncated) -
XSTS 요청에서
ServiceToken만 지정된 경우UserHash속성을 하이픈(-)으로 설정해야 합니다.예:
XBL3.0 x=-;eyJlbmMiO...(truncated)
XToken 부분은 XSTS 응답의 Token 요소 값으로 설정해야 합니다. X 토큰에는 만료 날짜와 시간이 있습니다. XSTS 응답의 NotAfter 요소에 지정됩니다. 만료된 토큰을 사용하여 XBOX 서비스를 호출하면 HTTP 상태 401로 요청이 거부되고 응답의 www-authenticate 헤더에 토큰이 만료되었다는 표시가 나타납니다.
또한 XBOX 서비스에는 이 문서의 증명 키 섹션에 설명된 사양에 따라 계산된 메시지 서명이 필요합니다.
서비스에서 XBOX 서비스를 호출할 때 각 요청과 함께 새 토큰을 요청하는 대신 만료될 때까지 X 토큰을 재사용해야 합니다. 또한 소셜 호출과 같이 가능한 경우 호출을 일괄 처리하여 처리량을 늘리고 요청 제한을 피하세요.
XBOX 서비스 멀티플레이어 서비스 S2S 호출에 대한 구체적인 정보는 서비스 간 멀티플레이어 세션 관리를 참조하세요.
이 문서 상단으로 돌아가기.
