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

# 타이틀 웹사이트에 대한 XBOX 서비스 로그인

> 타이틀 웹사이트에서 Microsoft 계정 OAuth 2.0 로그인을 활성화하고 액세스 토큰을 XBOX Live 사용자 토큰으로 교환하여 플레이어 데이터 및 프로필을 읽습니다.

다양한 시나리오에서 사용자가 Microsoft 계정(이전 이름은 XBOX 서비스 계정)을 사용하여 인증할 수 있는 웹사이트나 웹 앱을 구축해야 합니다. 이 인증을 통해 순위표, 통계, 게임 클립, 프로필과 같은 사용자의 XBOX 서비스 데이터에 (일반적으로 읽기 전용) 액세스할 수 있습니다.

사용자 인증을 활성화하려면 웹사이트나 웹 앱을 먼저 Microsoft에 등록하여 Microsoft 계정 인증에 대한 ID를 받아야 합니다. 이는 일회성 프로비저닝 단계입니다. 런타임에 웹사이트는 먼저 사용자가 Microsoft 계정으로 인증할 수 있도록 허용하며, 이는 XBOX 서비스 액세스 토큰으로 교환할 수 있는 자격 증명을 제공합니다.

그런 다음 XBOX 서비스 액세스 토큰을 사용하여 계정 연결 목적으로 정보를 검색하고 사용자를 대신하여 XBOX 서비스에 액세스할 수 있습니다. 다음 섹션에서는 이러한 인증 흐름을 자세히 설명합니다.

## 인증 개요

사용자 인증을 활성화하고 XBOX 서비스 데이터에 액세스할 권한을 얻는 프로세스는 세 단계로 구성됩니다. 첫 번째 단계는 일회성 프로비저닝 단계입니다:

**웹사이트 등록**

* 웹사이트나 웹 앱은 Microsoft 계정과 함께 사용할 ID를 프로비저닝합니다.
* 이 등록은 게시자의 Microsoft Entra ID에서 발생합니다.

이 단계가 완료된 후 웹사이트나 웹 앱을 개발할 수 있으며 런타임에 다음 단계를 수행하여 XBOX 플레이어 권한 부여 및 인증을 받을 수 있습니다:

**Microsoft 계정에 대한 사용자 인증**

1. 사용자가 웹사이트에 액세스하거나 앱을 시작합니다.
2. 사용자는 OAuth2.0 엔드포인트를 통해 Microsoft 계정에 로그인하도록 리디렉션됩니다.
3. 사용자가 자격 증명을 성공적으로 입력하고 웹사이트나 앱이 자신을 대신하여 XBOX 서비스 정보에 액세스하도록 동의합니다.
4. 웹사이트나 앱이 권한 부여 코드를 수신합니다.
5. 웹사이트나 앱이 권한 부여 코드를 활용하고 올바른 범위를 요청하여 액세스 토큰을 요청합니다.
6. 웹사이트나 앱이 액세스 토큰(및 요청한 경우 새로 고침 토큰)을 수신했습니다.

**XBOX 서비스에 대한 사용자 인증**

7. 액세스 토큰을 사용하여 웹사이트나 앱은 XBOX 서비스 사용자 토큰(U 토큰)에 대한 요청을 합니다.
8. 그런 다음 사용자 토큰은 XBOX 서비스 또는 타이틀 서비스에 액세스하기 위해 XBOX 보안 토큰 서비스(XSTS)에서 X 토큰(액세스 토큰)을 얻는 데 사용됩니다.

## 웹사이트 등록

Microsoft 계정을 사용하여 웹사이트에서 사용자를 인증할 수 있으려면 먼저 웹사이트나 앱을 Microsoft Entra ID 앱 등록 인터페이스를 통해 등록해야 합니다.

1. Microsoft Entra ID 내에서 앱을 등록할 권한이 있는 계정으로 Azure Portal에 로그인합니다.
2. \*"App Registration"\*을 선택합니다.
3. \*"+ New Registration"\*을 선택합니다.
   * 이 애플리케이션에 대한 이름을 입력합니다.
   * \*"Supported account types"\*의 경우 \*"Personal Microsoft accounts only"\*를 선택합니다.
   * 성공적인 인증 후 인증 흐름이 사용자를 리디렉션할 리디렉션 URL을 입력합니다. 나중에 필요하므로 이를 기록해 둡니다.
     나중에 추가 URI를 추가할 수도 있습니다.
   * 앱 등록을 완료합니다.
4. Application (client) ID와 Directory (tenant) ID를 기록해 둡니다.
5. Certificates & Secrets를 선택합니다.
   * \*"+ New Client Secret"\*을 선택합니다.
   * 설명을 입력합니다.
   * 만료 범위를 선택합니다.
   * 추가를 클릭합니다.
   * 나중에 필요하므로 생성된 Client Secret 값을 기록해 둡니다. 이 값은 서비스에서만 사용되고 안전하게 저장되어야 합니다.

