From be364e13d381f96d24f6bfaa608254583f3ea1b6 Mon Sep 17 00:00:00 2001 From: Cory Benfield Date: Sat, 15 Dec 2012 13:16:27 +0000 Subject: [PATCH 1/3] Update auth documentation with org info. --- docs/user/quickstart.rst | 50 +++++++++++++--------------------------- 1 file changed, 16 insertions(+), 34 deletions(-) diff --git a/docs/user/quickstart.rst b/docs/user/quickstart.rst index beb05a5c..8d0cc9f3 100644 --- a/docs/user/quickstart.rst +++ b/docs/user/quickstart.rst @@ -370,45 +370,27 @@ Another popular form of web service protection is Digest Authentication:: -OAuth Authentication +Other Authentication -------------------- -Requests features robust, built-in OAuth support! +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 a single +`organization on Github`_, including: -OAuth takes many forms, so let's take a look at a few different forms:: +- OAuth_ +- Kerberos_ +- NTLM_ - import requests - from requests.auth import OAuth1 +If you want to use any of these forms of authentication, go straight to their +Github page and follow the instructions. If you can't find the one you want, +why not write one and submit it? - 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) +.. _OAuth: https://github.com/requests/requests-oauthlib +.. _Kerberos: https://github.com/requests/requests-kerberos +.. _NTLM: https://github.com/requests/requests-ntlm +.. _organisation on Github: https://github.com/requests Redirection and History From 54b77afbb57ac66a34cb5a24dd7db99b0d39d383 Mon Sep 17 00:00:00 2001 From: Cory Benfield Date: Sat, 15 Dec 2012 13:18:47 +0000 Subject: [PATCH 2/3] Uh, typo broke the link. Yeah. That happened. --- docs/user/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/quickstart.rst b/docs/user/quickstart.rst index 8d0cc9f3..5f6e6a23 100644 --- a/docs/user/quickstart.rst +++ b/docs/user/quickstart.rst @@ -390,7 +390,7 @@ why not write one and submit it? .. _OAuth: https://github.com/requests/requests-oauthlib .. _Kerberos: https://github.com/requests/requests-kerberos .. _NTLM: https://github.com/requests/requests-ntlm -.. _organisation on Github: https://github.com/requests +.. _organization on Github: https://github.com/requests Redirection and History From a7c5d5e8ac7b4fac71352ef359a5af6b812a9a4c Mon Sep 17 00:00:00 2001 From: Cory Benfield Date: Mon, 17 Dec 2012 19:25:21 +0000 Subject: [PATCH 3/3] Split authentication out into a separate file. --- docs/index.rst | 1 + docs/user/authentication.rst | 84 ++++++++++++++++++++++++++++++++++++ docs/user/quickstart.rst | 56 ------------------------ 3 files changed, 85 insertions(+), 56 deletions(-) create mode 100644 docs/user/authentication.rst diff --git a/docs/index.rst b/docs/index.rst index 64929d17..cd0a0f86 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 5f6e6a23..1731b295 100644 --- a/docs/user/quickstart.rst +++ b/docs/user/quickstart.rst @@ -337,62 +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')) - - - -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 a single -`organization on Github`_, 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. If you can't find the one you want, -why not write one and submit it? - -.. _OAuth: https://github.com/requests/requests-oauthlib -.. _Kerberos: https://github.com/requests/requests-kerberos -.. _NTLM: https://github.com/requests/requests-ntlm -.. _organization on Github: https://github.com/requests - - Redirection and History -----------------------