oauth

A python implementation of the signature logic associated with the OAuth 1.0 protocol. It is not designed to handle the entire OAuth flow, and blissfully ignores the nonce. Use it for generating and validating signatures.

The code is hosted here at github. The latest code can be downloaded as a zip file or a tarball.

Requires Python 2.6 or newer and python-urlencoding.

Can be installed using pip:

pip install -r http://code.daaku.org/python-oauth/reqs

OAuthRequest

This is the primary interface into the library.

class oauth.OAuthRequest(url, http_method='GET', params=None, headers={}, version='1.0', timestamp_threshold=300, nonce_length=10)

Represents outgoing or incoming requests. Provides the ability to sign outgoing requests (sign_request), and validate incoming signed requests (validate_signature).

Arguments:

url
The URL. Query parameters in the URL will automatically be parsed out. Required.
http_method
The HTTP method for the request.
params
A dict or string body of request parameters.
headers
A dict which may contain the Authorization header.
version
The oauth_version.
timestamp_threshold
The number of seconds a received timestamp can be off by.
nonce_length
The length of the randomly generated nonce.
validate_signature(signature_method, consumer, token=None)

Validates an existing signature in the request. It does not return a value, and will throw an OAuthError exception when it fails.

BE WARNED: Nonce validation is left to the user.
http://oauth.net/core/1.0/#nonce

Arguments:

signature_method
The class used to handle Signature logic. This should be a concrete implementation of OAuthSignatureMethod.
consumer
A dict containing the oauth_token and oauth_token_secret representing a OAuth Consumer.
token
An optional dict containing the oauth_token and oauth_token_secret representing a OAuth Token to be used in validating the signature.

This is the basic usage flow for validating signatures:

  1. Create a Request object
  2. Create a dict with the OAuth Consumer information
  3. Optionally create a dict with the OAuth Token information
  4. Call validate_signature with the Signature Implementation, Consumer and optional Token and catch OAuthError exceptions.
>>> from oauth import OAuthRequest
>>> from oauth.signature_method.plaintext import OAuthSignatureMethod_PLAINTEXT
>>> import time
>>> params = {
        'oauth_nonce': '9747278682',
        'oauth_timestamp': str(int(time.time())),
        'oauth_consumer_key': 'my-ck',
        'oauth_signature_method': 'PLAINTEXT',
        'oauth_version': '1.0',
        'oauth_signature': 'my-cks%26',
    }
>>> consumer = {'oauth_token': 'my-ck', 'oauth_token_secret': 'my-cks'}
>>> request = OAuthRequest('https://example.org/get-request-token', 'GET', params)
>>> request.validate_signature(OAuthSignatureMethod_PLAINTEXT, consumer)
sign_request(signature_method, consumer, token=None)

Generate a new signature adding/replacing a number of oauth parameters as part of the process. Use this when you are making outbound signed requests.

Arguments:

signature_method
The class used to handle Signature logic. This should be a concrete implementation of OAuthSignatureMethod.
consumer
A dict containing the oauth_token and oauth_token_secret representing a OAuth Consumer.
token
An optional dict containing the oauth_token and oauth_token_secret representing a OAuth Token to be used in signing the request.

This is the basic usage flow for generating signatures:

  1. Create a Request object
  2. Create a dict with the OAuth Consumer information
  3. Optionally create a dict with the OAuth Token information
  4. Call sign_request with the Signature Implementation, Consumer and optional Token.
>>> from oauth import OAuthRequest
>>> from oauth.signature_method.hmac_sha1 import OAuthSignatureMethod_HMAC_SHA1
>>> consumer = {'oauth_token': 'my-ck', 'oauth_token_secret': 'my-cks'}
>>> request = OAuthRequest('http://example.org/get-request-token')
>>> request.sign_request(OAuthSignatureMethod_HMAC_SHA1, consumer)
>>> header = request.to_header()

header will now contain the string that can be used as the Authorization header for this request.

to_header(realm=None)

Generates the Authorization header with the current OAuth parameters.

http://oauth.net/core/1.0/#auth_header

Arguments:

realm
An optional string to use as as the realm. If missing, realm will be ommitted all together.
to_url(include_oauth=False)

Generates a URL suitable for a GET request.

Arguments:

include_oauth
Decides if oauth_ parameters are included. This is useful if the OAuth parameters are being sent via the query string in the URL instead of the Authorization header.
to_postdata(include_oauth=False)

Generates the POST body.

Arguments:

include_oauth
Decides if oauth_ parameters are included. This is useful if the OAuth parameters are being sent via the POST body instead of the Authorization header.

Signature Methods

This library supports the three types of signature methods defined in the OAuth specification. If you intend to use RSA-SHA1 signatures, you will also need to make sure you have the tlslite module available.

If you are using the PLAINTEXT or HMAC-SHA1 signature methods, then all you need to do is use the provided implementations. But the RSA-SHA1 implementation requires you to create a concrete implementation by inheriting from OAuthSignatureMethod_RSA_SHA1 and provide a public_cert and a private_cert, and use your class as the signature_method for signing and validating requests.

class oauth.signature_method.base.OAuthSignatureMethod(request, consumer={}, token={})

The base signature method class. An implementation needs to provide a name and a signature. The default validate_signature compares a newly generated signature.

http://oauth.net/core/1.0/#signing_process

Arguments:

request
An instance of an OAuthRequest object.
consumer
A dict containing the oauth_token and oauth_token_secret representing a OAuth Consumer.
token
An optional dict containing the oauth_token and oauth_token_secret representing a OAuth Token to be used in signing the request.
base_secrets
Returns the concatenated encoded values of the Consumer Secret and Token Secret, separated by a ‘&’ character (ASCII code 38), even if either secret is empty.
base_string

Generates the Signature Base String.

http://oauth.net/core/1.0/#rfc.section.A.5.1

name
An implementation should provide an attribute called name for use as the oauth_signature_method value.
signature
The core oauth_signature generating logic.
validate_signature(signature)

Checks if the given signature is valid. Default behaviour is to generate a new signature and compare it to the given one. Raises an OAuthError if the signatures do not match.

Arguments:

signature
The signature to validate.
class oauth.signature_method.hmac_sha1.OAuthSignatureMethod_HMAC_SHA1(request, consumer={}, token={})

Implements the HMAC-SHA1 signature logic.

http://oauth.net/core/1.0/#rfc.section.9.2

class oauth.signature_method.rsa_sha1.OAuthSignatureMethod_RSA_SHA1(request, consumer={}, token={})

Implements the RSA-SHA1 signature logic.

http://oauth.net/core/1.0/#rfc.section.9.3

This is not a concrete implementation. An implementation needs to provide a public_cert and a private_cert.

private_cert

The private certificate used for signing requests.

An implementation needs to provide this.

public_cert

The public certificate used for validating signatures.

An implementation needs to provide this.

class oauth.signature_method.plaintext.OAuthSignatureMethod_PLAINTEXT(request, consumer={}, token={})

Implements the PLAINTEXT signature logic.

http://oauth.net/core/1.0/#rfc.section.9.4

Error

class oauth.OAuthError
Generic OAuthError for all error cases.