Adding auth doc explaining all the ways to mint credentials.

[dhermes]

Fixes #633.

Follow along changes in:
www.googledrive.com/host/0B8el7dRo8mVOekRaUm1wWnFLeUE

/cc @jgeewax

[coveralls]

Changes Unknown when pulling 06918f1 on dhermes:add-gcloud-auth-docs into * on GoogleCloudPlatform:master*.

[tseaver]

LGTM

[dhermes]

@tseaver Thanks for the review, I'll hold off on merging until @jgeewax takes a look.

[coveralls]

Changes Unknown when pulling f6bba7b on dhermes:add-gcloud-auth-docs into * on GoogleCloudPlatform:master*.

[dhermes]

@jgeewax PTAL

[jgeewax]

OK, I was just attempting to explain to someone how this might work, and realized that, when coming from a totally fresh spot, it was much less helpful than I'd hoped. It feels a bit like "here is a page of formulas organized by complexity of the code you have to write" rather than "here's the tasks you might want to do and how you get them done".

---

Are there any objections to making this more "use-case" oriented? The way I'd picture it is:

Ways to authenticate

Use the 'default credentials'

If you're running in any of the following environments, we can detect both your credentials and the project ID (and dataset ID for Cloud Datastore) automatically:

• GAE
• ...

This means that in those environments, the following will 'just work':

from gcloud import datastore
datastore.get(...)

Specify a particular set of credentials

If you want to be explicit about the credentials, do that by using [insert detail here]:

# Note: I still think this is too long...

from gcloud import credentials
from gcloud import datastore

creds = credentials.get_for_service_account_json('/path/to/key.json')
datastore.set_default_connection(datastore.Connection(credentials=creds))

...

[tmatsuo]

JFYI, I wrote a doc about usable auth recently:
https://cloud.google.com/pubsub/configure

I also feel that we should advertise the simplest case (and most importantly, you can have the portable code which runs everywhere) first.