External transport discussion

[theacodes]

Continuing from #1, we need to figure out the story for use case (2):

It needs to allow users to attach credentials to an HTTP object of their choosing.

The usage of this is external-only. This is the means by which users will make authenticated requests. We want to initially support urllib3, but we should be aware of anything that will cause issues with a requests implementation.

How oauth2client does this

oauth2client only supports httplib2. The way that it accomplishes this is by monkeypatching an existing httplib2.Http object's request method.

1. The user must construct the http object themselves (this gives them the opportunity to configure settings such as SSL and proxies).
2. oauth2client modifies the object in place and returns it. The original request method is only available as a closure (via http.request.func_closure[0].cell_contents, which is insanity).

How oauth2client's transport refactor did it.

In the transport refactor, I modified this behavior slightly. Instead of monkeypatching, it wrapped the http object using an AuthedHttp wrapper class that has a common interface with httplib2.Http.

1. The user still must construct the http object themselves.
2. oauth2client returns a AuthedHttp wrapper instance that uses the original http object under the covers. The original http object is not modified in any way.

What we could do

We could largely adopt the second method without much heartache, as long a we're still okay with the wrapper pattern:

import google.auth
from google.auth.transport.urllib3 import AuthedHttp
import urllib3

http = urllib3.PoolManager()
credentials, _ = google.auth.default()
authed_http = AuthedHttp(credentials, http)

Similarly with requests:

import google.auth
from google.auth.transport.requests import AuthedSession
import urllib3

session = requests.Session()
credentials, _ = google.auth.default()
authed_session = AuthedSession(credentials, session)

We could also have these items construct their own underlying object using sane defaults if none is specified:

# Creates a PoolManager behind the scenes
authed_http = AuthedHttp(credentials)
# Creates a Session behind the scenes.
authed_session = AuthedSession(credentials)

The only concern I have about this is the long import path (google.auth.transport.urllib3). I can't think of a good, clean way to do something like oauth2client's authorize and I'm not sure that I want to.

Thoughts? Concerns? Alternatives?

[dhermes]

I like what you've constructed above.

[theacodes]

I like what you've constructed above.

Yay!

Any thoughts on this:

The only concern I have about this is the long import path (google.auth.transport.urllib3). I can't think of a good, clean way to do something like oauth2client's authorize and I'm not sure that I want to.

[dhermes]

Long import paths don't bother me. You can make transport the thing that people import.

[theacodes]

You can make transport the thing that people import.

How so? Import all the submodules?

[dhermes]

Yes.

[jplanza]

@jonparrott Is this the expected pattern for people to follow when they need to attach a custom http object to a google.auth.default() request? I'm trying to sort out how to run google-auth through a proxy; using a proxy is a pretty common use case, so if this is the right way to do it, some documentation pointers would be very helpful here:

https://google-auth.readthedocs.io/en/latest/user-guide.html

[theacodes]

If you're using a proxy and the requests transport you can just set the standard HTTP_PROXY and HTTPS_PROXY environment variables.