## 통합

위에서 언급한 흐름을 구현하고 등록 프로세스 중에 생성된 식별자를 사용하여 다음을 구현합니다.

1. 권한 부여 코드를 요청하여 OAuth2.0 흐름을 시작합니다:
   * 사용자를 `https://login.microsoftonline.com/consumers/oauth2/v2.0/authorize?client_id=[Application (client) ID from Registration]&response_type=code&redirect_uri=[RedirectUI given during registration]&scope=xboxlive.signin&xboxlive.offline_access`로 이동합니다.
     이 예에서는 만료된 후 액세스 토큰을 새로 고치는 데 사용할 수 있는 오프라인 토큰에 대한 로그인 토큰과 액세스를 요청합니다. 이는 또한 사용자에게 올바른 계정 개인 정보 보호 및 활동 알림을 표시합니다.
   * 사용자가 Microsoft 계정 로그인을 완료하면 권한 부여 코드가 추가된 리디렉션 URI로 리디렉션되며 `"code="` 뒤에 권한 부여 코드가 따라옵니다.
   * `xboxlive.offline_access` 범위 사용은 선택 사항이며 원래 로그인 토큰이 만료된 후 호출이 필요한 시나리오에만 필요합니다. 이 요청에는 다른 추가 범위를 사용할 수 없습니다.

2. 권한 부여 코드와 애플리케이션 등록 프로세스 중에 생성된 클라이언트 비밀을 사용하여 Microsoft 계정 액세스 토큰을 사용합니다:
   * 다음 속성으로 POST 웹 요청을 만듭니다:
     URL: `https://login.microsoftonline.com/consumers/oauth2/v2.0/token`
     헤더: `Content-Type: application/x-www-form-urlencoded`
     본문:

```
     client_id=[Application (Client) ID]&code=[Authorization Code received above]&
     redirect_uri=[A redirect UI set in the application]&
     grant_type=authorization_code&client_secret=[Client secret value from application registration]
```

* 서비스의 응답에는 다음 정보가 포함된 JSON 응답이 포함됩니다:
  Token Type: `Bearer`
  Scope: `XboxLive.signin XboxLive.offline_access`
  Expires\_in: `Value`
  Access\_token: `[token value]`
  이는 XBOX 사용자 토큰을 위해 XBOX 서비스와 교환하는 데 사용할 액세스 토큰입니다.

3. XBOX 인증 엔드포인트를 호출하여 XBOX 사용자 토큰을 요청하고 다음 요청을 완료하여 Microsoft 계정 액세스 토큰을 XBOX 사용자 토큰으로 교환할 수 있습니다:
   * 다음 속성으로 POST 웹 요청을 만듭니다:
     URL: `https://user.auth.xboxlive.com/user/authenticate`
     헤더: `x-xbl-contract-version: 1`
     헤더: `content-type: application/json`
     본문: 다음 데이터를 포함하는 잘 구성된 json 페이로드:

```
     {
       "RelyingParty": "http://auth.xboxlive.com",
       "TokenType": "JWT",
       "Properties": {
         "AuthMethod": "RPS",
         "SiteName": "user.auth.xboxlive.com",
         "RpsTicket": "d=[Microsoft Account access token received in the last step]"
       }
     }
```

* 서비스의 응답에는 XBOX 사용자 토큰이 포함된 다음 정보가 포함된 json 페이로드가 포함됩니다. 다음 단계에서 XBOX 사용자 토큰이 필요합니다:

```
     {
       "IssueInstant": "2021-06-08T23:45:50.2531302Z",
       "NotAfter": "2021-06-22T23:45:50.2531302Z",
       "Token": "d=[Xbox User Token]",
       "DisplayClaims": {
       "xui": [
           {
             "uhs": "[USER HASH]"
           }
         ]
       }
     }
```

4. 그런 다음 사용자 토큰을 X 토큰으로 교환할 수 있습니다. 사용자를 대신하여 서비스 간 호출을 수행하고 사용자에 대한 DelegationToken 클레임이나 XUID가 필요한 경우 자신의 신뢰 당사자에 대한 X 토큰을 요청한 다음 필요한 클레임을 추출하기 위해 평소와 같이 해당 토큰을 처리할 수 있습니다.

```
   POST https://xsts.auth.xboxlive.com/xsts/authorize HTTP/1.1
   x-xbl-contract-version: 1
   Content-Type: application/json
   Host: xsts.auth.xboxlive.com
   Content-Length: 1425
   Expect: 100-continue
   {
                   "Properties": {
                                   "SandboxId": "XDKS.1",
                                   "UserTokens": ["eyJlbmMiOiJBMTI4Q0JDK0hTMjU2IiwiYWxnIjoiUlN..."]
                   },
                   "RelyingParty": "[Your Relying Party here]",
                   "TokenType": "JWT"
   }
```