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.
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
OAuth2 implementation
The following platforms can be included on your form:
- PBS Account
- Apple
This section shows you how to implement each platform on your sign-in page.
Create custom PBS Account sign-in link
Use the following code to display a custom PBS Account Sign In / Link page:
Custom sign in links - PBS Account
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
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.
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>
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.