.. _docs-auth:

Authentication and Authorization
================================

The Python client library can be used to work with either public or
private feeds, however the Documents List Data API only provides
access to private feeds. That means your client application must
send authenticated requests to the API. This can be done via
`ClientLogin <#AuthClientLogin>`_ username/password authentication,
`AuthSub <#AuthAuthSub>`_, or `OAuth <#AuthOAuth>`_.

Please see the
`Google Data APIs Authentication Overview </apis/gdata/auth.html>`_
for more information on AuthSub, OAuth, and ClientLogin.

**Tip**: The API supports SSL (HTTPS). If you're using
AuthSub/OAuth, make sure to specify a scope of
``http<strong>s</strong>://docs.google.com/feeds/`` in order to
request feeds over SSL. You can force all API requests to be over
HTTPS by setting the ``DocsClient``'s ssl property:
``client.ssl = True``.

AuthSub for web applications
----------------------------

`AuthSub Authentication for Web Applications </apis/accounts/docs/AuthSub.html>`_
should be used by client applications which need to authenticate
their users to Google or Google Apps accounts. The operator does
not need access to the username and password for the Google Docs
user - only an AuthSub token is required.

*View instructions for incorporating AuthSub into your web application*

Request a single-use token
~~~~~~~~~~~~~~~~~~~~~~~~~~

When the user first visits your application, they need to
authenticate. Typically, developers print some text and a link
directing the user to the AuthSub approval page to authenticate the
user and request access to their documents. The Google Data Python
client library provides a function, ``generate_auth_sub_url()`` to
generate this URL. The code below sets up a link to the
`AuthSubRequest </apis/accounts/docs/AuthSub.html#AuthSubRequest>`_
page.

::

    import gdata.gauth
    
    def GetAuthSubUrl():
      next = 'http://www.example.com/myapp.py'
      scopes = ['http://docs.google.com/feeds/', 'https://docs.google.com/feeds/']
      secure = False  # set secure=True to request a secure AuthSub token
      session = True
      return gdata.gauth.generate_auth_sub_url(next, scopes, secure=secure, session=session)
    
    print '<a href="%s">Login to your Google account</a>' % GetAuthSubUrl()

If you want to authenticate users on a Google Apps hosted domain,
pass in the domain name to ``generate_auth_sub_url()``:

::

    def GetAuthSubUrl():
      domain = 'example.com'
      next = 'http://www.example.com/myapp.py'
      scopes = ['http://docs.google.com/feeds/', 'https://docs.google.com/feeds/']
      secure = False  # set secure=True to request a secure AuthSub token
      session = True
      return gdata.gauth.generate_auth_sub_url(next, scopes, secure=secure, session=session, domain=domain)

The ``generate_auth_sub_url()`` method takes several parameters
(corresponding to the query parameters used by the
`AuthSubRequest </apis/accounts/docs/AuthSub.html#AuthSubRequest>`_
handler):


-  the **next** URL — URL that Google will redirect to after the
   user logs into their account and grants access;
   ``http://www.example.com/myapp.py`` in the example above
-  the **scope** — ``http://docs.google.com/feeds/`` (and
   ``https://docs.google.com/feeds/``) in the example above. Note,
   both are used as a convenience to your app. Later, if you decide to
   initiate API requests over SSL, your existing AuthSub tokens will
   be valid.
-  **secure**, a boolean to indicate whether the token will be used
   in
   `secure and registered mode </apis/accounts/docs/AuthSub.html#signingrequests>`_
   or not; ``False`` in the example above
-  **session**, a second boolean to indicate whether the single-use
   token will later be exchanged for a session token or not; ``True``
   in the example above

Upgrading to a session token
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

See
`Using AuthSub with the Google Data API Client Libraries </apis/gdata/authsub.html#request-session-token>`_.

Retrieving information about a session token
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

See
`Using AuthSub with the Google Data API Client Libraries </apis/gdata/authsub.html#TokenInfo>`_.

Revoking a session token
~~~~~~~~~~~~~~~~~~~~~~~~

See
`Using AuthSub with the Google Data API Client Libraries </apis/gdata/authsub.html#revoke-token>`_.

**Tip**: Once your application has successfully acquired a long
lived sessions token, store that token in your database to recall
for later use. There's no need to send the user back to AuthSub on
every run of your application. Use
``client.auth_token = gdata.gauth.AuthSubToken(TOKEN_STR)`` to set
an existing token on the client.

OAuth for web or installed/mobile applications
----------------------------------------------

`OAuth </apis/accounts/docs/OAuth.html>`_ can be used as an
alternative to AuthSub, and is intended for web applications. OAuth
is similar to using the
`secure and registered mode </apis/accounts/docs/AuthSub.html#signingrequests>`_
of AuthSub in that all data requests must be digitally signed and
you must register your domain.

*View instructions for incorporating OAuth into your installed application*

Fetching a request token
~~~~~~~~~~~~~~~~~~~~~~~~

See
`Using OAuth with the Google Data API Client Libraries </apis/gdata/oauth.html#OAuthRequestToken>`_.

Authorizing a request token
~~~~~~~~~~~~~~~~~~~~~~~~~~~

See
`Using OAuth with the Google Data API Client Libraries </apis/gdata/oauth.html#OAuthAuthorizeToken>`_.

Upgrading to an access token
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

See
`Using OAuth with the Google Data API Client Libraries </apis/gdata/oauth.html#OAuthAuthorizeToken>`_.

**Tip**: Once your application has successfully acquired an OAuth
access token, store that token in your database to recall for later
use. There's no need to send the user back through OAuth on every
run of your application. Use
``client.auth_token = gdata.oauth.OAuthToken(TOKEN_STR, TOKEN_SECRET)``
to set an existing token on the client.

ClientLogin for installed/mobile applications
---------------------------------------------

`ClientLogin </apis/accounts/docs/AuthForInstalledApps.html>`_
should be used by installed or mobile applications which need to
authenticate their users to Google accounts. On first run, your
application prompts the user for their username/password. On
subsequent requests, an authentication token is referenced.

*View instructions for incorporating ClientLogin into your installed application*

To use
`ClientLogin </apis/accounts/docs/AuthForInstalledApps.html>`_,
invoke the
```ClientLogin()`` <http://gdata-python-client.googlecode.com/hg/pydocs/gdata.client.html#GDClient-ClientLogin>`_
method of ``DocsClient`` object, which is inherited from
```GDClient`` <http://gdata-python-client.googlecode.com/hg/pydocs/gdata.client.html#GDClient>`_.
Specify the email address and password of the user on whose behalf
your client is making requests. For example:

::

    client = gdata.docs.client.DocsClient(source='yourCo-yourAppName-v1')
    client.ClientLogin('user@gmail.com', 'pa$$word', client.source);

**Tip**: Once your application has successfully authenticated the
user for the first time, store the auth token in your database to
recall for later use. There's no need to prompt the user for
his/her password on every run of your application. See
`Recalling an auth token </apis/gdata/clientlogin.html#RecallAuthToken>`_
for more information.

For more information on using ClientLogin in your Python
applications, see the
`Using ClientLogin with the Google Data API Client Libraries </apis/gdata/clientlogin.html>`_.

`Back to top <#top>`_