QOAuth  1.0.1
Public Member Functions | Properties | List of all members
QOAuth::Interface Class Reference

This class provides means for interaction with network services supporting OAuth authorization scheme. More...

#include <QtOAuth>

Inheritance diagram for QOAuth::Interface:

Public Member Functions

 Interface (QObject *parent=0)
 Creates a new QOAuth::Interface class instance with the given parent.
 
 Interface (QNetworkAccessManager *manager, QObject *parent=0)
 Creates a new QOAuth::Interface class instance with the given parent, using manager for network connections. More...
 
virtual ~Interface ()
 Destroys the QOAuth::Interface object.
 
QNetworkAccessManager * networkAccessManager () const
 Returns the network access manager used by the interface.
 
void setNetworkAccessManager (QNetworkAccessManager *manager)
 Sets manager to be the network access manager used by the interface. More...
 
bool setRSAPrivateKey (const QString &key, const QCA::SecureArray &passphrase=QCA::SecureArray())
 
bool setRSAPrivateKeyFromFile (const QString &filename, const QCA::SecureArray &passphrase=QCA::SecureArray())
 
ParamMap requestToken (const QString &requestUrl, HttpMethod httpMethod, SignatureMethod signatureMethod=HMAC_SHA1, const ParamMap &params=ParamMap())
 
ParamMap accessToken (const QString &requestUrl, HttpMethod httpMethod, const QByteArray &token, const QByteArray &tokenSecret, SignatureMethod signatureMethod=HMAC_SHA1, const ParamMap &params=ParamMap())
 
QByteArray createParametersString (const QString &requestUrl, HttpMethod httpMethod, const QByteArray &token, const QByteArray &tokenSecret, SignatureMethod signatureMethod, const ParamMap &params, ParsingMode mode)
 
QByteArray inlineParameters (const ParamMap &params, ParsingMode mode=ParseForRequestContent)
 

Properties

QByteArray consumerKey
 This property holds the consumer key. More...
 
QByteArray consumerSecret
 This property holds the consumer secret. More...
 
uint requestTimeout
 This property holds the timeout value in milliseconds for issued network requests. More...
 
bool ignoreSslErrors
 This property is used to control SSL errors handling. More...
 
int error
 This property holds the error code. More...
 

Detailed Description

The QOAuth::Interface class is meant to enable OAuth support in applications in as simple way as possible. It provides 4 basic methods, two of which serve for authorization purposes:

and the other two help with creation of requests for accessing Protected Resources:

OAuth authorization scheme

According to OAuth 1.0 Core specification, the OAuth protocol enables websites or applications (Consumers) to access Protected Resources from a web service (Service Provider) via an API, without requiring Users to disclose their Service Provider credentials to the Consumers. Simply, OAuth is a way of connecting an application to the Service Provider's API without needing to provide User's login or password. The authorization is based on an exchange of a Token (user-specific) together with a Consumer Key (application-specific), encrypted with a combination of so called Token Secret and Customer Secret. Getting access to Protected Resources consists in three basic steps:

  1. obtaining an unauthorized Request Token from the Service Provider,
  2. asking the User to authorize the Request Token,
  3. exchanging the Request Token for the Access Token.

Details are covered in Section 6 of the OAuth 1.0 Core Specification. As the authorization procedure is quite complex, the QOAuth library helps to simplify it by doing all the dirty work behind the scenes.

OAuth authorization with QOAuth

First step of OAuth authorization can be done in one line using QOAuth library. Consult the example:

