Documentation Adobe Pass Adobe Pass Authentication

Apple SSO Cookbook (iOS/tvOS SDK) apple-sso-cookbook-iostvos-sdk

Last update: Tue Sep 12 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

Topics:
Authentication

NOTE

The content on this page is provided for information purposes only. Usage of this API requires a current license from Adobe. No unauthorized use is permitted.

Introduction Introduction

The Adobe Primetime Authentication AccessEnabler iOS/tvOS SDK can support platform Single Sign-On (SSO) authentication for end users of client applications running on iOS, iPadOS or tvOS through what we call Apple SSO workflow.

Please note that this document acts as an extension to the existing AccessEnabler iOS/tvOS SDK documentation, which can be found here.

Cookbook Cookbook

In order to benefit from the Apple SSO user experience, one application would need to integrate the AccessEnabler iOS/tvOS SDK and follow the sequence of tips presented below.

Prerequisites Prerequisites

Permission

TIP

Pro Tip: In order to have access to the user’s subscription information, the user must give the application permission to proceed, similar to providing access to the device’s camera or microphone. This permission must be requested per application and the device will save the user’s selection. Please bear in mind that the user can change its decision by going to the application settings (TV Provider permission access) or to the section from Settings -> TV Provider on iOS/iPadOS or Settings -> Accounts -> TV Provider on tvOS.

TIP

Pro Tip: We recommend requesting the user’s permission when the application enters the foreground state, but it is only a suggestion, because the application can check for permission to access the user’s subscription information at any point before requiring user authentication. Also, the AccessEnabler iOS/tvOS SDK APIs will automatically request the user’s permission when needing it.

TIP

Pro Tip: In case the user does not grant access to his subscription information or in case the communication with the Video Subscriber Account framework fails, then the AccessEnabler iOS/tvOS SDK will fallback to the regular authentication flow.

TIP

Pro Tip: We recommend incentivizing users who refuse to give permission to access subscription information by explaining the benefits of the Single Sign-On (SSO) user experience. Please bear in mind that the user can change its decision by going to the application settings (TV Provider permission access) or to the section from Settings -> TV Provider on iOS/iPadOS or Settings -> Accounts -> TV Provider on tvOS.

    ...
    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:
                   // Do nothing.

                // The user has not yet made a choice or does not allow the application to access subscription information.
                default:
                   // Incentivize users who refuse to give permission to access subscription information by explaining the benefits of the Single Sign-On (SSO) user experience. Please bear in mind that the user can change its decision by going to the application settings (TV Provider permission access) or to the section from Settings -> TV Provider on iOS/iPadOS or Settings -> Accounts -> TV Provider on tvOS.
                   ...
                }
    }
    ...

Callbacks

TIP

Pro Tip: Implement the following list of callbacks which are specific to the Apple SSO workflow.

presentTVProviderDialog - Callback triggered when the Apple MVPD picker is going to open.
dismissTVProviderDialog - Callback triggered when the Apple MVPD picker is going to close.

Error Reporting

TIP

Pro Tip: Implement the following list of advanced error codes which are specific to the Apple SSO workflow.

N003 - The user selected the “Other TV Provider” option from the Apple MVPD picker.
N004 - The user selected a TV Provider from the Apple MVPD picker, which is not supported (integration or Single Sign-On disabled) by the current requestor.
N005 - The user decided to cancel the regular MVPD picker or Apple MVPD picker.
VSA403 - The user’s TV Provider permission is denied for the application.
VSA404 - The user’s TV Provider permission is undetermined for the application.
VSA503 - The Video Subscriber Account metadata request failed, more context is provided in the message field.
AAPL / APPL_ERROR - The Video Subscriber Account metadata request failed, more context is provided in the details field.

Authentication Authentication

TIP

Tip: Follow the steps below for the iOS/iPadOS/tvOS implementation/s.

The application would have to initialise the AccessEnabler iOS/tvOS SDK.
The application would have to set the current requestor identifier.

Important: This second step could trigger an advanced error code which is specific to the Apple SSO workflow, in case one of the following is true:
- VSA403 - The user’s TV Provider permission is denied for the application.
- VSA404 - The user’s TV Provider permission is undetermined for the application.
- APPL - The communication between the AccessEnabler iOS/tvOS SDK and the Video Subscriber Account framework encountered an error.
This second step would try to silently exchange the Apple SSO profile for an Adobe authentication token, in case all of the above are false and all of the following are true:
- The user’s TV Provider permission is granted for the application.
- The user is signed in to its TV Provider account at the device system level.
- The AccessEnabler iOS/tvOS SDK received the user’s TV Provider identifier from the Video Subscriber Account framework.
- The user’s TV Provider integration with the application is enabled through the Adobe Primetime TVE Dashboard.
- The user’s TV Provider Single Sign-On with the application is enabled through the Adobe Primetime TVE Dashboard.
- The user’s TV Provider is not degraded through the Adobe Primetime TVE Dashboard.
- The AccessEnabler iOS/tvOS SDK received the user’s TV Provider SAML response from the Video Subscriber Account framework.
Pro Tip: This second step will not trigger any other callbacks, besides the setRequestorComplete callback, since authentication was not explicitly initiated by the application.
The application would have to check the authentication status.

Important: This third step could trigger an advanced error code which is specific to the Apple SSO workflow, in case one of the following is true:
- *VSA403 - The user is signed in to its TV Provider account at
  the device system level, but the user’s TV Provider permission is
  denied for the application.
- *VSA404 - The user is signed in to its TV Provider account at
  the device system level, but the user’s TV Provider permission
  is undetermined for the application.
