facebook twitter

kQOAuth

kQOAuth is an OAuth 1.0 library written for Qt in C++. The goal of the library has been to provide easy integration for existing Qt applications utilizing Qt signals describing the OAuth process and also to provide a convenient approach to the OAuth user authentication itself if you are not interested in doing all the steps required yourself. kQOAuth also supports Twitter xAuth.

kQOAuth has support for retrieving the user authorization from the service provider’s website. kQOAuth will open the user’s web browser to the authorization page, give a local URL as the callback URL and setup a HTTP server on this address to listen for the reply from the service and then processes it.

If you don’t want to use the convenience APIs but be in full control of the process, you can construct all the requests yourself when you also get all request reply parameters in the reply signals.

kQOAuth will run on all Qt 4.6 and Qt 4.7 supported platforms. It has been verified on Linux, MeeGo, Symbian (deployment as shared library still missing) and Mac OS X 10.6.

Source code

The source code is available on Gitorious at:
http://www.gitorious.org/kqoauth

git clone git://gitorious.org/kqoauth/kqoauth.git

To use kQOAuth in your application:

  1. Compile and install 
    qmake; make; sudo make install
  2. In your .pro file 
    CONFIG += kqoauth
  3. In your source code 
    #include <QtKOAuth>

License

The library and the source code is licensed under the GNU Lesser General Public License (LGPL). For more information, visit http://www.gnu.org/licenses/lgpl.html

Main components

The two main classes of kQOAuth are KQOAuthManager and KQOAuthRequest. KQOAuthManager executes the request and keeps track of the authorization process, while KQOAuthRequest describes the next step of the process and takes care of formatting the headers for the request.

KQOAuthManager
Executes OAuth requests (KQOAuthRequest), parses the replies and emits Qt signals describing the process of the OAuth authentication.

KQOAuthManager will keep track of the state of the authorization process. This means that the provided convenience methods can be used to achieve the necessary steps in OAuth authentication without explicitely constructing each request.

KQOAuthManager can also take care of the user authorization to the protected resources. This is considered to be the must cumbersome step in OAuth authentication, so kQOAuth can take care of it for you. This is done by opening the user’s web browser to the service provider’s authorization page, setting up a local HTTP server that is called upon authorization is completed, and then processing the reply and emitting a signal with the result.

If you are interested in service provider’s custom reply, be sure to connect to the signal requestReady(QByteArray networkReply). This signal will contain the raw response as sent from the service. You can then do whatever you want with it depending on the service.

KQOAuthRequest
KQOAuthRequest is given to KQOAuthManager to execute the requested OAuth request. It will also take care of parameter normalization, generating the necessary authorization header and most importantly it will generate the OAuth signature to the header.

kQOAuth gives also the possibility to be in total control of the authorization process if so desired. Internally KQOAuthManager uses KQOAuthRequests to construct the request that are being sent. Nothing prevents you from constructing all the necessary KQOAuthRequests yourself, giving them to KQOAuthManager and listening on requestReady(QByteArray networkReponse) signals when the request is completed. KQOAuthRequest will take care of request signing and header normalization for you anyway.

OAuth requests can be sent to the service as either HTTP POST or GET requests. This can be specified with the method setHttpMethod() giving KQOAuthRequest::GET or KQOAuthRequest::POST as parameter.

KQOAuthRequest_XAuth
KQOAuthRequest_XAuth encapsulates the functionality needed to do a xAuth authentication to Twitter. With xAuth you can do the authentication in one step. When initializing the request, specify the request type to be KQOAuthRequest::AccessToken and give the username and password with the method setXAuthLogin().  Then you can pass the request to KQOAuthManager to execute it. As a reply you will get the signal onAccessTokenReceived(QString accessToken, QString accessTokenSecret) that contain the necessary tokens to be used when accessing protected resources.

The TwitterCLI example application contains a complete functioning example demonstrating the xAuth authentication. Please note that xAuth is only one step and no other requests are needed in order to get access to protected resources.

Example

This is a command line utility for sending Twitter status updates. The application uses the convenience APIs to request access to protected resources and then constructs a request explicitly for sending the Twitter update (although there is a convenience method to do this directly, too).

#include <QtKOAuth>
#include "twittercli.h"

TwitterCLI::TwitterCLI() {
   oauthRequest = new KQOAuthRequest;
   oauthManager = new KQOAuthManager(this);
}

