QOAuth
1.0.1
|
This class provides means for interaction with network services supporting OAuth authorization scheme. More...
#include <QtOAuth>
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 ¶ms=ParamMap()) |
ParamMap | accessToken (const QString &requestUrl, HttpMethod httpMethod, const QByteArray &token, const QByteArray &tokenSecret, SignatureMethod signatureMethod=HMAC_SHA1, const ParamMap ¶ms=ParamMap()) |
QByteArray | createParametersString (const QString &requestUrl, HttpMethod httpMethod, const QByteArray &token, const QByteArray &tokenSecret, SignatureMethod signatureMethod, const ParamMap ¶ms, ParsingMode mode) |
QByteArray | inlineParameters (const ParamMap ¶ms, 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... | |
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:
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:
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.
First step of OAuth authorization can be done in one line using QOAuth library. Consult the example:
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:
Once the Access Token is received, the application is authorized.
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):
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:
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.
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.
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.:
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.
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.
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 |
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.
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.:
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.
void QOAuth::Interface::setNetworkAccessManager | ( | QNetworkAccessManager * | manager | ) |
The interface class takes ownership of the manager. If there already is a manager, it's being deleted.
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.
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:
QOAuth::RSAKeyFileError
- when the key file doesn't exist or is unreadable QOAuth::RSADecodingError
- if problems occurred during encoding (either the key and/or password are invalid).
|
readwrite |
The consumer key is used by the application to identify itself to the Service Provider.
Access functions:
|
readwrite |
The consumerSecret is used by the application for signing outgoing requests.
Access functions:
|
read |
|
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:
|
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: