跳轉到主要內容
本文說明如何使用 XBOX 安全性權杖 (XSTS) 從自訂遊戲服務呼叫 XBOX 服務: 本文涵蓋下列各節: 遊戲服務可以透過服務對服務 (S2S) 存取 (也稱為後端對後端) 來存取 XBOX 服務。這可啟用新的遊戲玩法和互動案例,例如自訂配對服務。它們可以使用 S2S 呼叫來建立和讀取多人遊戲工作階段資訊和玩家資料。 用戶端和遊戲服務呼叫 XBOX 服務端點的 RESTful 要求模式是相同的。不過,驗證路徑不同。遊戲服務需要更多驗證步驟,才能執行 XBOX 服務呼叫。下列各節說明此驗證路徑的流程,以為您的服務啟用 S2S 存取。

S2S 設定

本節提供遊戲對 XBOX 服務之 S2S 呼叫存取的概觀。根據預設,並未為每個遊戲啟用 S2S 存取。必須先在 Partner Center 中於發行者和遊戲層級設定存取權。

商務合作夥伴憑證設定

若要取得 XBOX 服務的存取權,遊戲服務必須具有在 XBOX 服務上註冊的認證。商務合作夥伴憑證用於此存取。此憑證是由 XBOX 服務憑證授權單位 (CA) 發出的 X509 憑證。 商務合作夥伴憑證是透過 Partner Center 中的 XBOX 服務 Web Services 頁面,在發行者層級針對所有沙箱進行設定的。如需詳細的設定步驟,請參閱在 Partner Center 中設定單一登入。

商務合作夥伴憑證到期

就像其他憑證一樣,商務合作夥伴憑證也會到期。它們應該在到期前更新。目前,商務合作夥伴憑證產生時的存留期約為自建立日期起 18 個月。未來,商務合作夥伴憑證的存留期可能會變更。已到期的商務合作夥伴憑證在到期日之後將無法運作。當您嘗試取得與這些憑證相關的服務權杖 (S 權杖) 或 XSTS 權杖時,就會發生錯誤。 開發人員必須追蹤任何使用中商務合作夥伴憑證的到期日,並在到期前透過 Partner Center 重新整理憑證。建議在商務合作夥伴憑證到期日前一週設定行事曆提醒,以重新整理並部署新的憑證。

使用商務合作夥伴憑證設定 XBOX 服務存取

若要讓具有商務合作夥伴憑證的伺服器能夠存取 XBOX 服務,每個遊戲都必須將存取權限授與為其產生商務合作夥伴憑證的 Web 服務。此設定是在 Partner Center 中針對每個遊戲執行的。如需詳細資訊,請參閱存取原則概觀。

委派的 S2S 設定

若要代表使用者對 XBOX 服務進行 S2S 呼叫,服務必須已針對服務驗證和信賴憑證者進行設定。如需詳細資訊,請參閱適用於遊戲服務的 XBOX 服務驗證。 對於委派的 S2S 呼叫存取,信賴憑證者的權杖定義也必須包含 DelegationToken 宣告。此宣告包含 XSTS 代表使用者發出權杖所需的資訊。 使用者的委派權杖會在發出後 30 天到期。此權杖只應在使用者登入期間或需要為使用者提出要求時使用。遊戲必須刪除不再需要的委派權杖。 返回本文頂端。

服務驗證流程

下圖描述向 XBOX 服務驗證遊戲服務的三個步驟。 向 XBOX 服務驗證遊戲服務之流程圖的影像。
  1. 遊戲服務首先向 XBOX 服務驗證服務 (XSAS) 執行驗證 POST 要求,並在要求本文中註明沙箱、證明金鑰和權杖類型。先前取得的商務合作夥伴憑證必須用作用戶端 TLS 憑證。如果成功,XSAS 會傳回預設存留期為兩週的 S 權杖。
    XSAS:https://service.auth.xboxlive.com/service/authenticate
  2. 接著可以透過向 XSTS 提出 POST 要求,將 S 權杖交換為稱為 X 權杖的授權權杖。需要下列參數作為要求屬性:S 權杖、您嘗試存取之沙箱的識別碼,以及目標信賴憑證者的名稱。
    XSTS:https://xsts.auth.xboxlive.com/xsts/authorize
  3. 如果需要代表您為其取得該宣告的使用者進行呼叫,您可以選擇性地將 DelegationToken 宣告新增至要求。在此案例中,提供的 SandboxId 必須可由 DelegationToken 宣告的使用者存取。使用以這種方式取得的 X 權杖,您的服務就可以對各種 XBOX 服務進行已驗證的呼叫。
返回本文頂端。

證明金鑰

