diff options
Diffstat (limited to 'docs/oauth2client-deprecation.rst')
-rw-r--r-- | docs/oauth2client-deprecation.rst | 117 |
1 files changed, 117 insertions, 0 deletions
diff --git a/docs/oauth2client-deprecation.rst b/docs/oauth2client-deprecation.rst new file mode 100644 index 0000000..2802c3e --- /dev/null +++ b/docs/oauth2client-deprecation.rst @@ -0,0 +1,117 @@ +: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 |