tv-auth

Overview

This repository contains our tv-auth service which allows users to authenticate against a variety of TV providers. The service takes a user's username and password for a given provider, logs them in on the provider's site, and then parses the provider for the user's subscription type. This whole process is made possible through the use of Puppeteer. The tv-auth service interacts with our DB via the API to store user login attempts as well as the subscriptions parsed. This data is then used by room-server to determine if the users has access to the content being streamed in the room.

Service architecture

The tv-auth service is a websocket server that receives and sends signals to individual clients in order to authenticate them and provide information around whether or not their authentication was successful. The service's client implementation can be found in common/tv-auth. A typical TV auth session between a client and this service looks something like:

Multiple instances of the tv-auth service are deployed to our cluster. Each service instance can be thought of as its own higly provisioned web browser where each authentication session is performed in an isolated incognito tab. Each tv-auth service deployment runs behind different network configurations. There are deployments that run directly from GCP's network, on Nord's VPN, and through different web proxies. These different networks configurations are neccesary as some TV providers will block traffic to their site if they detect it originating from a suspicious source, like a cloud network or other bot-like sources.

TV provider authentication interface

The list of TV providers supported can be seen by listing the src/auth directory of this repo. Each TV provider authentication file implements an interface that allows the provider to be consumed from src/service.ts. The interface is comprised of the following methods:

auth(page: Page, logger: winston.Logger, signal: AuthSignal) => Promise<{
    result: AuthResult;
}>

The auth method is used by the client to send the user's credentials for a select provider.

portalVerification(page: Page, logger: winston.Logger) => Promise<{
    result: PortalResult;
}>

The portalVerification method handles cases where the provider uses two-factor authentication or reCAPTCHA like techniques to identify users.

parseSubscription(page: Page, logger: winston.Logger, countryIsoCode?: string) => Promise<
    SubscriptionParserResult
>;

The parseSubscription methods is used to crawl the provider's site and extract subscripton information specific to the user which will determine whether or not the user has access to given TV content.

parseLocation(page: Page, logger: winston.Logger) => Promise<string>;

The parseLocation methods is used to extract the user's account location from the provider's site. This will be used during the access verification process to determine regional access to TV content.

Telemetry

The main source of insight in to the results of authentication sessions comes from the #tv-auth-bot channel in Slack. The channel is alerted every time an authentication is attempted. An example of a successful authentication alert looks like:

The alert contains a variety of information about the authentication session as seen above. The tv-auth service creates recordings for each auth session as well as a trail of "breadcrumbs" to help debug the flow if something goes wrong. Here is the above example's recording link and breadcrumbs link. The logs associated with the auth session are also linked to here.

Related moderator tool

There is a TV authentication moderation tool that we use in order to "whitelist" users who have trouble connecting to their TV provider. A lot of times either the provider or our service may not handle every authentcation attempt correctly while it is likely the case that the user does indeed have access. In these cases we use the moderator tool to manually grant access to the user. The tool can be found here.

Development

Clone this repo with submodules: git clone --recurse-submodules [email protected]:playback-sports/tv-auth.git

To install missing dependencies run: yarn install

To build the tv-auth service run: yarn build.

If building on an ARM-based chip, you may need to install Rosetta: softwareupdate --install-rosetta

To start the tv-auth service locally, run: yarn start. In order to run locally you will need to create a .env file to set the appropriate environment values to run the service locally. An example of an .env file can be found here in 1password. You will also need to create a .npm-token file in this repo in order to authenticate to our NPM repository.

To build a docker image run: make docker-build.

To then push the docker image to GCR run make docker-push. Note the image tag pushed to GCR is defined by the GIT_BRANCH environment variable in the Makefile