REST API逐步指南（伺服器對伺服器） rest-api-cookbook-server-to-server
概觀 overview
本逐步指南檔案的目的，在於詳細說明使用伺服器對伺服器架構實作Adobe Pass驗證的最佳實務。 它提供基本需求、逐步流程實作，以及生產環境和作業的一般考量事項。
節流機制
Adobe Pass驗證REST API受節流機制所控管。
元件 components
在運作中的伺服器對伺服器解決方案中，涉及下列元件：
此流程中使用的其他辭彙定義於
字彙表。
流程 flows
動態使用者端註冊(DCR)
Adobe Pass使用DCR來保護程式設計人員應用程式或伺服器與Adobe Pass服務之間的使用者端通訊。 DCR流程是獨立的，並在Dynamic Client Registration Overview檔案中說明。
驗證(authN)
驗證流程用於允許使用者識別自己
至其MVPD，以判斷使用者是否有有效的帳戶。
- 使用者啟動串流裝置應用程式，並嘗試登入或檢視受保護的內容。
- 串流裝置應用程式會向程式設計人員服務提出要求，以判斷裝置是否已驗證。
- 程式設計人員服務會使用DCR註冊應用程式。
- 程式設計師服務會呼叫Adobe Pass服務 checkauthn API來檢查串流裝置authN狀態。
- 如果 checkauthn 呼叫傳回使用者裝置已驗證的狀態，則應用程式可以繼續進行授權流程。
- 在 checkauthn 呼叫傳回使用者裝置「未驗證」的狀態的情況下，應用程式應等待使用者要求登入。
- 當使用者要求直接登入（例如選取登入按鈕）或間接登入（例如尚未驗證即選取受保護的內容）時，串流裝置應用程式會向程式設計人員服務提出要求，以啟動使用者驗證。 程式設計師服務會呼叫Adobe Pass服務 regcode API，要求並接收唯一的註冊代碼(regcode)。
- 程式設計師服務也會呼叫Adobe Pass服務 config API，以擷取目前的MVPD和屬性清單。 注意：此API也可以在流程中較早呼叫並快取。
- 程式設計師服務會將regcode傳回至串流裝置應用程式，並傳回步驟#7中要求的已處理MVPD清單。 注意：已處理的MVPD清單格式是由程式設計師指定，而且可以篩選為明確允許或封鎖特定的MVPD （亦即允許或封鎖清單）。
- 如果與AuthN裝置（即「第二個熒幕」）不同，則可能是出於選擇或必要（即串流裝置不支援使用者代理程式），則串流裝置應該顯示規則碼和URI，讓使用者可以存取AuthN應用程式。 使用者將URI輸入AuthN裝置上的使用者代理程式以啟動AuthN應用程式，然後將regcode輸入該應用程式。 如果串流裝置與AuthN裝置相同，則以程式設計方式將regcode傳遞至AuthN模組。
- AuthN模組會顯示MVPD選擇器，以啟動使用者與MVPD的驗證。 使用者選取MVPD後，AuthN模組會呼叫 使用regcode的authenticate，將使用者代理程式重新導向至MVPD IdP。 當使用者透過MVPD成功驗證時，使用者代理程式會透過Adobe Pass服務重新導向，其中系統會以regcode記錄成功的驗證，然後重新導向回AuthN模組。
- 如果串流裝置與AuthN裝置不同，則AuthN裝置應該向使用者顯示成功的驗證訊息，並逐步繼續(例如「Success\！ 您現在可以返回遊戲主機以繼續[…]")。 如果串流裝置與AuthN裝置相同，則串流裝置可能會以程式設計方式偵測驗證完成。
下圖說明了驗證流程：
授權(authZ)
授權流程用於決定使用者是否有權存取請求的內容。
- 每次使用者嘗試在串流裝置應用程式上檢視受保護的內容時，串流裝置應用程式就會呼叫程式設計服務，識別內容並請求啟動串流所需的許可權和資訊。
- 程式設計師服務會呼叫Adobe Pass 授權 API，傳遞資源ID以及其他必要的引數。 Adobe服務使用資源ID呼叫MVPD AuthZ服務，並接收及授權決定，該決定隨後傳回至程式設計人員服務。 Adobe Pass服務將在可設定的期間內快取此授權決定。 後續從程式設計師服務呼叫Adobe Pass服務時，只要快取值有效，系統就會傳回該值 授權。
- 如果授權被授予，程式設計師服務應該呼叫Adobe Pass /權杖/媒體 API，這會傳回已簽署的媒體權杖。 程式設計師服務應使用媒體權杖驗證器程式庫(JAR)來驗證媒體權杖。 如果有效，程式設計師服務應該傳回許可權，以及啟動步驟#1中要求的資料流（例如資料流URL）所需的許可權。
- 如果授權被拒絕，authorize 呼叫將會傳回錯誤碼和描述給程式設計師服務。 程式設計師服務應傳回錯誤碼和說明（或程式設計師修改訊息）至步驟#1中的要求。
下圖說明授權流程：
登出
登出流程可讓使用者移除目前的身分
與應用程式相關聯。
- 當使用者要求登出（即從裝置移除與應用程式相關聯的目前MVPD帳戶）時，串流裝置應用程式會呼叫程式設計人員服務，告知其登出裝置。
- 程式設計師服務應該呼叫Adobe Pass 登出 API。
下圖說明登出流程：
[Optional]預先授權（又稱為預檢）
預先授權可用於從一組資源中快速判斷使用者可能擁有存取權。 此呼叫的結果通常用於自訂個別使用者的UI。
-
一旦使用者通過驗證，串流裝置就會呼叫程式設計人員服務，請求使用者有權串流的內容。
-
程式設計人員服務應使用資源ID清單呼叫Adobe Pass preauthorize API，這是一般代表使用者可能有權串流的管道的簡單字串。 注意：目前， 預先授權 呼叫已設定為將清單限製為五(5)個資源識別碼。 當需要超過五個資源時，可以發出多個 預先授權 呼叫，或者可以設定該呼叫以接受來自MVPD的超過五個資源。 實作者應牢記 預先授權 呼叫MVPD資源的成本，以及程式設計師的回應時間，並審慎建構其呼叫的使用方式。
-
preauthorize 呼叫會以要求中每個資源ID的JSON物件來回應程式設計人員服務，該物件包含TRUE或FALSE值，以指出使用者是否有權使用相關的頻道。 注意：如果MVPD沒有為指定的資源ID提供答案（例如，因為網路錯誤或逾時），值將預設為FALSE。
-
程式設計人員服務應使用 預先授權 呼叫回應，來建立對串流裝置的程式設計人員定義的自訂回應，通常是根據使用者的許可權來個人化簡報。
下圖說明預先授權流程：
[Optional]中繼資料
中繼資料可用來擷取MVPD共用的使用者資訊。
其範例可能包括使用者ID、郵遞區號等。
-
使用者通過驗證後，程式設計人員服務可能會呼叫Adobe Pass usermetadata API來要求有關已驗證使用者的資訊。
-
回應將包含給定使用者可用的所有中繼資料。 每個程式設計師/MVPD整合會分別設定特定欄位。
下圖說明預先授權流程：
環境和功能需求 environments
程式設計師應建立至少兩個環境：一個用於生產，一個或更多用於測試。
生產
生產環境應具備高可用性，且規模要適合大型或未預期的尖峰（例如即時運動、破損）
新聞)。
Adobe Pass服務可在分散於美國各地的多個資料中心執行。 為了讓Adobe Pass服務達到最佳的回應時間（即最低的延遲），程式設計師也應該建立類似的地理分散服務
基礎結構。
如果Adobe需要重新路由流量，程式設計師服務應該將DNS快取限製為最多30秒。 如果資料中心無法使用，就可能會發生這種情況。
程式設計師應提供生產環境的公用IP範圍。 這些會輸入到Adobe Pass基礎結構中的IP允許清單中，以供存取，並由Adobe的Fair API使用原則進行管理。
分段
中繼環境可以是最小的，但應包括所有系統元件和業務邏輯。 其功能應與生產環境類似，並允許在生產環境之外測試版本。 理想情況下，預備環境可連線至Adobe Pass測試環境以供程式設計師使用，並在需要時透過Adobe使用，以便我們可協助測試和疑難排解。
功能需求
程式設計師服務必須傳遞其執行流程之裝置的正確裝置識別資訊。 此外，程式設計師服務必須傳遞他們執行流程的裝置的IP （在x-forwarded-for標頭中）以及連線來源連線埠（在裝置資訊欄位中）：
**X-Forwarded-For ： \<client\_ip\>**
其中\<client\_ip\>是使用者端公用IP位址
需要在​**regcode**​和**authorize**​呼叫上新增標頭
範例：
POST/regggie/v1/{req\_id}/regcode HTTP/1.1
X-Forwarded-For：203.45.101.20
GET/api/v1/authorize HTTP/1
X-Forwarded-For：203.45.101.20
程式設計師服務應傳送個別MVPD或整合應用程式所需的資料和格式（例如裝置IP、來源連線埠、裝置資訊、MRSS、選擇性資料，例如ECID）。。
程式設計師服務必須在快取時遵守authN和authZ TTL，並在收到通知時使authN或authZ工作階段失效。
程式設計師必須維護與Adobe共用的憑證。