Welcome to the already 5th part of this article series on SilverlightShow where we are discussing how Windows 8 apps can integrate with the outside world. In the 2 previous parts, we have explored some specific APIs, namely the BackgroundTransfer API for doing uploads and downloads in the background and the Tile API, where we looked using both periodic tiles for time-interval based tile updates as well as the push notifications where the server was capable of sending an update to the connected client when needed.
In this 5th part, we are going to switch gears and we’re going to explore how we can build apps that integrate with public APIs such as Facebook and Twitter. For both Facebook and Twitter, we are going to explore the way that we can authenticate with these services so that our app can access the API. Let’s dive in!
Integrating with Twitter and Facebook
The traditional approach
When we want to build an application which uses a public API, we traditionally face some common problems. Most of the time, we would let the user enter his/her credentials within the application. After we have captured these, we would then try to perform the authentication with the public API. This brings along some issues. For one, the user would have to trust you completely. It would be possible that you as the developer don’t have best intentions and behind the scenes log these credentials somewhere. It would even not require bad intentions: just not being careful enough by storing these credentials on the local system somewhere would be enough to compromise the user’s account.
Another issue that we face this way is happening when the user changes his/her password. The stored credentials would suddenly not work any longer and therefore the app would have to prompt the user again to enter these.
Many services today, including Facebook and Twitter are now using OAuth. Using OAuth, we don’t need to now the credentials from within our application. Instead, what we are getting is that the app gets authenticated to work with the service in the name of the user. Therefore, OAuth solves the second problem by means of building a token for the app, but not really the first one. Enter the WebAuthenticationBroker.
The WebAuthenticationBroker
The WebAuthenticationBroker class is a new class coming with WinRT. This class makes it possible to perform Internet authentication in a very simple and secure way (from both the developer’s and the user’s perspective). Basically, the WebAuthenticationBroker consists out of an API, a broker (an intermediate) and a web host. When our app needs to interface with a public API, the user won’t be entering credentials within the app any longer, but instead directly in a webpage, hosted in the web host in a separate app container. The following graphic makes things a bit clearer.
First, My App, which wants to integrate with Twitter calls the WebAuthenticationBroker API. Note that the app isn’t directly communicating with the web site (Twitter) nor is it prompting the user to enter credentials. We do have to pass the URL though where the application needs to go for authentication with the public API. The broker in turn now creates a dialog, modal to My App (meaning that as user, you’re working with the dialog and can’t access the app). In a new app container, separate from the one in which My App is running, the web authentication host is started. The host window is now positioned within the dialog. Finally, the passed URL is show in the host.
The user can now enter his credentials directly on the page. When authentication is completed, the broker is notified. The broker now tears down the dialog box and passes the result back to the calling application.
This solves the issues we had initially. The app itself doesn’t get access to the credentials. It’s not responsible for storing these anymore. The user can be sure of this as well. The only thing the application gets is a token, which is an authentication for the app to work with the API using the credentials that logged in.
Let’s take a look at this in 2 examples.
Facebook API
First, we are going to work with Facebook. Facebook’s authentication mechanism is pretty simple (certainly compared to Twitter). To work with Facebook’s API, you need to be a registered developer. To do so, go to https://developers.facebook.com/apps, login with your Facebook login and follow the steps to create a new app.
The net result is a list of parameters, as shown below for our sample app.
Once that’s finished, create a new Windows 8 application and name it MyFacebookApp. For this app, we’ll build up the UI so that we can make it “general purpose”: we allow for entering the callback URI and the application ID.
When clicking on the Launch button, we’ll trigger some code.
We start by creating the correct URLs for the authentication process.
string facebookUrl =
"https://www.facebook.com/dialog/oauth?client_id="
+ Uri.EscapeDataString(FacebookClientID.Text)
+ "&redirect_uri=" + Uri.EscapeDataString(FacebookCallbackUrl.Text)
+ "&scope=read_stream&display=popup&response_type=token";
Uri StartUri = new Uri(facebookUrl);
Uri EndUri = new Uri(FacebookCallbackUrl.Text);
Note that we are coding into our app this URL. This will be the web page that’s shown to the user to enter his credentials. It’s not something we can decide on, it’s maintained by the owner of the API.
Next, we can communicate with the broker through the WebAuthenticationBroker API.
WebAuthenticationResult WebAuthenticationResult = await WebAuthenticationBroker.AuthenticateAsync(
WebAuthenticationOptions.None,
StartUri,
EndUri);
if (WebAuthenticationResult.ResponseStatus == WebAuthenticationStatus.Success)
{
StatusTextBlock.Text = "Success: " + WebAuthenticationResult.ResponseData.ToString();
}
else if (WebAuthenticationResult.ResponseStatus == WebAuthenticationStatus.ErrorHttp)
{
StatusTextBlock.Text = "Error: " + "HTTP Error returned by AuthenticateAsync() : " + WebAuthenticationResult.ResponseErrorDetail.ToString();
}
else
{
StatusTextBlock.Text = "Error: " + "Error returned by AuthenticateAsync() : " + WebAuthenticationResult.ResponseStatus.ToString();
}
After successful authentication, we get the OAuth token that we can now use to make calls to Facebook which require authentication.
Run the app now, pasting in your values you’ve received after registering. When you now click the Launch button, the WebAuthenticationBroker starts doing its job, showing the dialog.
We can clearly see that our app is still running, as there’s a semi-transparent overlay being created. The bulk of the page though is now covered with our dialog window, showing the authentication page from Facebook.
After logging in, we see the following:
This is the response from Facebook, being passed by the broker. We need to parse this string to get the access token. This can now be stored for example in the PasswordVault.
Twitter API
As can be seen, authenticating with Facebook is pretty straightforward. Twitter is however, more complex. They require a 3 step process:
- Obtaining a request token: basically at this point, we are preparing the communication with Twitter, we’re informing Twitter that we want to sign in the user. The result of this step is a a request token, which is a parameter is the response with the name oauth_token.
- Redirecting the user: In this step, the web host will be shown in the dialog, allowing the user to enter his credentials in the web page. The user will see what permissions the application is asking at this point as well, giving him/her the chance to cancel the sign-in process.
- Converting the request token to an access token: finally, the response needs to be parsed again. This will result in 2 more parameters to be searched from the response string: oauth_token and oauth_token_secret. These are the ones we need to use for subsequent requests to Twitter.
This entire process is explained in much more detail here. The author of that article has also written a library, available on CodePlex: TwitterRT. This library encapsulates the entire authentication process with Twitter. This makes authenticating with Twitter very simple.
Similar to Facebook, building an app that works with Twitter requires us to register as a developer. Go to http://dev.twitter.com and create a new app. An important thing to do when created is changing the settings of the app so that it can send tweets as well.
Create a new project and name it TwitterRTTest. Once created, add a reference to Twitter RT via NuGet. The UI of the app is very simple as shown below.
In the code-behind, we instantiate the TwitterRt class. Next, we pass in the Consumer Key, Consumer Secret and Redirect URL as shown below for my registration (replace these values with the values you’ve received from Twitter of course).
public TwitterRt TwitterRtInstance { get; private set; }
public MainPage()
{
this.InitializeComponent();
TwitterRtInstance =
new TwitterRt("idYuOgrO3mVcQLm4Xep0Q",
"HNFJwrPDze6FxTZ12XGbhOsYm6JzwOghykTCWwQ2XQ",
"http://www.silverlightshow.net");
}
When we want to authenticate, we can do so as follows:
private async void AuthenticationButton_Click_1(object sender, RoutedEventArgs e)
{
await TwitterRtInstance.GainAccessToTwitter();
StatusTextBlock.Text = TwitterRtInstance.Status;
}
Sending the tweet is done using the following code:
private async void TweetButton_Click_1(object sender, RoutedEventArgs e)
{
await TwitterRtInstance.UpdateStatus("Hello From TwitterRt " + DateTime.Now);
StatusTextBlock.Text = TwitterRtInstance.Status;
}
When we run the application now and hit the login button, we get a screen similar to Facebook, where the modal dialog is created, showing the login page for Twitter.
Once authenticated, we can start sending tweets. In the image below, we have done so.
Summary
In this article, we looked at working with public APIs from a Windows 8 app. We looked at probably the 2 most popular ones today: Facebook and Twitter. In the next part of this series, we’ll look at working with Live and the Live SDK.