Apple SSO クックブック（REST API V2） apple-sso-cookbook-rest-api-v2
Adobe Pass認証 REST API V2 は、iOS、iPadOS、tvOS で動作するクライアントアプリケーションのエンドユーザー向けに、パートナーシングルサインオン（SSO）をサポートしています。
このドキュメントは、既存の REST API V2 概要の拡張機能として機能し概要の概要と、 パートナーフローを使用したシングルサインオンを実装する方法を説明するドキュメントを提供します。
パートナーフローを使用したAppleのシングルサインオン cookbook
前提条件 prerequisites
パートナーフローを使用してAppleのシングルサインオンを続行する前に、次の前提条件が満たされていることを確認してください。
-
ストリーミングアプリケーションは、Adobe Pass Authentication バックエンドがデバイスプラットフォームとその機能を識別できるように、
X-Device-InfoやUser-Agentヘッダーで必要なすべてのデータを収集する必要があります。 ヘッダーについて詳X-Device-Infoくは、X-Device-Info ドキュメントを参照してください。 -
ストリーミングアプリケーションは、デバイスレベルで保存されたユーザーの購読情報へのアクセスをリクエストする必要があります。これに対して、ユーザーは、デバイスのカメラまたはマイクへのアクセスを提供するのと同様に、続行を許可するアプリケーション権限を付与する必要があります。 この権限は、Apple ビデオ購読者のアカウントフレームワークを使用しているアプリケーションごとにリクエストされる必要があります。
Appleのシングルサインオンユーザーエクスペリエンスの利点を説明することで、購読情報へのアクセスを拒否するユーザーにインセンティブを与えることをお勧めしますが、アプリ設定（TV プロバイダーのアクセス）またはiOSと iPadOS または tvOS の
Settings -> Accounts -> TV Providerを使用するSettings -> TV Providerとで、ユーザーが判断を変えることができることに注意してください。ストリーミングアプリケーションは、アプリケーションがフォアグラウンド状態になると、ユーザー認証を要求する前の任意の時点でユーザーの購読情報に対する アクセス許可を確認できるので、ユーザーの許可を要求できます。
- ストリーミングアプリケーションは、プログラマーに適用され、Appleのシングルサインオンユーザーエクスペリエンスを有効にするために必要な オンボーディングの前提条件を完了しています。
ワークフロー workflow
次の図に示すパートナーフローを使用してAppleのシングルサインオンを実装するには、指定された手順を実行します。
パートナーフローを使用したAppleのシングルサインオン
-
クライアント資格情報の取得： ストリーミングアプリケーションは、クライアント登録エンドポイントを呼び出してクライアント資格情報を取得するために必要なすべてのデータを収集します。
note important IMPORTANT 次について詳しくは、 クライアント資格情報の取得API ドキュメントを参照してください。 software_statementのようなすべての 必須 パラメーターContent-Type、X-Device-Infoなどのすべての 必須 ヘッダー- すべての オプション パラメーターおよびヘッダー
-
クライアント資格情報を返す： クライアント登録エンドポイント応答には、受信したパラメーターおよびヘッダーに関連付けられたクライアント資格情報に関する情報が含まれます。
note important IMPORTANT クライアント資格情報応答で提供される情報について詳しくは、 クライアント資格情報の取得API ドキュメントを参照してください。 クライアントレジスタがリクエストデータを検証し、基本的な条件が満たされていることを確認します。 - required パラメーターおよびヘッダーは有効である必要があります。
検証に失敗した場合は、エラー応答が生成され、 クライアント資格情報の取得API ドキュメントに従った追加情報が提供されます。 note tip TIP 提案：クライアントの資格情報はキャッシュする必要があり、無期限に使用される可能性があります。 -
アクセストークンを取得： ストリーミングアプリケーションは、クライアントトークンエンドポイントを呼び出してアクセストークンを取得するために必要なすべてのデータを収集します。
note important IMPORTANT 次について詳しくは、 アクセストークンの取得API ドキュメントを参照してください。 client_id、client_secret、grant_typeなど、すべての 必須 パラメーターContent-Type、X-Device-Infoなどのすべての 必須 ヘッダー- すべての オプション パラメーターおよびヘッダー
-
アクセストークンを返す： クライアントトークンエンドポイント応答には、受信したパラメーターとヘッダーに関連付けられたアクセストークンに関する情報が含まれています。
note important IMPORTANT アクセストークン応答で提供される情報について詳しくは、 アクセストークンの取得API ドキュメントを参照してください。 クライアントトークンは、リクエストデータを検証して、基本的な条件が満たされていることを確認します。 - required パラメーターおよびヘッダーは有効である必要があります。
検証に失敗した場合は、エラー応答が生成され、 アクセストークンの取得API ドキュメントに準拠する追加情報が提供されます。 note tip TIP 提案：アクセストークンは、指定された期間（例：24 時間の有効期間）内にのみキャッシュおよび使用する必要があります。 有効期限が切れた後、ストリーミングアプリケーションは新しいアクセストークンをリクエストする必要があります。
-
パートナーフレームワークのステータスの取得： ストリーミングアプリケーションは、Appleが開発した ビデオ購読者アカウントフレームワークを呼び出して、ユーザー権限とプロバイダー情報を取得します。
note important IMPORTANT 次の項目について詳しくは、 ビデオ購読者のアカウントフレームワークドキュメントを参照してください。 ストリーミングアプリケーションは、このフェーズでユーザーを中断できないことを示すために、必ず VSAccountMetadataRequestオブジェクトのisInterruptionAllowedプロパティのブール値がfalseに等しいことを指定する必要があります。 -
パートナーフレームワークのステータス情報を返す： ストリーミングアプリケーションは、基本条件が満たされていることを確認するために応答データを検証します。
- ユーザー権限のアクセスステータスが付与されます。
- ユーザープロバイダーマッピング識別子が存在し、有効です。
- ユーザープロバイダープロファイルの有効期限（使用可能な場合）は有効です。
-
プロファイルの取得： ストリーミングアプリケーションは、プロファイルエンドポイントにリクエストを送信することで、すべてのプロファイル情報を取得するために必要なすべてのデータを収集します。
note important IMPORTANT 次について詳しくは、 プロファイルの取得API ドキュメントを参照してください。 serviceProviderのようなすべての 必須 パラメーターAuthorization、AP-Device-Identifier、AP-Partner-Framework-Statusなど、すべての 必須 ヘッダー- すべての オプション パラメーターおよびヘッダー
ストリーミングアプリケーションは、取得した応答に「appleSSO」タイプのプロファイルを含められるように、パートナーフレームワークステータスに有効な値が含まれていることを確認する必要があります。 ヘッダーについて詳 AP-Partner-Framework-Statusくは、AP-Partner-Framework-Status ドキュメントを参照してください。 -
見つかったプロファイルに関する情報を返す： プロファイルエンドポイント応答には、受信したパラメーターとヘッダーに関連付けられた、見つかったプロファイルに関する情報が含まれます。
-
プロファイルを選択し、決定フローを続行： プロファイルエンドポイント応答にプロファイルが含まれている場合、ストリーミングアプリケーションは（最終的にエンドユーザーとやり取りすることで）内部ロジックを使用して、使用可能なプロファイルの 1 つを選択し、後続の決定フローを続行します。
-
パートナー認証フローを続行： プロファイルエンドポイント応答にプロファイルが含まれていない場合、ストリーミングアプリケーションはパートナー認証フローを続行します。
-
設定の取得： ストリーミングアプリケーションは、設定エンドポイントにリクエストを送信して、アクティブな統合を持つ MVPD のリストを取得するために必要なすべてのデータを収集します。
note important IMPORTANT 次の項目について詳しくは、 特定のサービスプロバイダーの設定の取得API ドキュメントを参照してください。 serviceProviderのようなすべての 必須 パラメーターAuthorization、AP-Device-Identifier、X-Device-Infoなど、すべての 必須 ヘッダー- すべての オプション パラメーターおよびヘッダー
-
設定を返す： 設定エンドポイント応答には、サービスプロバイダーとアクティブに統合されている MVPD に関する情報が含まれています。
note important IMPORTANT 設定応答で提供される情報について詳しくは、 特定のサービスプロバイダーの設定の取得API ドキュメントを参照してください。 設定エンドポイントは、基本条件が満たされていることを確認するためにリクエストデータを検証します。 - required パラメーターおよびヘッダーは有効である必要があります。
検証に失敗した場合は、エラー応答が生成され、 拡張エラーコードに従った追加情報が提供されます note important IMPORTANT ストリーミングアプリケーションは、続行する際に、各 MVPD に提供される次の詳細を処理する必要があります。 enablePlatformServices:MVPD が現在Appleのシングルサインオンをサポートしているかどうかを示します。displayInPlatformPicker: MVPD をApple ピッカーに表示できるかどうかを示します。boardingStatus: Appleのシングルサインオンで MVPD がオンボードされるかどうかを示します。
-
パートナーフレームワークのステータスの取得： ストリーミングアプリケーションは、Appleが開発した ビデオ購読者アカウントフレームワークを呼び出して、ユーザー権限とプロバイダー情報を取得します。
note important IMPORTANT 次の項目について詳しくは、 ビデオ購読者のアカウントフレームワークドキュメントを参照してください。 ストリーミングアプリケーションは、ユーザーがこの段階で TV プロバイダーを選択するために中断できることを示すために、 VSAccountMetadataRequestオブジェクトのisInterruptionAllowedプロパティのブール値がtrueに等しいことを指定する必要があります。 -
パートナーフレームワークのステータス情報を返す： ストリーミングアプリケーションは、基本条件が満たされていることを確認するために応答データを検証します。
- ユーザー権限のアクセスステータスが付与されます。
- ユーザープロバイダーマッピング識別子が存在し、有効です。
- ユーザープロバイダープロファイルの有効期限（使用可能な場合）は有効です。
-
パートナー認証リクエストの取得： ストリーミングアプリケーションは、セッションパートナーエンドポイントを呼び出して認証セッションを開始するために必要なすべてのデータを収集します。
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 ドキュメントを参照してください。 セッションパートナーエンドポイントは、基本条件が満たされていることを確認するためにリクエストデータを検証します。 - required パラメーターおよびヘッダーは有効である必要があります。
- 指定した
serviceProviderとmvpdの統合はアクティブである必要があります。
基本検証が失敗した場合は、エラー応答が生成され、 拡張エラーコードドキュメントに従った追加情報が提供されます。 セッションパートナーエンドポイントは、リクエストデータを検証して、パートナーのシングルサインオン条件が満たされていることを確認します。 - Adobe Pass サーバーのパートナーのシングルサインオン設定が有効であり、有効である必要があります。
- AP-Partner-Framework-Status ヘッダーを介して受信したパートナーフレームワークステータスペイロードは、有効である必要があります。
パートナーのシングルサインオン検証が失敗した場合、応答はデフォルトで基本認証フローに設定されます。 -
決定フローで続行： セッションパートナーエンドポイント応答には、次のデータが含まれます。
actionName属性は「authorize」に設定されます。actionType属性は「direct」に設定されます。
Adobe Pass バックエンドが有効なプロファイルを特定した場合、選択された MVPD でストリーミングアプリケーションを再認証する必要はありません。その後の決定フローで使用できるプロファイルが既に存在するからです。
-
基本認証フローを続行： セッションパートナーエンドポイント応答には、次のデータが含まれています。
actionName属性は、「authenticate」または「resume」に設定されます。actionType属性は、「interactive」または「direct」に設定されます。
Adobe Pass バックエンドが有効なプロファイルを識別せず、パートナーのシングルサインオン検証に失敗した場合、Adobe Pass サーバーは基本認証フローにフォールバックします。
基本認証フローについて詳しくは、次のドキュメントを参照してください。
-
パートナー認証応答フローを使用したプロファイルの取得に進みます： セッションパートナーエンドポイント応答には、次のデータが含まれています。
actionName属性は「partner_profile」に設定されます。actionType属性は「direct」に設定されます。authenticationRequest - type属性には、MVPD ログイン用のパートナーフレームワークによって使用されるセキュリティプロトコルが含まれます（現在は SAML のみに設定されています）。authenticationRequest - request属性には、パートナーフレームワークに渡される SAML リクエストが含まれます。authenticationRequest - attributesNames属性には、パートナーフレームワークに渡される SAML 属性が含まれます。
Adobe Pass バックエンドが有効なプロファイルを識別できず、パートナーのシングルサインオン検証に合格した場合、ストリーミングアプリケーションはアクションとデータを含む応答を受け取り、MVPD を使用した認証フローを開始するためにパートナーフレームワークに渡します。
-
パートナーフレームワークで MVPD 認証を完了： 前の手順で取得したパートナー認証要求（SAML 要求）を ビデオ購読者アカウントフレームワークに転送します。 認証フローが成功すると、MVPD との ビデオ加入者アカウントフレームワークインタラクションによってパートナー認証応答（SAML 応答）が生成され、パートナーフレームワークのステータス情報と共に返されます。
note important IMPORTANT 次の項目について詳しくは、 ビデオ購読者のアカウントフレームワークドキュメントを参照してください。 ストリーミングアプリケーションは、このフェーズでユーザーが選択された TV プロバイダーによる認証を中断できることを示すために、 VSAccountMetadataRequestオブジェクトのisInterruptionAllowedプロパティのブール値がtrueに等しいことを指定する必要があります。 -
パートナー認証応答を返す： ストリーミングアプリケーションは、基本条件が満たされていることを確認するために応答データを検証します。
- ユーザー権限のアクセスステータスが付与されます。
- ユーザープロバイダーマッピング識別子が存在し、有効です。
- ユーザープロバイダープロファイルの有効期限（使用可能な場合）は有効です。
- パートナー認証応答（SAML 応答）が存在し、有効です。
-
パートナー認証応答を使用したプロファイルの取得： ストリーミングアプリケーションは、プロファイルパートナーエンドポイントを呼び出してプロファイルを作成および取得するために必要なすべてのデータを収集します。
note important IMPORTANT 次について詳しくは、 パートナー認証応答を使用したプロファイルの取得API ドキュメントを参照してください。 serviceProvider、partner、SAMLResponseなど、すべての 必須 パラメーターAuthorization、AP-Device-Identifier、Content-Type、X-Device-Info、AP-Partner-Framework-Statusなど、すべての 必須 ヘッダー- すべての オプション ヘッダーとパラメーター
ストリーミングアプリケーションは、取得した応答に「appleSSO」タイプのプロファイルを含められるように、パートナーフレームワークステータスおよびパートナー認証応答（SAML 応答）の有効な値が含まれていることを確認する必要があります。 ヘッダーについて詳 AP-Partner-Framework-Statusくは、AP-Partner-Framework-Status ドキュメントを参照してください。 -
パートナープロファイルに関する情報を返す： プロファイルエンドポイント応答には、「appleSSO」に設定されている属性
typeど、パートナープロファイルに関する情報が含まれています。note important IMPORTANT プロファイル応答で提供される情報について詳しくは、 パートナー認証応答を使用したプロファイルの取得API ドキュメントを参照してください。 プロファイルパートナーエンドポイントは、基本条件が満たされていることを確認するために、リクエストデータを検証します。 - required パラメーターおよびヘッダーは有効である必要があります。
- 指定した
serviceProviderとmvpdの統合はアクティブである必要があります。
検証に失敗した場合は、エラー応答が生成され、 拡張エラーコードドキュメントに従った追加情報が提供されます。 プロファイルパートナーエンドポイントは、リクエストデータを検証して、パートナーのシングルサインオン条件が満たされていることを確認します。 - Adobe Pass サーバーのパートナーのシングルサインオン設定が有効であり、有効である必要があります。
- AP-Partner-Framework-Status ヘッダーを介して受信したパートナーフレームワークステータスペイロードは、有効である必要があります。
パートナーのシングルサインオン検証が失敗した場合、応答はデフォルトで基本プロファイル取得フローに設定されます。 -
決定フローで続行： ストリーミングアプリケーションは、後続の決定フローで続行できます。
-
パートナーフレームワークのステータスの取得： ストリーミングアプリケーションは、Appleが開発した ビデオ購読者アカウントフレームワークを呼び出して、ユーザー権限とプロバイダー情報を取得します。
note important IMPORTANT 次の項目について詳しくは、 ビデオ購読者のアカウントフレームワークドキュメントを参照してください。 ストリーミングアプリケーションは、このフェーズでユーザーを中断できないことを示すために、必ず VSAccountMetadataRequestオブジェクトのisInterruptionAllowedプロパティのブール値がfalseに等しいことを指定する必要があります。note tip TIP 提案：ストリーミングアプリケーションでは、パートナーフレームワークのステータス情報にキャッシュされた値を使用できます。アプリケーションがバックグラウンド状態からフォアグラウンド状態に移行する際には、更新することを推奨します。 -
パートナーフレームワークのステータス情報を返す： ストリーミングアプリケーションは、基本条件が満たされていることを確認するために応答データを検証します。
- ユーザー権限のアクセスステータスが付与されます。
- ユーザープロバイダーマッピング識別子が存在し、有効です。
- ユーザープロバイダープロファイルの有効期限（使用可能な場合）は有効です。
-
事前認証決定の取得： ストリーミングアプリケーションは、決定の事前認証エンドポイントを呼び出すことにより、リソースのリストに対する事前認証決定を取得するために必要なすべてのデータを収集します。
note important IMPORTANT 次の項目について詳しくは、 特定の mvpd を使用した事前認証の決定の取得API ドキュメントを参照してください。 serviceProvider、mvpd、resourcesなど、すべての 必須 パラメーターAuthorizationやAP-Device-Identifierなど、すべての 必須 ヘッダー- すべての オプション パラメーターおよびヘッダー
選択したプロファイルが「appleSSO」タイプのプロファイルの場合、ストリーミングアプリケーションがリクエストを送信する前に、パートナーフレームワークステータスに有効な値が含まれていることを確認する必要があります。 ヘッダーについて詳 AP-Partner-Framework-Statusくは、AP-Partner-Framework-Status ドキュメントを参照してください。 -
再来訪の事前認証の決定： 決定の事前認証エンドポイント応答には、各リソースの
PermitまたはDenyの決定が含まれています。Permitの決定は、リソースが再生可能であることを意味します。 事前認証フローはリソースの再生に使用できないので、応答にはメディアトークンが含まれていません。Denyの決定は、リソースが再生可能でないことを意味します。 応答には、 拡張エラーコードドキュメントに従ったエラーペイロードが含まれています。
note important IMPORTANT 決定応答で提供される情報について詳しくは、 特定の mvpd を使用した事前認証の決定の取得API ドキュメントを参照してください。 決定の事前認証エンドポイントは、基本条件が満たされていることを確認するためにリクエストデータを検証します。 - required パラメーターおよびヘッダーは有効である必要があります。
- 指定した
serviceProviderとmvpdの統合はアクティブである必要があります。
検証に失敗した場合は、エラー応答が生成され、 拡張エラーコードドキュメントに従った追加情報が提供されます。 -
パートナーフレームワークのステータスの取得： ストリーミングアプリケーションは、Appleが開発した ビデオ購読者アカウントフレームワークを呼び出して、ユーザー権限とプロバイダー情報を取得します。
note important IMPORTANT 次の項目について詳しくは、 ビデオ購読者のアカウントフレームワークドキュメントを参照してください。 ストリーミングアプリケーションは、このフェーズでユーザーを中断できないことを示すために、必ず VSAccountMetadataRequestオブジェクトのisInterruptionAllowedプロパティのブール値がfalseに等しいことを指定する必要があります。note tip TIP 提案：ストリーミングアプリケーションでは、パートナーフレームワークのステータス情報にキャッシュされた値を使用できます。アプリケーションがバックグラウンド状態からフォアグラウンド状態に移行する際には、更新することを推奨します。 -
パートナーフレームワークのステータス情報を返す： ストリーミングアプリケーションは、基本条件が満たされていることを確認するために応答データを検証します。
- ユーザー権限のアクセスステータスが付与されます。
- ユーザープロバイダーマッピング識別子が存在し、有効です。
- ユーザープロバイダープロファイルの有効期限（使用可能な場合）は有効です。
-
認証決定の取得： ストリーミングアプリケーションは、決定の承認エンドポイントを呼び出して、特定のリソースの認証決定を取得するために必要なすべてのデータを収集します。
note important IMPORTANT 次の項目について詳しくは、 特定の mvpd を使用した認証決定の取得API ドキュメントを参照してください。 serviceProvider、mvpd、resourcesなど、すべての 必須 パラメーターAuthorizationやAP-Device-Identifierなど、すべての 必須 ヘッダー- すべての オプション パラメーターおよびヘッダー
選択したプロファイルが「appleSSO」タイプのプロファイルの場合、ストリーミングアプリケーションがリクエストを送信する前に、パートナーフレームワークステータスに有効な値が含まれていることを確認する必要があります。 ヘッダーについて詳 AP-Partner-Framework-Statusくは、AP-Partner-Framework-Status ドキュメントを参照してください。 -
再来訪承認決定： 決定の承認エンドポイント応答には、特定のリソースの
PermitまたはDenyの決定が含まれています。Permitの決定は、リソースが再生可能であることを意味します。 応答にはメディアトークンが含まれます。Denyの決定は、リソースが再生可能でないことを意味します。 応答には、 拡張エラーコードドキュメントに従ったエラーペイロードが含まれています。
note important IMPORTANT 決定応答で提供される情報について詳しくは、 特定の mvpd を使用した認証の決定の取得API ドキュメントを参照してください。 決定の認証エンドポイントは、基本条件が満たされていることを確認するためにリクエストデータを検証します。 - required パラメーターおよびヘッダーは有効である必要があります。
- 指定した
serviceProviderとmvpdの統合はアクティブである必要があります。
検証に失敗した場合は、エラー応答が生成され、 拡張エラーコードドキュメントに従った追加情報が提供されます。
-
Adobe Pass ログアウトの開始： ストリーミングアプリケーションは、Adobe Pass ログアウトエンドポイントを呼び出して、ログアウトフローを開始するために必要なすべてのデータを収集します。
note important IMPORTANT 次の項目について詳しくは、 特定の mvpd のログアウトの開始API ドキュメントを参照してください。 serviceProvider、mvpd、redirectUrlなど、すべての 必須 パラメーターAuthorization、AP-Device-Identifierなどのすべての 必須 ヘッダー- すべての オプション パラメーターおよびヘッダー
-
次のアクションを示す： Adobe Pass ログアウトエンドポイント応答には、次のアクションに関するストリーミングアプリケーションのガイドに必要なデータが含まれています。
note important IMPORTANT ログアウト応答で提供される情報について詳しくは、 特定の mvpd のログアウトの開始API ドキュメントを参照してください。 Adobe Pass ログアウトエンドポイントは、基本的な条件が満たされていることを確認するためにリクエストデータを検証します。 - required パラメーターおよびヘッダーは有効である必要があります。
- 指定した
serviceProviderとmvpdの統合はアクティブである必要があります。
検証に失敗した場合は、エラー応答が生成され、 拡張エラーコードドキュメントに従った追加情報が提供されます。 note important IMPORTANT ストリーミングアプリケーションでは、ユーザーがパートナーレベルからさらにログアウトし続けるように指定する必要があります。