Move from ClientLogin to OAuth 2.0

YouTube APIs use OAuth 2.0 to authorize user requests. We are frequently asked whether we will add support for ClientLogin authentication or something similar in YouTube APIs going forward. However, we officially deprecated ClientLogin as of April 20, 2012, and there are no plans to add such a mechanism.

There are numerous reasons why we believe supporting various flows of OAuth 2.0 authorization is better for YouTube users than ClientLogin. These flows support use cases for desktop applications, web-only applications, native mobile applications, and even applications that run on devices like televisions that don’t have sophisticated input mechanisms, something which is difficult to do using ClientLogin. Also, we’ve found that ClientLogin causes more headaches post-launch for many developers, some of which we describe in our blog post, ClientLogin #FAIL.

Using OAuth 2.0 for server-side, standalone scripts

Many developers use ClientLogin to authorize command-line scripts that run on servers without a browser. With OAuth 2.0, there’s almost always going to be a browser involved – the exception being when you’re working on an Android application that uses Google Play Services to fetch tokens via GoogleAuthUtil.

In a web-only flow, a website that wants to make authenticated API calls on behalf of a user must redirect the user to a google.com authentication page that explains what the application is trying to access. The web application then receives a token, which it uses to make API calls. The user can then revoke the application’s access at any time using the connected apps and sites page.

Our Python code samples demonstrate how command-line scripts can launch a browser and make API calls from a terminal window, create a local server to listen for the code after the authorization redirect, and automatically save a token for future API calls. A video of this in action is below:

The token used is an ASCII string. If it is an offline token, it is portable. Using the retrieved token, you will be able to run the script on your desktop, then copy and use the code on a remote server without a GUI, provided that code instantiates an OAuth 2.0 client with the same client ID and secret. In addition to Python, the Google API client libraries for other programming languages also provide helper methods for managing tokens, which can be shared between clients and even used in lower-level HTTP libraries directly in a client header or as a URL parameter.

Some examples of server-side scripts that use offline tokens:

• A daemon that monitors a directory for new videos to automatically upload to YouTube
• A cron job that that updates playlists daily with new content
• A script that monitors video data via the YouTube Analytics API and notifies channel managers when certain events take place, such as aggregate watch time exceeding a limit. Note that in this case, OAuth 2.0 is the only supported authorization method because the Analytics API does not support ClientLogin.

The section on long-lived access tokens provides more detail about how to generate the offline tokens that can be used for server side processes.

Client ID and client secret best practices

Any code that shares the same client ID and secret pair can use the same access tokens. It’s best to restrict access to client ID and client secrets to code that runs on machines and devices within your organization.

Do not include your client ID and client secret as part of your native mobile applications code. All developers doing OAuth 2.0 authentication from a mobile device should make use of the "Installed application" client ID, which asks for additional information to verify that the request is coming only from an application released by your team.

On Android devices, instead of using a client ID and client secret, your application is identified using a combination of the package name and a signing certificate hash. On iOS devices, the bundle ID and the app store ID are used. The official documentation on retrieving this information can be found on the Google API Console help page.

Service Accounts do not work with the YouTube API

Service accounts do not work for YouTube Data API calls because service accounts require an associated YouTube channel, and you cannot associate new or existing channels with service accounts. If you use a service account to call the YouTube Data API, the API server returns an error with the error type set to unauthorized and the reason set to youtubeSignupRequired.

Offline/long-lived access to the YouTube API

OAuth 2.0 has short-lived tokens and long-lived tokens. For one-off operations, short-lived access tokens are the best option. These tokens expire shortly after they are granted. For long running jobs, you may want to look into acquiring a refresh token, which is used to fetch short-lived access tokens.

To ensure that your application receives a long-lived refresh token and not a short-lived access token, use the "Installed Application" flow when creating a client ID, and select Other for the "Installed application type" value:

It's recommended that you use the "Installed application" flow for this use case. If you need long-lived access to the YouTube API in a web application, you can retrieve one by setting the access_type parameter to offline and the approval_prompt parameter to force in the initial authorization request or your client configuration. Some client libraries will manage fetching and refreshing access tokens. If you are interested in writing your own custom authorization code, we published a blog post on the Google Code blog that you can use as the basis for your code.

Using OAuth 2.0 with phones, tablets and other devices

When writing Android applications, developers can take advantage of Google Play services to handle the authorization details. Google Play services offers a standard authorization flow for all Google APIs, including APIs for the YouTube platform. This approach will provide a far superior user experience for users of your Android application than a custom authentication using ClientLogin.

On iOS devices, Google provides two options:

• the Google+ Platform for iOS, which integrates sign-in for Google products and also enables social features
• the gtm-oauth2 toolkit, which provides an authorization UIWebView and manages tokens

For devices that are meant to act as "second screen" devices or devices such as televisions without easy-to-use input mechanisms, OAuth 2.0 for Devices is the preferred approach. OAuth 2.0 for Devices works by presenting a unique code for a user when an authorization request is required. At this point, users are asked to browse to http://google.com/device on another device, such as a laptop or a phone, and enter in the unique code. The application presents a screen that looks something like this:

While the user is entering the code on another device, the application periodically polls to see if the code has been entered. Once it has, it retrieves a token for making API calls. To see this in action, check out the demo, which can be run on any web-enabled device. The API itself is platform-agnostic, making it useful for devices that don’t have web rendering capabilities. We’ve posted sample code in Python for the demo to be used as a reference.

Summary

OAuth 2.0 authorization provides flexibility for developers that require YouTube authorization. Developers familiar with ClientLogin may find that setting up their applications to use OAuth 2.0 requires slightly more work to get started, but once ported, OAuth 2.0 applications offer more flexibility, security and usability across multiple platforms for end users.

If you have any more questions about OAuth 2.0 or any of the examples in this article, please feel feel to ask with the youtube-api tag on StackOverflow.