void TwitterCLI::getAccess()  {
   connect(oauthManager, SIGNAL(temporaryTokenReceived(QString,QString)),
       this, SLOT(onTemporaryTokenReceived(QString, QString)));

   connect(oauthManager, SIGNAL(authorizationReceived(QString,QString)),
       this, SLOT( onAuthorizationReceived(QString, QString)));

   connect(oauthManager, SIGNAL(accessTokenReceived(QString,QString)),
      this, SLOT(onAccessTokenReceived(QString,QString)));

   oauthRequest->initRequest(KQOAuthRequest::TemporaryCredentials,
                    QUrl("https://api.twitter.com/oauth/request_token"));
   oauthRequest->setConsumerKey("9PqhX2sX7DlmjNJ5j2Q");
   oauthRequest->setConsumerSecretKey("1NYYhpIw1fXItywS9Bw6gGRmkRyF9zB54UXkTGcI8");

   oauthManager->setHandleUserAuthorization(true);

   oauthManager->executeRequest(oauthRequest);
}

void TwitterCLI::onTemporaryTokenReceived(QString token, QString tokenSecret)
{
   QUrl userAuthURL("https://api.twitter.com/oauth/authorize");

   if( oauthManager->lastError() == KQOAuthManager::NoError) {
       qDebug() << "Opening authorization web site: " << userAuthURL;
       oauthManager->getUserAuthorization(userAuthURL);
   }

}

void TwitterCLI::onAuthorizationReceived(QString token, QString verifier) {
    qDebug() << "User authorization received: " << token << verifier;

    oauthManager->getUserAccessTokens(
                       QUrl("https://api.twitter.com/oauth/access_token")
                  );
}

void TwitterCLI::onAccessTokenReceived(QString token, QString tokenSecret) {
    qDebug() << "Access token received: " << token << tokenSecret;

    oauthSettings.setValue("oauth_token", token);
    oauthSettings.setValue("oauth_token_secret", tokenSecret);

     qDebug() << "Access tokens now stored. You can Tweet now!";

    QCoreApplication::exit(0);
}

void TwitterCLI::onAuthorizedRequestDone() {
    qDebug() << "Request sent to Twitter!";
    QCoreApplication::exit(0);
}

void TwitterCLI::sendTweet(QString tweet) {

    if( oauthSettings.value("oauth_token").toString().isEmpty() ||
        oauthSettings.value("oauth_token_secret").toString().isEmpty()) {
        qDebug() << "No access tokens. Aborting.";

       return;
    }

    oauthRequest->initRequest(KQOAuthRequest::AuthorizedRequest,
                       QUrl("http://api.twitter.com/1/statuses/update.xml")
                   );
    oauthRequest->setConsumerKey("9PqhX2sX7DlmjNJ5j2Q");
    oauthRequest->setConsumerSecretKey("1NYYhpIw1fXItywS9Bw6gGRmkRyF9zB54UXkTGcI8");
    oauthRequest->setToken(oauthSettings.value("oauth_token").toString());
    oauthRequest->setTokenSecret(oauthSettings.value("oauth_token_secret").toString());

    KQOAuthParameters params;
    params.insert("status", tweet);
    oauthRequest->setAdditionalParameters(params);

    oauthManager->executeRequest(oauthRequest);

    connect(oauthManager, SIGNAL(authorizedRequestReady()),
         this, SLOT(onAuthorizedRequestReady()));
}

The complete source code for the application can be found at http://www.gitorious.org/kqoauth/kqoauth/blobs/master/examples/twittercli/twittercli.cpp

References

kQOAuth is already used by the following projects:

  • eCoach – eCoach is an application for recording and managing sport activities with Nokia N900.

Changelog

  • 0.95: Critical bug fixes for POST requests and token in user authorization page URL.
  • 0.94: xAuth support was added.
  • 0.93: Added support to use custom QNetworkAccessManager
  • 0.92: Network service reply is emitted with signal requestReady(QByteArray) from KQOAuthManager.
  • 0.91: GET support was added

Roadmap

kQOAuth is still in development. Here are the items, in priority order, I still want to add to kQOAuth:

  • Support for OAuth 2.0 Native Application profile
  • More example application to demonstrate how kQOAuth interacts with different services (Hattrick, Vimeo and more…)

So OAuth 2.0 support is coming down the line. This, however, requires some refactoring of the code that we want to do before the support can be added.

Contact

In case you have any questions about kQOAuth or suggestions for improvements , please send emails to kqoauth@d-pointer.com or via Twitter @d_ptr

News

d-pointer at Twitter

Powered by Twitter Tools

Comments

  • d-pointer 2011