1:orphan:
2
3oauth2client deprecation
4========================
5
6This page is intended for existing users of the `oauth2client`_ who want to
7understand the reasons for its deprecation and how this library relates to
8``oauth2client``.
9
10.. _oauth2client: https://github.com/google/oauth2client
11
12Reasons for deprecation
13-----------------------
14
15#. Lack of ownership: ``oauth2client`` has lacked a definitive owner since
16   around 2013.
17#. Fragile and ad-hoc design: ``oauth2client`` is the result of several years
18   of ad-hoc additions and organic, uncontrolled growth. This has led to a
19   library that lacks overall design and cohesion. The convoluted class
20   hierarchy is a symptom of this.
21#. Lack of a secure, thread-safe, and modern transport: ``oauth2client`` is
22   inextricably dependent on `httplib2`_. ``httplib2`` is largely unmaintained
23   (although recently there are a small group of volunteers attempting to
24   maintain it).
25#. Lack of clear purpose and goals: The library is named "oauth2client" but is
26   actually a pretty poor OAuth 2.0 client and does a lot of things that have
27   nothing to do with OAuth and its related RFCs.
28
29.. _httplib2: https://github.com/httplib2/httplib2
30
31We originally planned to address these issues within ``oauth2client``, however,
32we determined that the number of breaking changes needed would be absolutely
33untenable for downstream users. It would essentially involve our users having
34to rewrite significant portions of their code if they needed to upgrade (either
35directly or indirectly through a dependency). Instead, we've chosen to create a
36new replacement library that can live side-by-side with ``oauth2client`` and
37allow users to migrate gradually. We believe that this was the least painful
38option.
39
40Replacement
41-----------
42
43The long-term replacement for ``oauth2client`` is this library,
44``google-auth``. This library addresses the major issues with oauthclient:
45
46#. Clear ownership: google-auth is owned by the teams that maintain the
47   `Cloud Client Libraries`_, `gRPC`_, and the
48   `Code Samples for Google Cloud Platform`_.
49#. Thought-out design: using the lessons learned from ``oauth2client``, we have
50   designed a better module and class hierarchy. The ``v1.0.0`` release of this
51   library should provide long-term API stability.
52#. Modern, secure, and extensible transports: ``google-auth`` supports
53   `urllib3`_, `requests`_, `gRPC`_, and has `legacy support for httplib2`_ to
54   help clients migration. It is transport agnostic and has explicit support
55   for adding new transports.
56#. Clear purpose and goals: ``google-auth`` is explicitly focused on
57   Google-specific authentication, especially the server-to-server (service
58   account) use case.
59
60Because we reduced the scope of the library, there are several features in
61``oauth2client`` we intentionally are not supporting in the ``v1.0.0`` release
62of ``google-auth``. This does not mean we are not interested in supporting
63these features, we just didn't feel they should be part of the initial API.
64As downstream users ask for these features we will determine the best way to
65serve those use cases without allowing the library to become a dumping ground.
66
67The unsupported features are:
68
69#. Support for obtaining user credentials. While this library has support for
70   using user credentials, there are no provisions in the core library for
71   doing the three-party OAuth 2.0 flow to obtain authorization from a user.
72   Instead, we are opting to provide a separate package that does integration
73   with `oauthlib`_, `google-auth-oauthlib`_. When that library has a stable
74   API, we will consider its inclusion into the core library.
75#. Support for storing credentials. The only credentials type that needs to
76   be stored are user credentials. We have a `discussion thread`_ on what level
77   of support we should do. It's very likely we'll choose to provide an
78   abstract interface for this and leave it up to application to provide
79   storage implementation specific to their use case. It's also very likely
80   that we will also incubate this functionality in the
81   `google-auth-oauthlib`_ library before including it in the core library.
82
83.. _Cloud Client Libraries: https://github.com/googlecloudplatform/google-cloud-python
84.. _gRPC: http://www.grpc.io/
85.. _Code Samples for Google Cloud Platform: https://github.com/googlecloudplatform/python-docs-samples
86.. _urllib3: https://urllib3.readthedocs.io
87.. _requests: http://python-requests.org
88.. _legacy support for httplib2: https://pypi.python.org/pypi/google-auth-httplib2
89.. _oauthlib: https://oauthlib.readthedocs.io
90.. _google-auth-oauthlib: http://google-auth-oauthlib.readthedocs.io/
91.. _discussion thread: https://github.com/GoogleCloudPlatform/google-auth-library-python/issues/33
92
93
94Post-deprecation support
95------------------------
96
97While ``oauth2client`` will not be implementing or accepting any new features,
98the ``google-auth`` team will continue to accept bug reports and fix critical
99bugs. We will make patch releases as necessary. We have no plans to remove the
100library from GitHub or PyPI. Also, we have made sure that the
101`google-api-python-client`_ library supports oauth2client and google-auth and
102will continue to do so indefinitely.
103
104It is important to note that we will not be adding any features, even if an
105external user goes through the trouble of sending a pull request. This policy
106is in place because without it we will perpetuate the circumstances that led
107to ``oauth2client`` being in the semi-unmaintained state it was in previously.
108
109Some old documentation and examples may use ``oauth2client`` instead of
110``google-auth``. We are working to update all of these but it does take a
111significant amount of time. Since we are still iterating on user auth, some
112samples that use user auth will not be updated until we have settled on a final
113interface. If you find any samples you feel should be updated, please
114`file a bug`_.
115
116.. _google-api-python-client: https://github.com/google/google-api-python-client
117.. _file a bug: https://github.com/GoogleCloudPlatform/google-auth-library-python/issues
118