QByteArray token;
QByteArray tokenSecret;
// set the consumer key and secret
qoauth->setConsumerKey( "75b3d557c9268c49cfdf041a" );
qoauth->setConsumerSecret( "fd12803fbf0760d34cd2ceb9955199ce" );
// set a timeout for requests (in msecs)
qoauth->setRequestTimeout( 10000 );
// send a request for an unauthorized token
qoauth->requestToken( "http://example.com/request_token",
// if no error occurred, read the received token and token secret
if ( qoauth->error() == QOAuth::NoError ) {
token = reply.value( QOAuth::tokenParameterName() );
tokenSecret = reply.value( QOAuth::tokenSecretParameterName() );
}

Once the unauthorized Request Token is received, User has to authorize it using Service Provider-defined method. This is beyond the scope of this library. Once User authorizes the Request Token, it can be exchanged for an Access Token that authorizes the application to access User's Protected Resources. This can be done with another one line:

// if necessary, create a map of additional arguments required by the Service Provider
QOAuth::ParamMap otherArgs;
otherArgs.insert( "misc_arg1", "value1" );
otherArgs.insert( "misc_arg2", "value2" );
// send a request to exchange Request Token for an Access Token
qoauth->accessToken( "http://example.com/access_token", QOAuth::POST, token,
tokenSecret, QOAuth::HMAC_SHA1, otherArgs );
// if no error occurred, read the Access Token (and other arguments, if applicable)
if ( qoauth->error() == QOAuth::NoError ) {
token = reply.value( QOAuth::tokenParameterName() );
tokenSecret = reply.value( QOAuth::tokenSecretParameterName() );
otherInfo = reply.value( "misc_arg3" );
}

Once the Access Token is received, the application is authorized.

Requesting Protected Resources with QOAuth

In order to access Protected Resources, the application has to send a request containing arguments including Customer Key and Access Token, and encrypt them with Customer Secret and Token Secret. The process of constructing such a request can be reduced to another one-line call with QOAuth::Interface. The example code for inlining all request parameters (both User-specific and OAuth-related):

QByteArray url( "http://example.com/get_photo" );
// create a request parameters map
map.insert( "file", "flower_48.jpg" );
map.insert( "size", "small" );
// construct the parameters string
QByteArray content =
token, tokenSecret, map,
// append parameters string to the URL
url.append( content );
QNetworkRequest request( QUrl( url ) );
// etc...

If Service Provider requires the OAuth authorization to be done in the Authorization header field, then only User-specific parameters should be inlined with the URL:

QByteArray url( "http://example.com/get_photo" );
// create a request parameters map
map.insert( "file", "flower_48.jpg" );
map.insert( "size", "small" );
// construct the authorization header
QByteArray header =
token, tokenSecret, map,
// append parameters string to the URL
// alternatively you can use QOAuth::ParseForRequestContent if you want
// to use the output as a POST request content (remember then of passing
// QOAuth::POST above).
url.append( qoauth->inlineParameters( map, QOAuth::ParseForInlineQuery ) );
QNetworkRequest request( QUrl( url ) );
request.setRawHeader( "Authorization", header );
// etc...

Capabilities

QOAuth library works with all 3 signature methods supported by the OAuth protocol, namely HMAC-SHA1, RSA-SHA1 and PLAINTEXT. Hovewer, RSA-SHA1 and (especially) PLAINTEXT methods may still need additional testing for various input conditions.

Constructor & Destructor Documentation

QOAuth::Interface::Interface ( QNetworkAccessManager *  manager,
QObject *  parent = 0 
)

Use this constructor if you want to use your custom network access manager to handle network connections needed by the interface.

/sa setNetworkAccessManager()

Member Function Documentation

QOAuth::ParamMap QOAuth::Interface::accessToken ( const QString &  requestUrl,
HttpMethod  httpMethod,
const QByteArray &  token,
const QByteArray &  tokenSecret,
SignatureMethod  signatureMethod = HMAC_SHA1,
const ParamMap params = ParamMap() 
)

This method constructs and sends a request for exchanging a Request Token (obtained previously with a call to requestToken()) for an Access Token, that authorizes the application to access Protected Resources. This is the third step of the OAuth authentication flow, according to OAuth 1.0 Core specification. The PLAINTEXT signature method uses Customer Secret and (if provided) Token Secret to sign a request. For the HMAC-SHA1 and RSA-SHA1 signature methods the Signature Base String is created using the given requestUrl, httpMethod, token and tokenSecret. The optional request parameters specified by the Service Provider can be passed in the params ParamMap.

The Signature Base String contains the consumerKey and uses consumerSecret for encrypting the message, so it's necessary to provide them both before issuing this request. The method will check if both consumerKey and consumerSecret are provided, and fail if any of them is missing.

When the signature is created, the appropriate request is sent to the Service Provider (namely, the requestUrl). Depending on the type of the request, the parameters are passed according to the Consumer Request Parametes section of the OAuth specification, i.e.:

  • for GET requests, in the HTTP Authorization header, as defined in OAuth HTTP Authorization Scheme,
  • for POST requests, as a request body with content-type set to application/x-www-form-urlencoded.

Once the request is sent, a local event loop is executed and set up to wait for the request to complete. If the requestTimeout property is set to a non-zero value, its vaue is applied as a request timeout, after which the request is aborted.

Returns
If request succeded, the method returns all the data passed in the Service Provider response (including an authorized Access Token and Token Secret), formed in a ParamMap. This request ends the authorization process, and the obtained Access Token and Token Secret should be kept by the application and provided with every future request authorized by OAuth, e.g. using createParametersString(). If request fails, the error property is set to an appropriate value, and an empty ParamMap is returned.
See also
requestToken(), createParametersString(), error
QByteArray QOAuth::Interface::createParametersString ( const QString &  requestUrl,
HttpMethod  httpMethod,
const QByteArray &  token,
const QByteArray &  tokenSecret,
SignatureMethod  signatureMethod,
const ParamMap params,
ParsingMode  mode 
)

This method generates a parameters string required to access Protected Resources using OAuth authorization. According to OAuth 1.0 Core specification, every outgoing request for accessing Protected Resources must contain information like the Consumer Key and Access Token, and has to be signed using one of the supported signature methods.

The PLAINTEXT signature method uses Customer Secret and (if provided) Token Secret to sign a request. For the HMAC-SHA1 and RSA-SHA1 signature methods the Signature Base String is created using the given requestUrl, httpMethod, token and tokenSecret. The optional request parameters specified by the Service Provider can be passed in the params ParamMap.

The Signature Base String contains the consumerKey and uses consumerSecret for encrypting the message, so it's necessary to provide them both before issuing this request. The method will check if both consumerKey and consumerSecret are provided, and fail if any of them is missing.

The mode parameter specifies the format of the parameter string.

Returns
The parsed parameters string, that depending on mode and httpMethod is:
mode outcome
QOAuth::ParseForRequestContent ready to be posted as a request body
QOAuth::ParseForInlineQuery prepended with a '?' and ready to be appended to the requestUrl
QOAuth::ParseForHeaderArguments ready to be set as an argument for the Authorization HTTP header
QOAuth::ParseForSignatureBaseString meant for internal use
See also
inlineParameters()
QByteArray QOAuth::Interface::inlineParameters ( const ParamMap params,
ParsingMode  mode = ParseForRequestContent 
)

This method is provided for convenience. It generates an inline query string out of given parameter map. The resulting string can be either sent in an HTTP POST request as a request content, or appended directly to an HTTP GET request's URL as a query string. When using this method for preparing an HTTP GET query string you can set the mode to ParseForInlineQuery to have the string prepended with a question mark (separating the URL path from the query string). Modes other than QOAuth::ParseForRequestContent and QOAuth::ParseForInlineQuery produce an empty byte array.

Use this method together with createParametersString(), when you request a header parameters string (QOAuth::ParseForHeaderArguments) together with HTTP GET method. In such case, apart from header arguments, you must provide a query string containing custom request parameters (i.e. not OAuth-related). Pass the custom parameters map to this method to receive a query string to be appended to the URL.

See also
createParametersString()
QOAuth::ParamMap QOAuth::Interface::requestToken ( const QString &  requestUrl,
HttpMethod  httpMethod,
SignatureMethod  signatureMethod = HMAC_SHA1,
const ParamMap params = ParamMap() 
)

This method constructs and sends a request for obtaining an unauthorized Request Token from the Service Provider. This is the first step of the OAuth authentication flow, according to OAuth 1.0 Core specification. The PLAINTEXT signature method uses Customer Secret and (if provided) Token Secret to sign a request. For the HMAC-SHA1 and RSA-SHA1 signature methods the Signature Base String is created using the given requestUrl and httpMethod. The optional request parameters specified by the Service Provider can be passed in the params ParamMap.

The Signature Base String contains the consumerKey and uses consumerSecret for encrypting the message, so it's necessary to provide them both before issuing this request. The method will check if both consumerKey and consumerSecret are provided, and fail if any of them is missing.

When the signature is created, the appropriate request is sent to the Service Provider (namely, the requestUrl). Depending on the type of the request, the parameters are passed according to the Consumer Request Parametes section of the OAuth specification, i.e.:

  • for GET requests, in the HTTP Authorization header, as defined in OAuth HTTP Authorization Scheme,
  • for POST requests, as a request body with content-type set to application/x-www-form-urlencoded.

Once the request is sent, a local event loop is executed and set up to wait for the request to complete. If the requestTimeout property is set to a non-zero value, its vaue is applied as a request timeout, after which the request is aborted.

Returns
If request succeded, the method returns all the data passed in the Service Provider response (including a Request Token and Token Secret), formed in a ParamMap. If request fails, the error property is set to an appropriate value, and an empty ParamMap is returned.
See also
accessToken(), error
void QOAuth::Interface::setNetworkAccessManager ( QNetworkAccessManager *  manager)

The interface class takes ownership of the manager. If there already is a manager, it's being deleted.

/sa networkAccessManager()

bool QOAuth::Interface::setRSAPrivateKey ( const QString &  key,
const QCA::SecureArray &  passphrase = QCA::SecureArray() 
)

This method is useful when using OAuth with RSA-SHA1 signing algorithm. It reads the RSA private key from the string given as key, and stores it internally. If the key is secured by a passphrase, it should be passed as the second argument.

The provided string is decoded into a private RSA key, optionally using the passphrase. If key contains a valid RSA private key, this method returns true. If any problems were encountered during decoding (either the key or the passphrase are invalid), false is returned and the error code is set to QOAuth::RSADecodingError.

See also
setRSAPrivateKeyFromFile()
bool QOAuth::Interface::setRSAPrivateKeyFromFile ( const QString &  filename,
const QCA::SecureArray &  passphrase = QCA::SecureArray() 
)

This method is useful when using OAuth with RSA-SHA1 signing algorithm. It reads the RSA private key from the given file, and stores it internally. If the key is secured by a passphrase, it should be passed as the second argument.

The provided file is read and decoded into a private RSA key, optionally using the passphrase. If it contains a valid RSA private key, this method returns true. If any problems were encountered during decoding, false is returned and the appropriate error code is set:

See also
setRSAPrivateKey()

Property Documentation

QByteArray QOAuth::Interface::consumerKey
readwrite

The consumer key is used by the application to identify itself to the Service Provider.

Access functions:

  • QByteArray consumerKey() const
  • void setConsumerKey( const QByteArray &consumerKey )
QByteArray QOAuth::Interface::consumerSecret
readwrite

The consumerSecret is used by the application for signing outgoing requests.

Access functions:

  • QByteArray consumerSecret() const
  • void setConsumerSecret( const QByteArray &consumerSecret )
int QOAuth::Interface::error
read

The error code is initially set to NoError, and its value is updated with every method that can cause errors.

Access functions:

  • int error() const
See also
ErrorCode
bool QOAuth::Interface::ignoreSslErrors
readwrite

The default value is false, meaning that the interface will fail upon an SSL error. Set it to true if you want to disregard any SSL errors encountered during the authorization process.

Access functions:

  • bool ignoreSslErrors() const
  • void setIgnoreSslErrors( bool enabled )
uint QOAuth::Interface::requestTimeout
readwrite

The QOAuth::Interface class can send network requests when asked to do so by calling either requestToken() or accessToken() method. By defining the requestTimeout, requests can have the time constraint applied, after which they fail, setting error to Timeout. The requestTimeout value is initially set to 0, which in this case means that no timeout is applied to outgoing requests.

Access functions:

  • uint requestTimeout() const
  • void setRequestTimeout( uint requestTimeout )

The documentation for this class was generated from the following files: