diff --git a/docs/index.rst b/docs/index.rst index c43a8de4..0a77af16 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -90,6 +90,7 @@ instructions for getting the most out of Requests. user/install user/quickstart user/advanced + user/authentication Community Guide diff --git a/docs/user/authentication.rst b/docs/user/authentication.rst new file mode 100644 index 00000000..a3b5b56d --- /dev/null +++ b/docs/user/authentication.rst @@ -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')) + + +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')) + + +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')) + + + +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 + diff --git a/docs/user/quickstart.rst b/docs/user/quickstart.rst index c2f38b21..183c89d6 100644 --- a/docs/user/quickstart.rst +++ b/docs/user/quickstart.rst @@ -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')) - - -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')) - - -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')) - - - -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 -----------------------