- *APPL_ERROR - The user is signed in to its TV Provider
  account at the device system level, but the communication between
  the AccessEnabler iOS/tvOS SDK and the Video Subscriber Account
  framework encountered an error.
Important: This third step will trigger the setAuthenticationStatus callback with status equal to 0, in case one of the following is true:
- The user is not signed in to its TV Provider account at the device system level or through regular authentication flow.
- The user is signed in to its TV Provider account at the device system level or through regular authentication flow, but the user’s TV Provider authentication token TTL has passed.
- The user is signed in to its TV Provider account at the device system level or through regular authentication flow, but the user’s TV Provider integration with the application is disabled through the Adobe Primetime TVE Dashboard.
- The user is signed in to its TV Provider account at the device system level, but the user’s TV Provider Single Sign-On with the application is disabled through the Adobe Primetime TVE Dashboard.
- The user is signed in to its TV Provider account at the device system level, but the user’s TV Provider permission is denied for the application.
- The user is signed in to its TV Provider account at the device system level, but the user’s TV Provider permission is undetermined for the application.
- The user is signed in to its TV Provider account at the device system level, but the communication between the AccessEnabler iOS/tvOS SDK and the Video Subscriber Account framework encountered an error.
Important: This third step will trigger the setAuthenticationStatus callback with status equal to 1, in case all of the above are false.
The application would have to initialise the authentication in case the previous authentication status check triggered the setAuthenticationStatus callback with status equal to 0.

Pro Tip: Implement one of the following AccessEnabler iOS/tvOS SDK API getAuthentication or getAuthentication:filter.

Important: This fourth step could trigger an advanced error code which is specific to the Apple SSO workflow, in case one of the following is true:
- VSA403 - The user’s TV Provider permission is denied for the application.
- VSA404 - The user’s TV Provider permission is undetermined for the application.
- VSA503 - The communication between the AccessEnabler iOS/tvOS SDK and the Video Subscriber Account framework encountered an error.
- N003 - The user selected the “Other TV Provider” option from the Apple MVPD picker.
- N004 - The user selected a TV Provider from the Apple MVPD picker, which is not supported (integration or Single Sign-On disabled) by the current requestor.
- N005 - The user decided to cancel the regular MVPD picker or Apple MVPD picker.
Important: This fourth step would fallback to the regular authentication flow, by triggering the displayProviderDialog callback and one of the above advanced error codes, in case one of the above is true.

Important: This fourth step would fallback to the regular authentication flow, by triggering the navigateToUrl or navigateToUrl:useSVC callback and none of the above advanced error codes, in case the user selected a TV provider, which does not support Apple SSO, but is present in the Apple MVPD picker.

Pro Tip: The AccessEnabler iOS/tvOS SDK silently calls the setSelectedPrrovder API, in case the user selected a TV provider, which does not support Apple SSO, but is present in the Apple MVPD picker.

Important: This fourth step would try to silently exchange the Apple SSO profile for an Adobe authentication token, in case all of the above are false and all of the following are true:
- The user’s TV Provider permission is granted for the application.
- The user is signed in / currently signs in to its TV Provider account at the device system level.
- The AccessEnabler iOS/tvOS SDK received the user’s TV Provider identifier from the Video Subscriber Account framework.
- The user’s TV Provider integration with the application is enabled through the Adobe Primetime TVE Dashboard.
- The user’s TV Provider Single Sign-On with the application is enabled through the Adobe Primetime TVE Dashboard.
- The user’s TV Provider is not degraded through the Adobe Primetime TVE Dashboard.
- The AccessEnabler iOS/tvOS SDK received the user’s TV Provider SAML response from the Video Subscriber Account framework.

Pro Tip: This fourth step will trigger the setAuthenticationStatus callback, regardless of status result, since authentication was explicitly initiated by the application.

Metadata Metadata

The application has the option to determine if the authentication has happened as a result of a sign-in through the platform SSO or not, using the "tokenSource" user metadata API from the AccessEnabler iOS/tvOS SDK.

    ...
    accessEnabler.getMetadata([METADATA_OPCODE_KEY:Int(METADATA_USER_META), METADATA_USER_META_KEY: "tokenSource"])
    ...

Logout Logout

The Video Subscriber Account framework does not provide an API to programatically log out people who have signed in to their TV provider account at the device system level. Therefore, for the logout to take full effect, the end user would have to explicitly sign out from Settings -> TV Provider on iOS/iPadOS or Settings -> Accounts -> TV Provider on tvOS. The other option which the user would have is to withdraw permission to access the user’s subscription information from the specific application settings section (TV Provider permission access).

TIP

Tip: Implement this through the medium of AccessEnabler iOS/tvOS SDK logout API.

TIP

Pro Tip: Follow the steps below for the tvOS implementation/s.

The application would have to initiate the logout from the AccessEnabler iOS/tvOS SDK. This would not facilitate session clean-up on the MVPD side.
The application would have to instruct/prompt the user to explicitly sign out from Settings -> Accounts -> TV Provider on tvOS only in case VSA203 status code is triggered.

TIP

Pro Tip: Follow the steps below for the iOS/iPadOS implementation/s.

The application would have to initiate the logout from the AccessEnabler iOS/tvOS SDK. This would facilitate session clean-up on the MVPD side.
The application would have to instruct/prompt the user to explicitly sign out from Settings -> TV Provider on iOS/iPadOS only in case VSA203 status code is triggered.

recommendation-more-help

3f5e655c-af63-48cc-9769-2b6803cc5f4b