Skip to content

Commit

Permalink
Merge pull request psf#1009 from Lukasa/master
Browse files Browse the repository at this point in the history
Auth documentation.
Kenneth Reitz committed Dec 17, 2012
2 parents d0f2382 + a7c5d5e commit 4701243
Showing 3 changed files with 85 additions and 74 deletions.
1 change: 1 addition & 0 deletions docs/index.rst
Original file line number Diff line number Diff line change
@@ -90,6 +90,7 @@ instructions for getting the most out of Requests.
user/install
user/quickstart
user/advanced
user/authentication


Community Guide
84 changes: 84 additions & 0 deletions docs/user/authentication.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
.. _authentication:

Authentication
==============

This document discusses using various kinds of authentication with Requests.

Many web services require authentication, and there are many different types.
Below, we outline various forms of authentication available in Requests, from
the simple to the complex.


Basic Authentication
--------------------

Many web services that require authentication accept HTTP Basic Auth. This is
the simplest kind, and Requests supports it straight out of the box.

Making requests with HTTP Basic Auth is very simple::

>>> from requests.auth import HTTPBasicAuth
>>> requests.get('https://api.github.com/user', auth=HTTPBasicAuth('user', 'pass'))
<Response [200]>

In fact, HTTP Basic Auth is so common that Requests provides a handy shorthand
for using it::

>>> requests.get('https://api.github.com/user', auth=('user', 'pass'))
<Response [200]>

Providing the credentials in a tuple like this is exactly the same as the
``HTTPBasicAuth`` example above.


Digest Authentication
---------------------

Another very popular form of HTTP Authentication is Digest Authentication,
and Requests supports this out of the box as well::

>>> from requests.auth import HTTPDigestAuth
>>> url = 'http://httpbin.org/digest-auth/auth/user/pass'
>>> requests.get(url, auth=HTTPDigestAuth('user', 'pass'))
<Response [200]>


Other Authentication
--------------------

Requests is designed to allow other forms of authentication to be easily and
quickly plugged in. Members of the open-source community frequently write
authentication handlers for more complicated or less commonly-used forms of
authentication. Some of the best have been brought together under the
`Requests organization`_, including:

- OAuth_
- Kerberos_
- NTLM_

If you want to use any of these forms of authentication, go straight to their
Github page and follow the instructions.


New Forms of Authentication
---------------------------

If you can't find a good implementation of the form of authentication you
want, you can implement it yourself. Requests makes it easy to add your own
forms of authentication.

To do so, subclass :class:`requests.auth.AuthBase` and implement the
``__call__()`` method. When an authentication handler is attached to a request,
it is called during request setup. The ``__call__`` method must therefore do
whatever is required to make the authentication work. Some forms of
authentication will additionally add hooks to provide further functionality.

Examples can be found under the `Requests organization`_ and in the
``auth.py`` file.

.. _OAuth: https://github.com/requests/requests-oauthlib
.. _Kerberos: https://github.com/requests/requests-kerberos
.. _NTLM: https://github.com/requests/requests-ntlm
.. _Requests organization: https://github.com/requests

74 changes: 0 additions & 74 deletions docs/user/quickstart.rst
Original file line number Diff line number Diff line change
@@ -337,80 +337,6 @@ parameter::
'{"cookies": {"cookies_are": "working"}}'


Basic Authentication
--------------------

Many web services require authentication. There are many different types of
authentication, but the most common is HTTP Basic Auth.

Making requests with Basic Auth is extremely simple::

>>> from requests.auth import HTTPBasicAuth
>>> requests.get('https://api.github.com/user', auth=HTTPBasicAuth('user', 'pass'))
<Response [200]>

Due to the prevalence of HTTP Basic Auth, requests provides a shorthand for
this authentication method::

>>> requests.get('https://api.github.com/user', auth=('user', 'pass'))
<Response [200]>

Providing the credentials as a tuple in this fashion is functionally equivalent
to the ``HTTPBasicAuth`` example above.


Digest Authentication
---------------------

Another popular form of web service protection is Digest Authentication::

>>> from requests.auth import HTTPDigestAuth
>>> url = 'http://httpbin.org/digest-auth/auth/user/pass'
>>> requests.get(url, auth=HTTPDigestAuth('user', 'pass'))
<Response [200]>


OAuth Authentication
--------------------

Requests features robust, built-in OAuth support!

OAuth takes many forms, so let's take a look at a few different forms::

import requests
from requests.auth import OAuth1

url = u'https://api.twitter.com/1/account/settings.json'

client_key = u'...'
client_secret = u'...'
resource_owner_key = u'...'
resource_owner_secret = u'...'


Query signing::

queryoauth = OAuth1(client_key, client_secret,
resource_owner_key, resource_owner_secret,
signature_type='query')
r = requests.get(url, auth=queryoauth)

Header signing::

headeroauth = OAuth1(client_key, client_secret,
resource_owner_key, resource_owner_secret,
signature_type='auth_header')
r = requests.get(url, auth=headeroauth)

Body signing::

bodyoauth = OAuth1(client_key, client_secret,
resource_owner_key, resource_owner_secret,
signature_type='body')

r = requests.post(url, auth=bodyoauth)


Redirection and History
-----------------------

0 comments on commit 4701243

Please sign in to comment.