使用證明金鑰可以防止中間人攻擊,這種攻擊會讓攻擊者擷取權杖,並代表真正的權杖擁有者撰寫訊息。如需產生證明金鑰和簽章的完整程式碼範例,請參閱可在 XBOX 開發人員下載上下載的 GameService 主控台範例。 更具體地說,在取得安全性權杖時,呼叫端會先產生公開/私密金鑰組。然後,呼叫端會為自己保留私密金鑰,並將公開金鑰與安全性權杖要求一起傳送 (本文稍後的取得服務權杖一節將會說明)。公開金鑰接著會內嵌在權杖中。每次呼叫端將要求傳送至服務時,都會將權杖傳遞給服務,並使用私密金鑰簽署訊息。只有呼叫端擁有私密金鑰。 接收訊息的服務會驗證權杖的有效性,然後使用權杖中包含的公開金鑰來驗證要求的簽章。如果要求簽章通過驗證,就證明呼叫端擁有私密金鑰。假設呼叫端妥善保管其私密金鑰,這就證明呼叫端與向安全性權杖服務提供公開金鑰的一方是同一方。 金鑰本身是 JSON Web 金鑰 (JWK),如網際網路工程任務推動小組 (IETF) 規格 https://tools.ietf.org/html/draft-ietf-jose-json-web-key-08 中所定義。 URL、路徑、查詢字串、Authorization 標頭和時間戳記一律會簽署。因此,它們會隱含在用來簽署要求的簽章原則中。每個公開驗證端點的服務也可以要求必須包含在簽章原則中的其他標頭。它也可以指定將簽署之要求本文的大小上限 (以位元組為單位)。每個服務都會定義其支援的簽署演算法集合。 簽章原則以 JSON 形式表示如下。
用戶端 (在此案例中為您的遊戲服務) 必須了解其需要呼叫之端點所需的簽署原則。它們會從要求建立要簽署的資料流 (確切的程序在下列步驟 1 到 7 中說明),使用安全雜湊演算法 256 (SHA256) 對資料流進行雜湊,然後使用私密金鑰加密以產生簽章。 簽章透過 HTTP 標頭傳輸,由下列三個部分組成。
  1. 簽章原則版本。它以網路位元組順序 (big-endian) 的 4 位元組整數值表示。
  2. 網路位元組順序的 64 位元 Windows 檔案時間。
  3. 產生的簽章位元組。
這三個部分會合併為單一位元組資料流,並編碼為 base-64 字串,隨要求以額外標頭 (Signature 標頭) 傳送。 由於簽章是以 HTTP 標頭傳輸,因此任何包含本文雜湊的訊息都必須先在記憶體中進行雜湊,才能將本文的任何位元組寫入要求資料流。簽章是根據實際傳輸的位元組計算的。簽章必須在任何要求本文轉換之後計算。 建立要簽署之資料流的確切程序如下所示。所有字串資料 (例如標頭和 URL) 都以 ASCII 編碼。本文是不透明的 Blob,會依原樣簽署。 這些元素的值說明如下。
  1. 網路位元組順序的 4 位元組不帶正負號整數形式的原則版本,後面接著 null 位元組。
  2. 網路位元組順序的時間戳記 (來自 Signature 標頭),後面接著 null 位元組。
  3. 大寫的 HTTP 方法 (例如 GET 或 POST),後面接著 null 位元組。
  4. 絕對路徑和查詢字串,後面接著 null 位元組。
  5. Authorization 標頭的值 (如果有),後面接著 null 位元組。
  6. 簽章原則中指定的其他標頭,如果您要新增任何標頭,每個標頭後面都接著 null 位元組。如果沒有其他標頭,則不應新增任何位元組。
  7. 讓 N 為要簽署之本文的位元組數上限,如要呼叫之端點的簽章原則所指定。讓 M 為未壓縮本文的大小。如果 M \> N,請使用未壓縮本文的前 N 個位元組。如果 M \<= N,請使用整個未壓縮本文 (不含填補)。會附加一個 null 位元組 (即使沒有要求本文,也必須附加 null 位元組)。
上述每個元素都以 null 位元組 (0x00) 分隔,以減少在沒有分隔符號的情況下串連所造成的任何模稜兩可。之所以使用 null 位元組,是因為 HTTP 標準禁止在標頭中使用不可列印的字元。因此,任何插入或延伸資料的嘗試都需要包含 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~。如果全域原則指定了 Range 之類不適用於 POST 要求的標頭,就需要這麼做。 不過,如果缺少某個標頭,仍必須包含對應的 null 位元組。如果未指定任何標頭,這也適用。如果缺少 H~2~,要簽署的資料流會在 H~1~ 和 H~3~ 標頭之間包含兩個 null 位元組。另一種思考方式是將遺漏的標頭視為空字串。 返回本文頂端。

