Well, at last! In this piece we get in to a little code and write something that runs! I'd recommend you read part one, part two and part three before playing with the code in this post because they describe what is happening. By understanding what data and tokens are moving between what services; by realising there are really 3 parts to Windows Live and by understanding a little about the OAuthWRAP profile, you'll have a much better understanding of what these different code elements are doing and therefore be better able to apply your own creativity to the things you'd like to achieve with Messenger Connect.
The user is going to give a website access to some potentially very sensitive information. Recall in figure 5, there is a Windows Live UI element that shows what the site has asked for (in this case to view your contacts and view your profile). The site uses the client scope to communicate what parts of your Windows Live environment it wants access to.
I said it's a tetchy area, because it concerns privacy. For this reason there are 2 main classes of client scope. One is for pretty much any website. The other is for websites that have entered in to a special partnership arrangement with Microsoft, via the management portal (http://manage.dev.live.com). These sites can specify a client scope that gets access to more of the Windows Live information. The process to be permitted access to this scope is for the site to be vetted (by a human being) by Microsoft.
Remember though, the user still has control and still has to grant consent (see figures 4 and 5) for the site to get access to their information. The scope types are:
- Restricted scopes: Available to your application only with approval from Microsoft. These scopes are not available for use by your application until you have approval, for which you will have to email firstname.lastname@example.org, describing which restricted scope you want to access and how it will be used.
If you want to know more about what each type of scope gets you access to, click here. In short with public scopes your application can view the users' activities, photos, contacts and profiles. You can also update their activities and status. With restricted scopes your application can view the users' calendars and get full views of their profiles and contacts. You can also update their contacts and profiles. You can see why Microsoft would want to be assured of your authenticity if you had such power and therefore why some scopes are restricted.
The best way to see how the controls are used is to create a simple site. Bear in mind everything from parts 1, 2 and 3 to understand how the data is moving from the different parties.
Then, down in the body of the page, you'll need to give the page information about the application. This is done with an app tag:
!--><wl:app channel-url="/channel.htm" callback-url="/OAuthWrapCallback.ashx?wl_session_id=<%= Session.SessionID %>" client-id="00000000xxxxxxxx" scope="WL_Contacts.View,WL_Profiles.View, Messenger.SignIn"> </wl:app> !-- code>
- The callback URL is the one mentioned in steps 11 and 12 of figure 3 (in part two) which accepted the verification code and passed over the client secret to the Windows Live Token URL. The callback code itself is actually supplied in an assembly that's part of the Windows Live SDK. We'll return to this later.
- The client ID is the one you registered at manage.dev.live.com. There is a picture of it in figure 2 (in part one).
- The scope is discussed in the client scope section which you've probably just read. In this case you can see the requested scopes fit with the consent screen shown in figure 5 (part two).
!--><wl:signin> </wl:signin> !-- code>
A good control to add now so you can see what Windows Live information you've asked for is the userinfo control.
!--><wl:userinfo> </wl:userinfo> !-- code>
Figure 6: The Sign In control and the User Info control
At this stage, your page will look something like this:
The bold text shows the pieces you'd need to add to a standard naked web form.
When you click the signin control (curiously named "connect"), steps 1 through 8 in figure 3 (part one) are executed (if you attempt the authentication that is). Because the callback URL is not properly configured yet, the process stops at this point. Refer back to steps 1 through 8 of figure 3 (part one) and you'll see how information such as the client ID, the scope and so on are communicated between the different players.
In the next article we'll have a look at a little more of the code that implements steps 9 through 17 in figure 3 (part one).