:orphan: 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``. .. _oauth2client: https://github.com/google/oauth2client Reasons for deprecation ----------------------- #. Lack of ownership: ``oauth2client`` has lacked a definitive owner since around 2013. #. 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. #. 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). #. 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. .. _httplib2: https://github.com/httplib2/httplib2 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: #. Clear ownership: google-auth is owned by the teams that maintain the `Cloud Client Libraries`_, `gRPC`_, and the `Code Samples for Google Cloud Platform`_. #. 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. #. 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. #. 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: #. 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. .. _Cloud Client Libraries: https://github.com/googlecloudplatform/google-cloud-python .. _gRPC: http://www.grpc.io/ .. _Code Samples for Google Cloud Platform: https://github.com/googlecloudplatform/python-docs-samples .. _urllib3: https://urllib3.readthedocs.io .. _requests: http://python-requests.org .. _legacy support for httplib2: https://pypi.python.org/pypi/google-auth-httplib2 .. _oauthlib: https://oauthlib.readthedocs.io .. _google-auth-oauthlib: http://google-auth-oauthlib.readthedocs.io/ .. _discussion thread: https://github.com/GoogleCloudPlatform/google-auth-library-python/issues/33 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`_. .. _google-api-python-client: https://github.com/google/google-api-python-client .. _file a bug: https://github.com/GoogleCloudPlatform/google-auth-library-python/issues