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
Reasons for deprecation¶
Lack of ownership:
oauth2clienthas lacked a definitive owner since around 2013.
Fragile and ad-hoc design:
oauth2clientis 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.
Lack of a secure, thread-safe, and modern transport:
oauth2clientis inextricably dependent on httplib2.
httplib2is largely unmaintained (although recently there are a small group of volunteers attempting to maintain it).
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
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
allow users to migrate gradually. We believe that this was the least painful
The long-term replacement for
oauth2client is this library,
google-auth. This library addresses the major issues with oauthclient:
Thought-out design: using the lessons learned from
oauth2client, we have designed a better module and class hierarchy. The
v1.0.0release of this library should provide long-term API stability.
Modern, secure, and extensible transports:
google-authsupports 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.
Clear purpose and goals:
google-authis 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
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:
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.
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.
oauth2client will not be implementing or accepting any new features,
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
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.