Comments, Code and Qt. Some words about the wonderful world of software engineering

Introducing kQOAuth – Easy and Powerful OAuth library for Qt

kQOAuth is a powerful yet easy way to integrate OAuth authentication to your Qt application. kQOAuth handles OAuth request signing, request submitting and reply parsing for you. It also provides an easy way to retrieve user authorization to protected resources with a built in HTTP server. All this is done with Qt programming in mind, so you can use Qt's signals to react to OAuth events in your own application. This also means that the library works fully asynchronously. kQOAuth is licensed under the LGPL license.

You can read more about kQOAuth usage in my next post: Advanced use of kQOAuth. There is now also an official web page for kQOAuth: http://www.johanpaul.com/blog/kqoauth/

If you are unfamiliar with OAuth, it is worth first checking out some tutorials:

• Beginner’s Guide to OAuth – Part II : Protocol Workflow
• Authenticating Requests with OAuth

Features

kQOAuth is written in C++ and its main features include:

• Provides easy, "automated", OAuth authentication but also more advanced detailed control of the authentication process.
• OAuth request handling (request signing, submitting and result parsing).
• No dependencies to external libraries, for example QCA.
• Works with signals and slots - asynchronously.
• Handles protected resource owner authentication by taking care of opening temporary token retrieval web page and parsing the reply with a built in HTTP server.

Download and source code

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

Usage - the easy way

kQOAuth can be used in two different ways. If you don't want to control the authentication process in detail, you can use the convenience APIs to get access to protected resources with a few lines of code.The only pieces of information you will need are

• your application's consumer key
• your application's secret consumer key
• URL for retrieving the temporary request tokens
• URL for the user to authenticate the application to access the protected resources
• URL for sending the authenticated request.

All of the above information should be available from the service provider.

The example below is taken from the Twitter CLI example application. Please note that parameter names are included in the connect() statements in the examples below for the purpose of clarity. To see the complete compilable example, please check the TwitterCLI example application.

Temporary token.

You will need to start OAuth authentication by creating a KQOAuthRequest and initialize it to be of type KQOAuthRequest::TemporaryCredential. If you want to use the easy, "automated", approach for OAuth authentication then this is probably your hardest step. And even this is not that hard.

KQOAuthManager *oauthManager = new KQOAuthManager(this);

connect(oauthManager, SIGNAL(temporaryTokenReceived(QString oauthToken, QString oauthTokenSecret)),
this, SLOT(onTemporaryTokenReceived(QString oauthToken, QString oauthTokenSecret)));

KQOAuthRequest *oauthRequest = new KQOAuthRequest;

oauthRequest->initRequest(KQOAuthRequest::TemporaryCredentials, QUrl(temporaryTokenEndpoint));
oauthRequest->setConsumerKey(consumerKey);
oauthRequest->setConsumerSecretKey(consumerKeySecret);

oauthManager->setHandleUserAuthorization(true);
oauthManager->executeRequest(oauthRequest);

That's it.Let's see the details.

KQOAuthManager *oauthManager = new KQOAuthManager(this);

connect(oauthManager, SIGNAL(temporaryTokenReceived(QString oauthToken, QString oauthTokenSecret)),
this, SLOT(onTemporaryTokenReceived(QString oauthToken, QString oauthTokenSecret)));

Here you first create the KQOAuthManager which will handle the state of the OAuth authentication process. You connect the signal temporaryTokenReceived(QString oauthToken, QString oauthTokenSecret)) to an appropriate slot and as a result you will get the temporary request tokens which you will need in next steps of the authentication process. Actually not even that, but we'll get to that in a short while.

KQOAuthRequest *oauthRequest = new KQOAuthRequest;

QUrl temporaryTokenEndpoint("https://api.twitter.com/oauth/request_token");
oauthRequest->initRequest(KQOAuthRequest::TemporaryCredentials, QUrl(temporaryTokenEndpoint));
oauthRequest->setConsumerKey(consumerKey);
oauthRequest->setConsumerSecretKey(consumerKeySecret);

Next you will create a KQOAuthRequest request that will be sent using the KQOAuthManager. initRequest() call will initialize the request to be a request that will fetch the temporary request tokens and it will also need the service endpoint for retrieving the tokens. You also give the request your consumer key and consumer secret key. These are needed for signing the request and for the service to know who is asking for permissions.

oauthManager->setHandleUserAuthorization(true);

If you specify this to be true, this will notify the KQOAuthManager that you want it to take care of user authorization on your behalf. What this does is that it will open the user's web browser for authentication and setup a HTTP server that will retrieve the result and parse them for you. To initiate this, just one command is needed in next phase.

