oauth2client deprecation

This page is intended for existing users of the oauth2client who want to understand the reasons for its deprecation and how this library relates to oauth2client.

Reasons for deprecation

  1. Lack of ownership: oauth2client has lacked a definitive owner since around 2013.

  2. Fragile and ad-hoc design: oauth2client is the result of several years of ad-hoc additions and organic, uncontrolled growth. This has led to a library that lacks overall design and cohesion. The convoluted class hierarchy is a symptom of this.

  3. Lack of a secure, thread-safe, and modern transport: oauth2client is inextricably dependent on httplib2. httplib2 is largely unmaintained (although recently there are a small group of volunteers attempting to maintain it).

  4. Lack of clear purpose and goals: The library is named “oauth2client” but is actually a pretty poor OAuth 2.0 client and does a lot of things that have nothing to do with OAuth and its related RFCs.

We originally planned to address these issues within oauth2client, however, we determined that the number of breaking changes needed would be absolutely untenable for downstream users. It would essentially involve our users having to rewrite significant portions of their code if they needed to upgrade (either directly or indirectly through a dependency). Instead, we’ve chosen to create a new replacement library that can live side-by-side with oauth2client and allow users to migrate gradually. We believe that this was the least painful option.

Replacement

The long-term replacement for oauth2client is this library, google-auth. This library addresses the major issues with oauthclient:

  1. Clear ownership: google-auth is owned by the teams that maintain the Cloud Client Libraries, gRPC, and the Code Samples for Google Cloud Platform.

  2. Thought-out design: using the lessons learned from oauth2client, we have designed a better module and class hierarchy. The v1.0.0 release of this library should provide long-term API stability.

  3. Modern, secure, and extensible transports: google-auth supports urllib3, requests, gRPC, and has legacy support for httplib2 to help clients migration. It is transport agnostic and has explicit support for adding new transports.

  4. Clear purpose and goals: google-auth is explicitly focused on Google-specific authentication, especially the server-to-server (service account) use case.

Because we reduced the scope of the library, there are several features in oauth2client we intentionally are not supporting in the v1.0.0 release of google-auth. This does not mean we are not interested in supporting these features, we just didn’t feel they should be part of the initial API. As downstream users ask for these features we will determine the best way to serve those use cases without allowing the library to become a dumping ground.

The unsupported features are:

  1. Support for obtaining user credentials. While this library has support for using user credentials, there are no provisions in the core library for doing the three-party OAuth 2.0 flow to obtain authorization from a user. Instead, we are opting to provide a separate package that does integration with oauthlib, google-auth-oauthlib. When that library has a stable API, we will consider its inclusion into the core library.

  2. Support for storing credentials. The only credentials type that needs to be stored are user credentials. We have a discussion thread on what level of support we should do. It’s very likely we’ll choose to provide an abstract interface for this and leave it up to application to provide storage implementation specific to their use case. It’s also very likely that we will also incubate this functionality in the google-auth-oauthlib library before including it in the core library.

Post-deprecation support

While oauth2client will not be implementing or accepting any new features, the google-auth team will continue to accept bug reports and fix critical bugs. We will make patch releases as necessary. We have no plans to remove the library from GitHub or PyPI. Also, we have made sure that the google-api-python-client library supports oauth2client and google-auth and will continue to do so indefinitely.

It is important to note that we will not be adding any features, even if an external user goes through the trouble of sending a pull request. This policy is in place because without it we will perpetuate the circumstances that led to oauth2client being in the semi-unmaintained state it was in previously.

Some old documentation and examples may use oauth2client instead of google-auth. We are working to update all of these but it does take a significant amount of time. Since we are still iterating on user auth, some samples that use user auth will not be updated until we have settled on a final interface. If you find any samples you feel should be updated, please file a bug.