Apple SSO Cookbook (iOS/tvOS SDK) apple-sso-cookbook-iostvos-sdk
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
Settings -> TV Provider
on iOS/iPadOS or Settings -> Accounts -> TV Provider
on tvOS.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
- 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
- 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
-
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.
- *VSA403 - The user is signed in to its TV Provider account at
-
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).
- 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.
- 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.