oauthManager->executeRequest(oauthRequest);

The request which was initialized will be signed and sent by the KQOAuthManager to the endpoint. It will also take care of signaling you when the tokens are available. The signal temporaryTokenReceived(QString oauthToken, QString oauthTokenSecret) is emited with the resulting temporary request tokens.

User authorization

We now have the request tokens that we can use to retrieve user's authorization for us to access the protected resources. Below is the Qt slot which was called as a result of the signal. The signal contains the retrieved temporary tokens, but as  you can see from the code below you don't really need them if you want to do the easy OAuth authentication process.

The slot below we will ask KQOAuthManager to handle user authorization for us and we connect the signal authorizationReceived(QString oauthToken, QString oauthVerifier) to a slot that is called after this step is concluded. The signal will contain the oauth_verifier token we need in the next step.

void TwitterCLI::onTemporaryTokenReceived(QString token, QString tokenSecret) {

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

if( oauthManager->lastError() == KQOAuthManager::NoError) {
oauthManager->getUserAuthorization(QUrl("https://api.twitter.com/oauth/authorize"));
}
}

If you did set oauthManager->setHandleUserAuthorization(true) then this is all you need for retrieving the user's authorization to the protected resources (i.e. user will grant your application access to the information you are interested in). The URL given above is the service's URL for providing the user's authorization to protected resources. What the request above will do is:

• Open the user's web browser to the authorization URL with the correct token.
• Use an internally generated URL as the callback URL where the service will return after user's authoriszation
• Setup a HTTP server listening on the generated URL.
• Parse the reply and provide you with the oauth_verifier token needed in next step (but you will not need this if you don't want to).

authorizationRecieved(oauth_token, oauth_verifier) signal is emitted when the user has authorized the application.

Access tokens

The user has now authorized us to access the protected resources. The last step before we can access the protected resources is to exchange the temporary request tokens (retrieved from the first step) for access tokens which are used when accessing the protected resources. Below is the slot that is called after the user has authorized us to access the protected resources.

void TwitterCLI::onAuthorizationReceived(QString token, QString verifier) {

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

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

}

token parameter is our temporary request token which is identifying our authentication session. The verifier parameter is our verifier code which identifies the user's authentication to protected resources. These are sent as the signal parameters from the previous step, but in this easy authentication process you don't need them.

Above is the only step you do to in order to exchange the temporary request tokens for the access tokens which we need when sending request to the protected resource. The URL is the service's endpoint for exchanging the tokens.

As you can see again, we connect the signal accessTokenReceived(QString oauthToken, QString oauthTokenSecret) to a slot with the resulting tokens from this step.

Sending authenticated requests

We are finally done! When this slot is called, you are authenticated to access the protected resources. The signal parameters provide you with the access tokens, which you want to keep in a secure place. With these tokens you can access the protected resource until the user revokes the tokens. Please note that again following this easy OAuth authentication process you will not need the token parameters - these are taken care of by the manager.

Below is the slot which is called when we have access to protected resources. In this slot we can start communicating to the service and do what we actually wanted to do. In this example I am going to send a tweet to Twitter. The tweet will be sent from the account which provided us access to its account.

void TwitterCLI::onAccessTokenReceived(QString token, QString tokenSecret) {

QUrl requestEndpoint("http://api.twitter.com/1/statuses/update.xml");

KQOAuthParameters params;
params.insert("status", "Hello, World!");

oauthManager->sendAuthorizedRequest(requestEndpoint, requestParameters);

}

And now the world can see your tweet from your application!

When the request is done, the KQOAuthManager will emit the signal authorizedRequestReady() and this will conclude the kQOAuth interactions.

Example application - command line Twitter client

kQOAuth provides as example application a command line tool for sending Twitter updates - tweets. The command line tool uses the easy authentication process to retrieve access tokens and will store them with QSettings. After that you can send tweets from the command line.

twittercli -a          -- This will request for the access tokens and do all the steps between.
twittercli -t 'Hello!' -- This will send the tweet "Hello!" to Twitter.

The Twitter command line example application is available on Gitorious.org at http://www.gitorious.org/kqoauth/kqoauth/trees/master/examples/twittercli

Disclaimer

kQOAuth is still at version 0.91. Use it at your own risk. It has so far been tested on Mac OS X 10.6. and Linux (Ubuntu 10.10). Only Qt 4.7 and newer are supported. kQOAuth still supports only HMAC-SHA1 signing method. Patches are welcome.

Technorati Tags: authentication, c++, hmac-sha1, oauth, oauth library, Qt