Apple SSO逐步指南(REST API V2) apple-sso-cookbook-rest-api-v2
Adobe Pass Authentication REST API V2支援在iOS、iPadOS或tvOS上執行之使用者端應用程式的一般使用者進行合作夥伴單一登入(SSO)。
此檔案可作為現有REST API V2總覽的延伸，提供高階檢視和說明如何使用合作夥伴流程🔗實作單一登入的檔案。
使用合作夥伴流程的Apple單一登入 cookbook
先決條件 prerequisites
繼續使用合作夥伴流程進行Apple單一登入之前，請確定符合下列先決條件：
-
串流應用程式必須收集
X-Device-Info和/或User-Agent標題所需的所有必要資料，讓Adobe Pass驗證後端可以識別裝置平台及其功能。 如需X-Device-Info標頭的詳細資訊，請參閱X-Device-Info檔案。 -
串流應用程式必須請求存取儲存在裝置層級的使用者訂閱資訊，使用者必須授予應用程式繼續的許可權，類似於提供裝置攝影機或麥克風的存取權。 必須使用Apple的視訊訂閱者帳戶架構為每個應用程式要求此許可權，裝置將會儲存使用者的選擇。
我們建議您說明Apple單一登入使用者體驗的優點，以鼓勵拒絕授予許可權存取訂閱資訊的使用者，但請注意，使用者可以移至應用程式設定（電視提供者許可權存取）、iOS和iPadOS上的
Settings -> TV Provider或tvOS上的Settings -> Accounts -> TV Provider來變更其決定。當應用程式進入前景狀態時，串流應用程式可以要求使用者的許可權，因為應用程式可以在要求使用者驗證之前，隨時檢查存取使用者訂閱資訊的許可權。
工作流程 workflow
執行指定的步驟，使用合作夥伴流程來實作Apple單一登入，如下圖所示。
使用合作夥伴流程
使用合作夥伴流程 Apple單一登入
-
擷取使用者端認證： 串流應用程式會呼叫使用者端登入端點，以收集擷取使用者端認證所需的所有資料。
note important IMPORTANT 如需下列詳細資訊，請參閱擷取使用者端認證 API檔案： - 所有_必要的_引數，例如
software_statement - 所有_必要的_標頭，例如
Content-Type、X-Device-Info - 所有_選用的_引數和標頭
- 所有_必要的_引數，例如
-
傳回使用者端認證： 使用者端登入端點回應包含與所接收引數和標頭相關聯的使用者端認證的相關資訊。
note important IMPORTANT 請參閱擷取使用者端認證 API檔案，以取得使用者端認證回應中提供的詳細資訊。 Client Register會驗證要求資料，以確保符合基本條件： - 必要 引數和標頭必須有效。
如果驗證失敗，將會產生錯誤回應，提供遵守擷取使用者端認證 API檔案的額外資訊。 note tip TIP 建議：使用者端認證必須快取，並可無限期使用。 -
擷取存取Token： 串流應用程式會呼叫使用者端權杖端點，收集擷取存取Token所需的所有資料。
note important IMPORTANT 請參閱擷取存取Token API檔案，以取得下列詳細資訊： - 所有_必要的_引數，例如
client_id、client_secret和grant_type - 所有_必要的_標頭，例如
Content-Type、X-Device-Info - 所有_選用的_引數和標頭
- 所有_必要的_引數，例如
-
傳回存取權杖： 使用者端權杖端點回應包含與收到的引數和標頭關聯的存取權杖相關資訊。
note important IMPORTANT 請參閱擷取存取Token API檔案，以取得存取Token回應中提供的詳細資訊。 使用者端權杖會驗證請求資料，以確保符合基本條件： - 必要 引數和標頭必須有效。
如果驗證失敗，將會產生錯誤回應，提供遵守擷取存取Token API檔案的額外資訊。 note tip TIP 建議：存取權杖只能在指定的期間內快取和使用（例如24小時存留時間）。 到期後，串流應用程式必須要求新的存取權杖。
-
擷取合作夥伴架構狀態： 串流應用程式會呼叫Apple開發的視訊訂閱者帳戶架構，以取得使用者許可權和提供者資訊。
note important IMPORTANT 請參閱視訊訂閱者帳戶架構檔案，以取得下列詳細資訊： 串流應用程式必須確定它為 VSAccountMetadataRequest物件中的isInterruptionAllowed屬性指定了等於false的Boolean值，以表示在此階段無法中斷使用者。 -
傳回夥伴架構狀態資訊： 串流應用程式會驗證回應資料，以確保符合基本條件：
- 已授予使用者許可權存取狀態。
- 使用者提供者對應識別碼存在且有效。
- 使用者提供者設定檔的到期日（如果有的話）有效。
-
擷取設定檔： 串流應用程式會收集所有必要資料，藉由傳送要求給設定檔端點來擷取所有設定檔資訊。
note important IMPORTANT 如需下列詳細資訊，請參閱擷取設定檔 API檔案： - 所有_必要的_引數，例如
serviceProvider - 所有_必要的_標頭，例如
Authorization、AP-Device-Identifier和AP-Partner-Framework-Status - 所有_選用的_引數和標頭
串流應用程式必須確定其包含合作夥伴架構狀態的有效值，以便擷取的回應可包含「appleSSO」型別設定檔。 如需 AP-Partner-Framework-Status標頭的詳細資訊，請參閱AP-Partner-Framework-Status檔案。 - 所有_必要的_引數，例如
-
傳回有關已找到設定檔的資訊： 設定檔端點回應包含有關已找到與已接收引數和標題相關聯的設定檔的資訊。
-
選擇設定檔並繼續決策流程： 如果「設定檔」端點回應包含設定檔，串流應用程式會使用其內部邏輯（最終透過與一般使用者互動）來選擇其中一個可用的設定檔，以繼續後續的決策流程。
-
繼續協力驗證流程： 如果Profiles端點回應不包含設定檔，串流應用程式會繼續協力驗證流程。
-
擷取組態： 串流應用程式會收集所有必要的資料，藉由傳送要求給組態端點，以擷取具有作用中整合的MVPD清單。
note important IMPORTANT 如需下列詳細資訊，請參閱特定服務提供者🔗 API的擷取組態： - 所有_必要的_引數，例如
serviceProvider - 所有_必要的_標頭，例如
Authorization、AP-Device-Identifier和X-Device-Info - 所有_選用的_引數和標頭
- 所有_必要的_引數，例如
-
傳回組態： 組態端點回應包含與服務提供者有效整合之MVPD的相關資訊。
note important IMPORTANT 請參閱特定服務提供者🔗 API檔案的擷取組態，以取得組態回應中提供的詳細資訊。 設定端點會驗證請求資料，以確保符合基本條件： - 必要 引數和標頭必須有效。
如果驗證失敗，將會產生錯誤回應，提供可遵守增強錯誤碼檔案的額外資訊。 note important IMPORTANT 串流應用程式在繼續下一步作業時，必須確定已處理每個MVPD所提供的下列詳細資料： enablePlatformServices：指出MVPD目前是否支援Apple單一登入。displayInPlatformPicker：指出MVPD是否可顯示在Apple選擇器中。boardingStatus：指出MVPD是否已上線到Apple單一登入。
-
擷取合作夥伴架構狀態： 串流應用程式會呼叫Apple開發的視訊訂閱者帳戶架構，以取得使用者許可權和提供者資訊。
note important IMPORTANT 請參閱視訊訂閱者帳戶架構檔案，以取得下列詳細資訊： 串流應用程式必須確定它為 VSAccountMetadataRequest物件中的isInterruptionAllowed屬性指定了等於true的Boolean值，以表示在此階段可以中斷使用者選取電視提供者。 -
傳回夥伴架構狀態資訊： 串流應用程式會驗證回應資料，以確保符合基本條件：
- 已授予使用者許可權存取狀態。
- 使用者提供者對應識別碼存在且有效。
- 使用者提供者設定檔的到期日（如果有的話）有效。
-
擷取合作夥伴驗證要求： 串流應用程式會收集所有必要的資料，藉由呼叫工作階段合作夥伴端點來啟動驗證工作階段。
note important IMPORTANT 如需下列詳細資訊，請參閱擷取合作夥伴驗證要求 API檔案： - 所有_必要的_引數，例如
serviceProvider和partner - 所有_必要的_標頭，例如
Authorization、AP-Device-Identifier、Content-Type、X-Device-Info和AP-Partner-Framework-Status - 所有_選用的_標頭和引數
串流應用程式必須確保其包含合作夥伴框架狀態的有效值，以便擷取的回應可能包含合作夥伴驗證請求（SAML請求）。 如需 AP-Partner-Framework-Status標頭的詳細資訊，請參閱AP-Partner-Framework-Status檔案。 - 所有_必要的_引數，例如
-
指示下一個動作： 工作階段合作夥伴端點回應包含必要的資料，可引導串流應用程式瞭解下一個動作。
note important IMPORTANT 請參閱擷取合作夥伴驗證要求 API檔案，以取得工作階段回應中提供的詳細資訊。 工作階段合作夥伴端點會驗證請求資料，以確保符合基本條件： - 必要 引數和標頭必須有效。
- 提供的
serviceProvider與mvpd之間的整合必須是作用中。
如果基本驗證失敗，將會產生錯誤回應，提供遵守增強型錯誤碼檔案的額外資訊。 「工作階段」合作夥伴端點會驗證請求資料，以確保符合合作夥伴單一登入條件： - Adobe Pass伺服器中的合作夥伴單一登入設定必須有效且已啟用。
- 透過AP-Partner-Framework-Status標頭收到的合作夥伴架構狀態承載必須有效。
如果合作夥伴單一登入驗證失敗，回應將預設為基本驗證流程。 -
繼續決策流程： 工作階段夥伴端點回應包含下列資料：
actionName屬性已設定為「授權」。actionType屬性設定為「直接」。
如果Adobe Pass後端識別有效的設定檔，串流應用程式就不需要使用選取的MVPD重新驗證，因為已經有設定檔可用於後續的決策流程。
-
繼續基本驗證流程： 工作階段夥伴端點回應包含下列資料：
actionName屬性已設定為「驗證」或「繼續」。actionType屬性設定為「互動」或「直接」。
如果Adobe Pass後端未識別有效的設定檔，且合作夥伴單一登入驗證失敗，則Adobe Pass伺服器會回覆為基本驗證流程。
如需基本驗證流程的詳細資訊，請參閱以下檔案：
-
繼續使用合作夥伴驗證回應流程建立及擷取設定檔： 工作階段合作夥伴端點回應包含下列資料：
actionName屬性設定為"partner_profile"。actionType屬性設定為「直接」。authenticationRequest - type屬性包含合作夥伴架構用於MVPD登入的安全性通訊協定（目前僅設定為SAML）。authenticationRequest - request屬性包含傳遞至合作夥伴架構的SAML要求。authenticationRequest - attributesNames屬性包含傳遞至合作夥伴架構的SAML屬性。
如果Adobe Pass後端未識別有效的設定檔，且合作夥伴單一登入驗證通過時，串流應用程式會收到包含動作和資料的回應，並傳遞至合作夥伴架構，以啟動與MVPD的驗證流程。
-
使用合作夥伴架構完成MVPD驗證： 將先前步驟取得的合作夥伴驗證要求（SAML要求）轉送至視訊訂閱者帳戶架構。 如果驗證流程成功，與MVPD的視訊訂閱者帳戶架構互動會產生合作夥伴驗證回應（SAML回應），此回應會連同合作夥伴架構狀態資訊一併傳回。
note important IMPORTANT 請參閱視訊訂閱者帳戶架構檔案，以取得下列詳細資訊： 串流應用程式必須確定它為 VSAccountMetadataRequest物件中的isInterruptionAllowed屬性指定了等於true的Boolean值，以表示在此階段可以中斷使用者，以向選取的電視提供者進行驗證。 -
傳回夥伴驗證回應： 串流應用程式會驗證回應資料，以確保符合基本條件：
- 已授予使用者許可權存取狀態。
- 使用者提供者對應識別碼存在且有效。
- 使用者提供者設定檔的到期日（如果有的話）有效。
- 合作夥伴驗證回應（SAML回應）存在且有效。
-
使用合作夥伴驗證回應來建立及擷取設定檔： 串流應用程式會收集所有必要的資料，藉由呼叫「設定檔合作夥伴」端點來建立及擷取設定檔。
note important IMPORTANT 如需下列詳細資訊，請參閱使用合作夥伴驗證回應 API檔案建立和擷取設定檔： - 所有_必要的_引數，例如
serviceProvider、partner和SAMLResponse - 所有_必要的_標頭，例如
Authorization、AP-Device-Identifier、Content-Type、X-Device-Info和AP-Partner-Framework-Status - 所有_選用的_標頭和引數
串流應用程式必須確定其包含合作夥伴架構狀態和合作夥伴驗證回應（SAML回應）的有效值，以使擷取的回應可能包含「appleSSO」型別設定檔。 如需 AP-Partner-Framework-Status標頭的詳細資訊，請參閱AP-Partner-Framework-Status檔案。 - 所有_必要的_引數，例如
-
傳回夥伴設定檔的相關資訊： 設定檔端點回應包含夥伴設定檔的相關資訊，包括設定為「appleSSO」的屬性
type。note important IMPORTANT 請參閱使用合作夥伴驗證回應 API檔案，以取得有關設定檔回應中所提供資訊的詳細資訊。 設定檔合作夥伴端點會驗證請求資料，以確保符合基本條件： - 必要 引數和標頭必須有效。
- 提供的
serviceProvider與mvpd之間的整合必須是作用中。
如果驗證失敗，將會產生錯誤回應，提供可遵守增強錯誤碼檔案的額外資訊。 設定檔合作夥伴端點會驗證請求資料，以確保符合合作夥伴單一登入條件： - Adobe Pass伺服器中的合作夥伴單一登入設定必須有效且已啟用。
- 透過AP-Partner-Framework-Status標頭收到的合作夥伴架構狀態承載必須有效。
如果合作夥伴單一登入驗證失敗，回應將預設為基本設定檔擷取流程。 -
繼續決策流程： 串流應用程式可以繼續後續的決策流程。
-
擷取合作夥伴架構狀態： 串流應用程式會呼叫Apple開發的視訊訂閱者帳戶架構，以取得使用者許可權和提供者資訊。
note important IMPORTANT 如果選取的使用者設定檔型別不是「appleSSO」，串流應用程式可以略過此步驟。 note important IMPORTANT 請參閱視訊訂閱者帳戶架構檔案，以取得下列詳細資訊： 串流應用程式必須確定它為 VSAccountMetadataRequest物件中的isInterruptionAllowed屬性指定了等於false的Boolean值，以表示在此階段無法中斷使用者。note tip TIP 建議：串流應用程式可改用快取值作為合作夥伴架構狀態資訊，建議在應用程式從背景轉換為前景狀態時重新整理。 在這種情況下，串流應用程式必須確保其快取並僅使用合作夥伴架構狀態的有效值，如「傳回合作夥伴架構狀態資訊」步驟所述。 -
傳回夥伴架構狀態資訊： 串流應用程式會驗證回應資料，以確保符合基本條件：
- 已授予使用者許可權存取狀態。
- 使用者提供者對應識別碼存在且有效。
- 使用者提供者設定檔的到期日有效。
note important IMPORTANT 如果選取的使用者設定檔型別不是「appleSSO」，串流應用程式可以略過此步驟。 -
擷取預先授權決定： 串流應用程式會呼叫Decisions Preauthorize端點，收集所有必要的資料，以取得資源清單的預先授權決定。
note important IMPORTANT 如需下列詳細資訊，請參閱使用特定mvpd🔗 API檔案擷取預先授權決定： - 所有_必要的_引數，例如
serviceProvider、mvpd和resources - 所有_必要的_標頭，例如
Authorization和AP-Device-Identifier - 所有_選用的_引數和標頭
當選擇的設定檔是「appleSSO」型別設定檔時，串流應用程式在進一步提出請求之前，必須確定它包含合作夥伴框架狀態的有效值。 但是，如果所選的使用者設定檔型別不是「appleSSO」，則可以跳過此步驟。 如需 AP-Partner-Framework-Status標頭的詳細資訊，請參閱AP-Partner-Framework-Status檔案。 - 所有_必要的_引數，例如
-
傳回預先授權決定： 決定預先授權端點回應包含每個資源的
Permit或Deny決定：Permit決定表示資源可供播放。 回應不包含媒體Token，因為預先授權流程不能用於播放資源。Deny決定表示資源無法播放。 回應包含附在增強錯誤碼檔案的錯誤承載。
note important IMPORTANT 請參閱使用特定mvpd🔗 API檔案的擷取預先授權決定，以取得決定回應中提供的詳細資訊。 決定預先授權端點會驗證請求資料，以確保符合基本條件： - 必要 引數和標頭必須有效。
- 提供的
serviceProvider與mvpd之間的整合必須是作用中。
如果驗證失敗，將會產生錯誤回應，提供可遵守增強錯誤碼檔案的額外資訊。 -
擷取合作夥伴架構狀態： 串流應用程式會呼叫Apple開發的視訊訂閱者帳戶架構，以取得使用者許可權和提供者資訊。
note important IMPORTANT 如果選取的使用者設定檔型別不是「appleSSO」，串流應用程式可以略過此步驟。 note important IMPORTANT 請參閱視訊訂閱者帳戶架構檔案，以取得下列詳細資訊： 串流應用程式必須確定它為 VSAccountMetadataRequest物件中的isInterruptionAllowed屬性指定了等於false的Boolean值，以表示在此階段無法中斷使用者。note tip TIP 建議：串流應用程式可改用快取值作為合作夥伴架構狀態資訊，建議在應用程式從背景轉換為前景狀態時重新整理。 在這種情況下，串流應用程式必須確保其快取並僅使用合作夥伴架構狀態的有效值，如「傳回合作夥伴架構狀態資訊」步驟所述。 -
傳回夥伴架構狀態資訊： 串流應用程式會驗證回應資料，以確保符合基本條件：
- 已授予使用者許可權存取狀態。
- 使用者提供者對應識別碼存在且有效。
- 使用者提供者設定檔的到期日有效。
note important IMPORTANT 如果選取的使用者設定檔型別不是「appleSSO」，串流應用程式可以略過此步驟。 -
擷取授權決定： 串流應用程式會呼叫Decisions Authorized端點，收集所有必要資料以取得特定資源的授權決定。
note important IMPORTANT 請參考使用特定mvpd API擷取授權決定，以取得以下詳細資訊： - 所有_必要的_引數，例如
serviceProvider、mvpd和resources - 所有_必要的_標頭，例如
Authorization和AP-Device-Identifier - 所有_選用的_引數和標頭
當選擇的設定檔是「appleSSO」型別設定檔時，串流應用程式在進一步提出請求之前，必須確定它包含合作夥伴框架狀態的有效值。 但是，如果所選的使用者設定檔型別不是「appleSSO」，則可以跳過此步驟。 如需 AP-Partner-Framework-Status標頭的詳細資訊，請參閱AP-Partner-Framework-Status檔案。 - 所有_必要的_引數，例如
-
傳回授權決定： 決定授權端點回應包含特定資源的
Permit或Deny決定：Permit決定表示資源可供播放。 回應包含媒體權杖。Deny決定表示資源無法播放。 回應包含附在增強錯誤碼檔案的錯誤承載。
note important IMPORTANT 請參閱使用特定mvpd🔗 API檔案的擷取授權決定，以取得決定回應中提供的詳細資訊。 Decisions Authorize端點會驗證請求資料，以確保符合基本條件： - 必要 引數和標頭必須有效。
- 提供的
serviceProvider與mvpd之間的整合必須是作用中。
如果驗證失敗，將會產生錯誤回應，提供可遵守增強錯誤碼檔案的額外資訊。
-
啟動Adobe Pass登出： 串流應用程式會呼叫Adobe Pass登出端點，收集所有必要的資料以啟動登出流程。
note important IMPORTANT 如需下列詳細資訊，請參閱特定mvpd🔗 API的起始登出： - 所有_必要的_引數，例如
serviceProvider、mvpd和redirectUrl - 所有_必要的_標頭，例如
Authorization、AP-Device-Identifier - 所有_選用的_引數和標頭
- 所有_必要的_引數，例如
-
指示下一個動作： Adobe Pass登出端點回應包含必要的資料，可引導串流應用程式執行下一個動作：
url屬性遺失，因為使用者需要與夥伴（系統）層級互動以完成登出流程。actionName屬性設定為「partner_logout」。actionType屬性設定為"partner_interactive"。
note important IMPORTANT 當移除的使用者設定檔型別為「appleSSO」時，串流應用程式必須提示使用者完成由 actionName和actionType屬性指定的合作夥伴層級的登出程式。note important IMPORTANT 如需登出回應中提供的詳細資訊，請參閱特定mvpd🔗 API的Initiate登出。 Adobe Pass登出端點會驗證請求資料，以確保符合基本條件： - 必要 引數和標頭必須有效。
- 提供的
serviceProvider與mvpd之間的整合必須是作用中。
如果驗證失敗，將會產生錯誤回應，提供可遵守增強錯誤碼檔案的額外資訊。