Apple SSO クックブック(REST API) apple-sso-cookbook-rest-api
概要 Introduction
Adobe Pass認証 REST API は、Apple SSO ワークフローと呼ばれるワークフローを通じて、iOS、iPadOS、tvOS で動作するクライアントアプリケーションのエンドユーザーに対して、Platform シングルサインオン(SSO)認証をサポートできます。
このドキュメントは、既存の REST API ドキュメント( こちらの拡張機能として機能することに注意してください。
クックブック Cookbooks
Apple SSO のユーザーエクスペリエンスを活用するには、Appleが開発した ビデオ購読者アカウントフレームワークを 1 つのアプリケーションで統合する必要があります。一方、Adobe Pass認証 REST API 通信については、以下に示す一連のヒントに従う必要があります。
認証 Authentication
手順:「有効なAdobe認証トークンがあるか」 Is_there_a_valid_Adobe_authentication_token
手順:「ユーザーは Platform SSO を使用してログインしていますか?」 Is_the_user_logged_in_via_Platform_SSO
...
let videoSubscriberAccountManager: VSAccountManager = VSAccountManager();
videoSubscriberAccountManager.checkAccessStatus(options: [VSCheckAccessOption.prompt: true]) { (accessStatus, error) -> Void in
switch (accessStatus) {
// The user allows the application to access subscription information.
case VSAccountAccessStatus.granted:
// Construct the request for subscriber account information.
let vsaMetadataRequest: VSAccountMetadataRequest = VSAccountMetadataRequest();
// This is actually the SAML Issuer not the channel ID.
vsaMetadataRequest.channelIdentifier = "https://saml.sp.auth.adobe.com";
// This is the subscription account information needed at this step.
vsaMetadataRequest.includeAccountProviderIdentifier = true;
// This is the subscription account information needed at this step.
vsaMetadataRequest.includeAuthenticationExpirationDate = true;
// This is going to make the Video Subscriber Account framework to refrain from prompting the user with the providers picker at this step.
vsaMetadataRequest.isInterruptionAllowed = false;
// Submit the request for subscriber account information - accountProviderIdentifier.
videoSubscriberAccountManager.enqueue(vsaMetadataRequest) { vsaMetadata, vsaError in
if (vsaMetadata != nil && vsaMetadata!.accountProviderIdentifier != nil) {
// The vsaMetadata!.authenticationExpirationDate will contain the expiration date for current authentication session.
// The vsaMetadata!.authenticationExpirationDate should be compared against current date.
...
// The vsaMetadata!.accountProviderIdentifier will contain the provider identifier as it is known for the platform configuration.
// The vsaMetadata!.accountProviderIdentifier represents the platformMappingId in terms of Adobe Pass Authentication configuration.
...
// The application must determine the MVPD id property value based on the platformMappingId property value obtained above.
// The application must use the MVPD id further in its communication with Adobe Pass Authentication services.
...
// Continue with the "Obtain a profile request from Adobe for the selected MVPD" step.
...
// Continue with the "Forward the Adobe request to Platform SSO to obtain the profile" step.
...
} else {
// The user is not authenticated at platform level, continue with the "Fetch Adobe configuration" step.
...
}
}
// The user has not yet made a choice or does not allow the application to access subscription information.
default:
// Fallback to regular authentication workflow.
...
}
}
...
手順:「Adobe設定を取得」 Fetch_Adobe_configuration
enablePlatformServices
、boardingStatus
、displayInPlatformPicker
、platformMappingId
、requiredMetadataFields
)に注意し、他の手順のコードスニペットに表示されるコメントに特に注意してください。手順「Adobe設定を使用して Platform SSO ワークフローを開始する」 Initiate_Platform_SSO_workflow_with_Adobe_config
...
let videoSubscriberAccountManager: VSAccountManager = VSAccountManager();
// This must be a class implementing the VSAccountManagerDelegate protocol.
let videoSubscriberAccountManagerDelegate: VideoSubscriberAccountManagerDelegate = VideoSubscriberAccountManagerDelegate();
videoSubscriberAccountManager.delegate = videoSubscriberAccountManagerDelegate;
videoSubscriberAccountManager.checkAccessStatus(options: [VSCheckAccessOption.prompt: true]) { (accessStatus, error) -> Void in
switch (accessStatus) {
// The user allows the application to access subscription information.
case VSAccountAccessStatus.granted:
// Construct the request for subscriber account information.
let vsaMetadataRequest: VSAccountMetadataRequest = VSAccountMetadataRequest();
// This is actually the SAML Issuer not the channel ID.
vsaMetadataRequest.channelIdentifier = "https://saml.sp.auth.adobe.com";
// This is the subscription account information needed at this step.
vsaMetadataRequest.includeAccountProviderIdentifier = true;
// This is the subscription account information needed at this step.
vsaMetadataRequest.includeAuthenticationExpirationDate = true;
// This is going to make the Video Subscriber Account framework to prompt the user with the providers picker at this step.
vsaMetadataRequest.isInterruptionAllowed = true;
// This can be computed from the [Adobe Pass Authentication](https://experienceleague.adobe.com/docs/pass/authentication/programmer-integration-guide/restapi/rest-api-reference/provide-mvpd-list.html?lang=ja) service response in order to filter the TV providers from the Apple picker.
vsaMetadataRequest.supportedAccountProviderIdentifiers = supportedAccountProviderIdentifiers;
// This can be computed from the [Adobe Pass Authentication](https://experienceleague.adobe.com/docs/pass/authentication/programmer-integration-guide/restapi/rest-api-reference/provide-mvpd-list.html?lang=ja) service response in order to sort the TV providers from the Apple picker.
if #available(iOS 11.0, tvOS 11, *) {
vsaMetadataRequest.featuredAccountProviderIdentifiers = featuredAccountProviderIdentifiers;
}
// Submit the request for subscriber account information - accountProviderIdentifier.
videoSubscriberAccountManager.enqueue(vsaMetadataRequest) { vsaMetadata, vsaError in
// This represents the checks for the "Is user login successful?" step.
if (vsaMetadata != nil && vsaMetadata!.accountProviderIdentifier != nil) {
// The vsaMetadata!.authenticationExpirationDate will contain the expiration date for current authentication session.
// The vsaMetadata!.authenticationExpirationDate should be compared against current date.
...
// The vsaMetadata!.accountProviderIdentifier will contain the provider identifier as it is known for the platform configuration.
// The vsaMetadata!.accountProviderIdentifier represents the platformMappingId in terms of Adobe Pass Authentication configuration.
...
// The application must determine the MVPD id property value based on the platformMappingId property value obtained above.
// The application must use the MVPD id further in its communication with Adobe Pass Authentication services.
...
// Continue with the "Obtain a profile request from Adobe for the selected MVPD" step.
...
// Continue with the "Forward the Adobe request to Platform SSO to obtain the profile" step.
...
} else {
// The user is not authenticated at platform level.
if (vsaError != nil) {
// The application can check to see if the user selected a provider which is present in Apple picker, but the provider is not onboarded in platform SSO.
if let error: NSError = (vsaError! as NSError), error.code == 1, let appleMsoId = error.userInfo["VSErrorInfoKeyUnsupportedProviderIdentifier"] as! String? {
var mvpd: Mvpd? = nil;
// The requestor.mvpds must be computed during the "Fetch Adobe configuration" step.
for provider in requestor.mvpds {
if provider.platformMappingId == appleMsoId {
mvpd = provider;
break;
}
}
if mvpd != nil {
// Continue with the "Initiate second screen authentcation workflow" step, but you can skip prompting the user with your MVPD picker and use the mvpd selection, therefore creating a better UX.
...
} else {
// Continue with the "Initiate second screen authentcation workflow" step.
...
}
} else {
// Continue with the "Initiate second screen authentcation workflow" step.
...
}
} else {
// Continue with the "Initiate second screen authentcation workflow" step.
...
}
}
}
// The user has not yet made a choice or does not allow the application to access subscription information.
default:
// Fallback to regular authentication workflow.
...
}
}
...
手順:「ユーザーログインに成功しましたか?」 Is_user_login_successful
vsaMetadata!.accountProviderIdentifier
に有効な値が含まれ、現在の日付が vsaMetadata!.authenticationExpirationDate
値を渡していない場合、ユーザーログインは成功します。手順「選択した MVPD のAdobeからプロファイルリクエストを取得する」 Obtain_a_profile_request_from_Adobe_for_the_selected_MVPD
platformMappingId
を表していることに注意してください。 そのため、Adobe Pass Authentication Provide MVPD List サービスを通じて、platformMappingId
の値を使用して MVPD id プロパティの値を判断する必要があります。手順:「Adobeリクエストを Platform SSO に転送してプロファイルを取得する」 Forward_the_Adobe_request_to_Platform_SSO_to_obtain_the_profile
...
let videoSubscriberAccountManager: VSAccountManager = VSAccountManager();
videoSubscriberAccountManager.checkAccessStatus(options: [VSCheckAccessOption.prompt: true]) { (accessStatus, error) -> Void in
switch (accessStatus) {
// The user allows the application to access subscription information.
case VSAccountAccessStatus.granted:
// Construct the request for subscriber account information.
let vsaMetadataRequest: VSAccountMetadataRequest = VSAccountMetadataRequest();
// This is actually the SAML Issuer not the channel ID.
vsaMetadataRequest.channelIdentifier = "https://saml.sp.auth.adobe.com";
// This is going to include subscription account information which should match the provider determined in a previous step.
vsaMetadataRequest.includeAccountProviderIdentifier = true;
// This is going to include subscription account information which should match the provider determined in a previous step.
vsaMetadataRequest.includeAuthenticationExpirationDate = true;
// This is going to make the Video Subscriber Account framework to refrain from prompting the user with the providers picker at this step.
vsaMetadataRequest.isInterruptionAllowed = false;
// This are the user metadata fields expected to be available on a successful login and are determined from the [Adobe Pass Authentication](https://experienceleague.adobe.com/docs/pass/authentication/programmer-integration-guide/restapi/rest-api-reference/provide-mvpd-list.html?lang=ja) service. Look for the requiredMetadataFields associated with the provider determined in a previous step.
vsaMetadataRequest.attributeNames = requiredMetadataFields;
// This is the payload from [Adobe Pass Authentication](https://experienceleague.adobe.com/docs/pass/authentication/programmer-integration-guide/restapi/rest-api-reference/retrieve-profilerequest.html?lang=ja) service.
vsaMetadataRequest.verificationToken = profileRequestPayload;
// Submit the request for subscriber account information.
videoSubscriberAccountManager.enqueue(vsaMetadataRequest) { vsaMetadata, vsaError in
if (vsaMetadata != nil && vsaMetadata!.samlAttributeQueryResponse != nil) {
var samlResponse: String? = vsaMetadata!.samlAttributeQueryResponse!;
// Remove new lines, new tabs and spaces.
samlResponse = samlResponse?.replacingOccurrences(of: "[ \\t]+", with: " ", options: String.CompareOptions.regularExpression);
samlResponse = samlResponse?.components(separatedBy: CharacterSet.newlines).joined(separator: "");
samlResponse = samlResponse?.trimmingCharacters(in: CharacterSet.whitespacesAndNewlines);
// Base64 encode.
samlResponse = samlResponse?.data(using: .utf8)?.base64EncodedString(options: []);
// URL encode. Please be aware not to double URL encode it further.
samlResponse = samlResponse?.addingPercentEncoding(withAllowedCharacters: CharacterSet.init(charactersIn: "!*'();:@&=+$,/?%#[]").inverted);
// Continue with the "Exchange the Platform SSO profile for an Adobe authentication token" step.
...
} else {
// Fallback to regular authentication workflow.
...
}
}
// The user has not yet made a choice or does not allow the application to access subscription information.
default:
// Fallback to regular authentication workflow.
...
}
}
...
手順:「Platform SSO プロファイルをAdobe認証トークンと交換する」 Exchange_the_Platform_SSO_profile_for_an_Adobe_authentication_token
vsaMetadata!.samlAttributeQueryResponse!
は、 トークン交換で渡す必要がある SAMLResponse
を表し、呼び出しを行う前に文字列操作とエンコード(Base64 がエンコードされ、URL が後でエンコードされた)が必要です。手順:「Adobeトークンは正常に生成されましたか?」 Is_Adobe_token_generated_successfully
204 No Content
ールであるAdobe Pass認証 トークン交換成功応答を介して、これを実装します。手順:「2 番目の画面認証ワークフローの開始」 Initiate_second_screen_authentication_workflow
重要: 「2 番目の画面の認証ワークフロー」という用語は AppleTV に適していますが、「最初の画面の認証ワークフロー」/「通常の認証ワークフロー」という用語は iPhone と iPad に適しています。
登録コードリクエスト、 認証の開始および REST API 認証トークンの取得または 認証トークンの確認サービス。
- アプリケーションは、 登録コードを取得し、1 番目のデバイス(画面)でエンドユーザーに提示する必要があります。
- アプリケーションは、登録コードが取得された後、1 台目のデバイス(画面)で ポーリングして認証状態を確認する必要があります。
- 別のアプリケーションは、登録コードが使用される場合、2 番目のデバイス(画面)で 認証を開始する必要があります。
- 認証トークンが生成されると、アプリケーションは最初のデバイス 🔗 画面)で ポーリング)を停止する必要があります。
- アプリケーションは、 登録コードを取得する必要があります。このコードは、1 番目のデバイス(画面)でエンドユーザーに表示されるべきではありません。
- アプリケーションは、登録コードと WKWebView または SFSafariViewController コンポーネントを使用して、1 番目のデバイス(画面)で 認証を開始する必要があります。
- アプリケーションは、🔗WKWebView🔗 または SFSafariViewController コンポーネントが閉じた後、最初のデバイス(画面)で 認証状態に関する情報のポーリング を開始する必要があります。
- 認証トークンが生成されると、アプリケーションは最初のデバイス 🔗 画面)で ポーリング)を停止する必要があります。
手順:「認証フローを続行」 Proceed_with_authorization_flows
ログアウト Logout
ビデオ購読者アカウントフレームワークには、デバイスシステムレベルで TV プロバイダーアカウントにログインしたユーザーをプログラムでログアウトする API はありません。 そのため、ログアウトを完全に有効にするには、エンドユーザーはiOS/iPadOS の Settings -> TV Provider
または tvOS の Settings -> Accounts -> TV Provider
から明示的にログアウトする必要があります。 ユーザーが持つもう 1 つのオプションは、特定のアプリケーション設定セクション(TV プロバイダーへのアクセス)からユーザーの購読情報にアクセスするための権限を取り消すことです。
- アプリケーションは、Adobe Pass Authentication サービスの「tokenSource」 ユーザーメタデータを使用して、Platform SSO を使用したログインの結果として認証が発生したかどうかを判断する必要があります。
- "tokenSource" の値が「Apple **に等しい場合、tvOS の
Settings -> Accounts -> TV Provider
で明示的にログアウトするようにユーザーに指示またはプロンプトを表示する必要があります*のみ*。 - アプリケーションは、直接 HTTP 呼び出しを使用して、Adobe Pass Authentication サービスから ログアウトを開始する必要があります。 これは、MVPD 側でのセッションのクリーンアップを容易にするものではありません。
- アプリケーションは、Adobe Pass Authentication サービスの「tokenSource」 ユーザーメタデータを使用して、Platform SSO にログインした結果として認証が発生したかどうかを判断する必要があります。
- "tokenSource" の値が "Apple" に等しい場合、iOS/iPadOS のみ で
Settings -> TV Provider
から明示的にログアウトするようにユーザーに指示またはプロンプトする必要があります。 - アプリケーションは、🔗WKWebView🔗 または SFSafariViewController コンポーネントを使用して、Adobe Pass Authentication サービスから ログアウトを開始 する必要があります。 これにより、MVPD 側のセッションクリーンアップが容易になります。