Have you have followed the Adobe Primetime Single Sign-On (SSO) integration documentation, but it’s not working as expected?
A common problem that users face is when they are not able to select a Multi-Channel Video Programming Distributor (MVPD) to log into from a list of MVPDs within your app. Another scenario is users who have successfully logged into a selected MVPD, but keep getting asked to log in every time they try to play content within your app.
The tips in this blog will help you get past some of these very issues.
Recap of SSO on Fire TV
SSO allows customers who authenticate in one SSO app to not have to authenticate again when logging into another SSO-enabled app. Adobe provides the Primetime authentication API to facilitate this method of authentication for third party TV Everywhere (TVE) apps on Fire TV.
Adobe provides Fire TV client developers with a stub library with its APIs. Developers need to use Fire OS system level APIs to retrieve a personalized token and use it when calling Adobe APIs. And, the Fire OS system level APIs are encapsulated within a Fire TV system app, called the SSO companion app.
Here is a set of diagrams that explains the SSO workflow.
There are 4 key steps in the SSO workflow:
- Initialization: The Android client application initiates Adobe Primetime authentication using the Adobe Primetime authentication native Amazon Fire OS library (AccessEnabler).
- Authentication: This starts the authentication flow, or gets confirmation that the user is already authenticated.
- Authorization: This is the authorization flow and ensures that the user is authenticated and authorized to watch the requested media. It returns a short media token.
- Media token issuance: The short media token is then validated. If valid, it is issued to the Android client application and the media is played for the user.
Here is a breakdown of each of these steps in the SSO process.
Step 1: Initialization
In this step, the Android client application initializes the Adobe Primetime Authentication native Amazon Fire OS library (AccessEnabler) that has been integrated with the application. It establishes the identity of the application using a personalized token, and then proceeds to the Authentication flow.
Step 2: Authentication
The Android client application now starts the authentication flow, or gets confirmation that the user is already authenticated. If the user is not authenticated, the user is presented with a list of MVPD providers. After the user selects a provider, the provider page is opened for the user to login. Upon successful login by the user, the authentication token is retrieved from the backend Adobe server. The token is validated and the user proceeds to the Authorization flow.
Step 3: Authorization
The Android client application next gets the authorization token, and then validates the authentication and authorization tokens. This means checking whether the user is authenticated and authorized to watch the requested media. If there is an authentication (AuthN) error, then the authentication flow is re-started. If there is an authorization (AuthZ) error, then the user is not authorized to watch the requested media and a relevant error message is displayed to the user. If authorization is successful, a short media token is returned by Adobe’s server.
Step 4: Media Token Issuance
Next, the short-lived media token returned from the authorization flow is validated by the Adobe server. If the validation succeeds, the Android client application plays the requested media for the user. However, if the validation fails, The AuthZ token was invalid, the media request is refused, and an error message is displayed to the user.
Now that you have an overview of how the SSO process flow works, let’s get into some of the issues you can face and how to solve them.
Tip #1: App not authorized to use SSO on Fire TV
A common SSO error, as we mentioned above, is that when users select a valid MVPD provider (see figure Step 2: Authentication) to log into in order to play their content, instead of seeing the MVPD provider’s login page, they loop back into the provider picker page.
The user is following the entitlement steps in this workflow (also see figure 1: High-Level Single Sign-on Flow).
Your call to authenticate the user initially should successfully log the user into to a selected MVPD using valid credentials and store the returned authentication token in the backend server. Subsequent call(s) to authenticate should ideally get confirmation that the user is already authenticated, and the user should then be authorized to single-sign on into the app. However, these calls fail, and the user keeps getting asked to login into the MVPD.
This error may simply be a function of your app not being authorized or allow-listed to use Single-Sign-On (SSO) on Fire TV platforms.
In the workflow in Figure 1, before the SSO companion app checks if the authentication is complete, under the hood, it checks to see if the app is allow-listed, i.e. whether the app is authorized to use SSO on Fire TV. If not, it does not allow the user to proceed beyond the MVPD list display page.
To determine if this is indeed the reason for the login issue, look for the following error in your device logs:
E/OttSso_OttSsoService: Trying to verify app com.yourappname.yourpackagename but Approved apps list size is 0.This error means that your app needs to be authorized to use SSO on Fire TV platforms. Please work with your Fire TV Solutions Architect at Amazon to get this done.
Once your app package name has been authorized for SSO, you need to wait for 24 hours for the device cache to be refreshed. If you are still facing the same error, check your package name. Please note that both the debug and production package names need to be allow-listed.
If you are still running into the same errors, you will need to clear the companion app cache manually with the following commands:
adb shell pm clear com.amazon.tv.ottssocompanionapp
adb shell am force-stop com.amazon.tv.ottssocompanionapp
Now when the user goes through your app login workflow again, instead of the E/OttSso_OttSsoService error in your device logs, they will be able to log in successfully with valid credentials. And the following line will appear in the device logs as proof that your app is now allow-listed for SSO on Fire TV:
I OttSso_OttSsoService: app setup complete, number of approved apps Tip #2: Adobe SDK and SSO Companion version mismatch
The Adobe SDK that your app has integrated with is a stub library which makes calls to the SSO companion system app on Fire TV to deliver SSO functionality. For SSO to work correctly with your apps on Fire TV, both the SSO companion app and the Adobe stub library integrated within your app should always be up-to-date with their most recent versions.
To check the version of this app via ADB, use the following command:
Mac:
adb shell dumpsys package com.amazon.tv.ottssocompanionapp | grep versionCodeWindows:
adb shell dumpsys package com.amazon.tv.ottssocompanionapp | find /I "versionCode"Results:
Old version output:
In the example stated above, the last updated version number of the SSO companion app on this specific device is 4810. However, the latest version of the Adobe SDK requires the system SSO companion app to be of version number 5510 or greater. To update the SSO companion app in SMP devices, go to device Settings->My Fire TV->About->Check for Updates. In Fire TV Edition devices, go to device Settings->Device & Software->About->Check for Updates. Run this command repeatedly, until there are no more system updates left to be received. When you run your adb version command again, the results should now be as follows:
To prevent your app users from facing SSO issues because they have not updated their device system OS recently, the app should perform a version check and nudge the users to update their app and device OS.
For more information about Single-Sign On, please see this documentation on Adobe Primetime Authentication Fire TV SDK.
