Apple TV Authentication Context

Shloka Kini: The authentication context is a web service that presents the authentication UI and communicates with your identity provider server to authenticate your customer's credentials.

It is one of many steps you will need to take to get the Single Sign-On feature for your TV provider on iOS and tvOS devices as part of the Apple TV distribution program.

The authentication context is a web service hosted on your server that is downloaded to an Apple device and executed at run time.

When the authentication context passes an authentication response to the VideoSubscriberAccount framework it is saved into the device keychain.

On iOS devices the authentication response can be synced to other iOS devices via iCloud Keychain.

And on Apple TV, the authentication response will not leave the device because tvOS does not support iCloud Keychain.

The purpose of the authentication context is to provide OS-level authentication across supported apps.

The first step of this process is to prompt a person to type in their credentials by presenting them UI for authentication.

To specify the UI for this credential entry, use an authenticationTemplate.

This is an XML document similar to the examples we provide in documentation.

When you provide us this XML, we take it and format it to look like part of the Apple system UI, depending on which platform the person is using.

For example, the default username-password template here, can be applied to both iOS and tvOS devices.

The autoAuthenticationTemplate doesn't ask the customer to enter credentials.

Instead, it informs the customer which account they will be automatically authenticated to, and gives them an option to manually sign in to a different account.

This template is also applicable to both iOS and tvOS devices.

If you are not able to directly take credentials from a customer, we provide alternative templates for authentication in special cases.

The onscreenCode AuthenticationTemplate only applies to tvOS.

It displays an onscreen code for a person to enter on a web browser on a separate device, such as their phone, tablet, or computer.

The webAuthenticationTemplate applies only to iOS devices.

It launches a web view, like this, using the URL specified.

To communicate between the authentication context and the web view that is launched, you use the VideoSubscriberAccount class.

To get started, you will create an authentication context with JavaScript and define the authentication UI with XML templates.

Host this JavaScript file on your server.

Remember only to write one authentication context, because the same one can be used for both devices.

Lastly, after writing your context and XML, send us the TV provider onboarding data.

This data includes the name to be displayed in our UI for the TV provider; the identifier for the TV provider, which will be used in our systems to identify the TV provider uniquely amongst others; and the authentication URL, the URL we need to ping on the TV provider server to access and download your authentication context to device.

Send us the artwork to be displayed for the TV provider's brand in the App Store UI.

For more details on the artwork specs, see our documentation.

Send us a supported channel list.

This is an optional piece of onboarding data.

Here, a channel references TV provider-supported apps.

In the Apple TV distribution program, one app will be automatically installed after the authentication flow; that's the main app.

If you have any additional apps that use your TV provider credentials, use this list to show those other TV provider-supported apps to the customer.

To begin developing the authentication context, handle the callbacks for requests made by the VideoSubscriberAccount framework to the authentication context.

The first is onLaunch.

This indicates what should happen after a TV provider is selected from the VideoSubscriberAccount list.

After selecting a TV provider, a pending screen appears until the next callback.

onShowUserInterface.

After launch, then you must handle the callback to show the authentication template for credential entry.

Next is onRequest.

After credentials are entered, you take those credentials and send them directly to your identity provider server.

These credentials are not stored on device.

An authentication response is sent back from the server to the authentication context to the VideoSubscriberAccount framework to establish system-level authentication.

App-level authentication requests will only be sent for processing if this system-level authentication is good.

To debug your application, enable Developer Mode on your iOS and tvOS devices to add and test your TV provider before code is live.

To specifically debug your authentication context, use Safari Web Inspector.

Make sure to enable Web Inspector on device so your macOS device can debug the JavaScript.

In summary, the authentication context is a JavaScript-based web service that facilitates communication between the identity provider server for a TV provider and the VideoSubscriberAccount framework.

Thank you.