取得服務權杖

本節涵蓋與取得服務權杖相關之要求、回應和錯誤處理的詳細資料。如需要求和管理服務權杖的完整範例程式碼實作,請參閱可在 XBOX 開發人員下載上下載的 GameService 主控台範例。

服務權杖要求

XSAS 提供下列 REST 端點來處理服務驗證。 https://service.auth.xboxlive.com/service/authenticate 此端點需要 TLS 1.2 (或更新版本),以及在要求中用作用戶端 SSL 憑證的有效商務合作夥伴憑證。 如果與端點的連線中斷,通常是因為要求中缺少或錯誤設定了上述項目。 您的服務會執行 POST,其本文遵循下列 XSASRequest 資料合約。
XSASRequest 之 PropertyBag 中唯一必要的屬性是 ProofKey。它必須是 JWK,如本文的證明金鑰一節所示。
請快取或記錄此 S 權杖的證明金鑰。使用以該 S 權杖取得的權杖呼叫 XBOX 服務時,請使用該證明金鑰來產生簽章。
此外,要求中必須包含下表中的標頭。 以下是範例要求的程式碼。
將曲線點 x 和 y 從十進位表示法轉換為十六進位表示法時,請確保它們的長度為偶數。否則,可能會導致轉換長度不正確而遭到服務拒絕。 原始格式是 r 和 s 單純串連的格式。在此格式中,r 和 s 必須先依照某種慣例 (通常是 big-endian) 表示為位元組序列,並可能帶有一些值為 0x00 的額外填補位元組。這可確保 r 和 s 編碼具有相同的大小。r 和 s 編碼的大小相同,對於驗證者知道在何處分割此資料很重要。 預期使用原始格式,而非 DER。對於此原始格式,也必須套用 0x00 填補。

服務權杖回應

回應的資料合約如下。

服務權杖錯誤處理

如果證明金鑰簽章無效,伺服器會傳回 403 錯誤。
若要成功建立 SSL 通道,必須在用戶端上安裝商務合作夥伴憑證的完整信任憑證鏈結。憑證鏈結是公開的。您可以開啟商務合作夥伴憑證、選取 Certification Path 索引標籤,然後檢視或下載您需要的個別憑證,以下載適當的憑證。
返回本文頂端。

取得用於 S2S 呼叫的 XSTS 權杖

本節提供與取得 X 權杖相關之要求、回應和錯誤處理的詳細資料。如需要求、管理和使用 XSTS 權杖進行 S2S 呼叫的完整範例程式碼實作,請參閱可在 XBOX 開發人員下載上下載的 GameService 主控台範例。 下列兩種類型的 XSTS 權杖可用來向 XBOX 服務驗證您的服務。
  • **服務驗證 XSTS 權杖:**只包含您服務的身分識別,並使用產生的服務權杖建立。此權杖只能用於字串驗證、多人遊戲和已刪除帳戶服務的驗證。
  • **委派驗證 XSTS 權杖:**包含使用者宣告,是向大多數 XBOX 服務和 Microsoft Store 服務進行驗證所必需的。

要求

XSTS 服務提供下列 REST 端點來處理授權。 https://xsts.auth.xboxlive.com/xsts/authorize 您的服務會執行 POST,其本文遵循下列 XSTSRequest 資料合約。
[!NOTE] 取得服務驗證 XSTS 權杖時,您只需要提供 S 權杖。 對於委派驗證 XSTS 權杖,您還需要包含 DelegationToken 值。它包含您代表其進行呼叫之使用者的身分識別。

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 宣告新增至您的 XSTS 權杖,如本文稍早的委派的 S2S 設定一節所詳述。 只有當您從網站呼叫 XBOX 服務,而該網站的 Web 伺服器是以商務合作夥伴憑證進行驗證,且使用者是使用 Microsoft 帳戶 OAuth 流程進行使用者驗證來向您的網站驗證時,才應使用 UserTokens 屬性。在此情況下,UserTokens 屬性應該是包含一個元素的陣列,該元素包含在使用者 XBOX 驗證服務 (XASU) 中,將從 Microsoft 帳戶擷取之使用者存取權杖交換為使用者 (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 權杖直到其到期為止,而不是在每次要求時都要求新的權杖。此外,盡可能將呼叫批次處理 (例如社交呼叫),以提高輸送量並避免要求節流。 如需以 S2S 方式呼叫 XBOX 服務多人遊戲服務的特定資訊,請參閱服務對服務多人遊戲工作階段管理。 返回本文頂端。

另請參閱

XBOX 服務 RESTful 參考 服務對服務多人遊戲工作階段管理 從服務取得已刪除帳戶清單 Microsoft Store 服務 API
最後修改於 2026年10月8日