| :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 |