Overview

PBS Account is PBS's OAuth 2 provider that also supports authentication via Google, Facebook, and Apple Oauth2 and can be used to implement login on station sites and for Passport. No profile information (e.g.: watch history, favorite shows and videos) is included.

Integration is based on OAuth 2. You can learn more about OAuth 2 here: 

Getting started

Begin by submitting a ticket to PBS support to request a client id, client secret, and scopes. 

  • Account - Access to user's PBS account. Necessary for logging users in.
  • Station (this is automatically assigned) - Station can create their own access to features on their station site or app that PBS account cannot access.
  • VPPA - Passport data.

Learn more about scopes

Provide a redirect URI in your request. This is the URL you want your users to land on once they have successfully logged in to your site. This link can be anything as long as it's a valid landing page. Examples: 

  • https://www.stationsite.org/login/
  • https://www.stationsite.org/callback/

Development and testing

  • Play around! Use the preconfigured Google OAuth 2 playground to view server requests and responses. Click here to access the playground
  • Install or develop an OAuth 2 client. Each platform offers several options. In a browser window, search for "OAuth 2 client" plus your platform. For instance, search for OAuth 2 client Wordpress. A list of options should display. 
  • Develop and test! Develop and test your implementation on the PBS QA site before going live. 

What you receive from PBS

After PBS processes your request, you will receive the following items:

  • Client id: Given to you by a PBS Account Admin

  • Client secret: Granted to you by a PBS Account Admin

  • Scope(s): This denotes what you can do with your access token; currently PBS requires account and station name (e.g. 'wnet') scopes. Learn more about scopes
  • Access token: This is actually dynamically provided via the OAuth 2 workflow (smile)

OAuth2 implementation

The following platforms can be included on your form:

  • PBS Account
  • Apple
  • Facebook
  • Google

This section shows you how to implement each platform on your sign-in page.

Click image to enlarge

Use the following code to display a custom PBS Account Sign In / Link page:

Code
https://account.pbs.org/oauth2/authorize/?scope={scope type}+{station name as specified in OAUTH2}&client_id={your client_id}&redirect_uri={redirect URI as specified in OAUTH2}&response_type=code


Example
https://account.pbs.org/oauth2/authorize/?scope=account+wpbs&client_id=TjsKCm3VA92wtsDymz1iDtFiCTpV83fBM&redirect_uri=http://www.wpbs.org/passport/passport.cfm&response_type=code

Social endpoints for custom sign-in

In order to begin the login process using a social provider, you need to redirect the user to the corresponding endpoint (e.g. through a button). Each of the endpoints below begin the social provider sign in process and, when finished, redirect the user to your website's landing page specified in your request ticket to PBS through the redirect_uri parameter.

Facebook

https://account.pbs.org/oauth2/social/login/facebook/?scope=<scopes_requested_in_PBS_ticket>&redirect_uri=<redirect_url_requested_in_PBS_ticket>&response_type=code&client_id=<client_id_received_from_PBS>

Google

https://account.pbs.org/oauth2/social/login/google-oauth2/?scope=<scopes_requested_in_PBS_ticket>&redirect_uri=<redirect_url_requested_in_PBS_ticket>&response_type=code&client_id=<client_id_received_from_PBS>

Apple

https://account.pbs.org/oauth2/social/login/apple/?scope=&redirect_uri=&response_type=code&client_id=>

Sample callback redirect request

After PBS Account authenticates a user, the user is redirected back to the redirect URI that you defined with an OAuth code in the URL.

http://www.wpbs.org/passport/passport.cfm?scope=account+wpbs&code=ahCqWWyH9ozeJqX8hZSbSaJhmO2kty#_=_

Retrieve OAuth token

The code received in the redirect request should be exchanged on the server side for an OAuth token:

The client MUST NOT use the authorization code more than once, as specified in  https://www.rfc-editor.org/rfc/rfc6749#section-4.1.2.


https://account.pbs.org/oauth2/token?client_id={your client_id}&client_secret={your client_secret}&redirect_uri=http://video.pbs.org/login/callback&code={redirect-auth-code}

Sample token exchange response

Example Token Exchange response:
{
  "access_token": "{access-token}",
  "token_type": "Bearer",
  "expires_in": {seconds-til-expiration},
  "refresh_token": "{refresh-token}",
  "scope": "account wgbh"
} 


The access token that is returned can be used to retrieve user information, including the user's PID, by calling the URL and passing in the access token as the Authorization header:

GET https://account.pbs.org/oauth2/user/info/ HTTP/1.1
Authorization: {access_token}


Sample user information response

If the token doesn't have the vppa scope, the "vppa" key will be null.

{
    "pid": "da9fb262-17e7-59d8-b89e-405378d55b26",
    "first_name": "FirstName",
    "last_name": "LastName",
    "email": "useremail@pbs.org",
    "zip_code": "20004",
    "analytics_id": null,
    "thumbnail_URL": "https://lh3.googleusercontent.com/-TYOtPg-zVH0/AAAAAAAAAAI/CCCCAAAAACM/Zmn8eQWemFs/photo.jpg?sz=50",
    "vppa": {
        "vppa_accepted": True,
        "vppa_last_updated": "2016-03-06 00:37:09.370124+00:00"
    }
}

What's happening in the back-end

Implementing VPPA

The Video Privacy Protection Act (VPPA) requires that Passport members who use PBS Video apps explicitly grant PBS permission to share the user’s personal data (viewing history, favorites, etc.) with the station. To be clear, the agreement is between the user and PBS, not the user and the station, which is why it is contained in an authentication flow managed by PBS.

Learn how to implement VPPA