hen developing with Windows Live services, you open your application to a whole new world of software integration. In this fascinating realm of mash-up mania, developers can find tools for adding maps, searches, video, chats, and even social networking services directly into their applications and ultimately right into their users’ browsers. The benefits of adding services like Virtual Earth and Silverlight Streaming are obvious?you can create dazzling content and facilitating rich user experiences. Yet services like these are still limited to specific contexts within your program. They are perfectly wonderful for beefing up the user experience in web sites, but wouldn’t it be great if the folks at Microsoft provided a service that helps you administer user accounts and customize services around your web site? Well indeed they have, and its name is Windows Live Admin Center.

Windows Live Admin Center (formerly known as Custom Domains) is a service provided by Microsoft that allows users to create domain-specific Live ID accounts. Up until this point you’ve likely spent a lot of time reading about Live services that work within your web sites or web-enabled applications. Admin Center marks a subtle shift from these services, representing one of the few features of Windows Live that works around your application. On the surface its purpose is simple: allow users to create Live ID usernames within your site’s URL. For example, if you are the owner of a domain named coragi.com, you could register that domain name with Windows Live Admin Center and, through it, create Live ID accounts with names such as [email protected] or [email protected]. After the domain is registered, webmasters have the ability to administer these accounts directly, adding names, removing users, and performing basic account maintenance as they see fit.

I know what you’re thinking: So what? Most webmasters with only a moderate amount of experience know how to create accounts like this on their own. After all, most hosting services already provide the administrative features and mail services needed to create an almost limitless list of domain-specific accounts. Who needs yet another service to do this for you? At first, I thought the same thing. However I soon learned that the power behind Windows Live Admin Center lies not in the simple creation of accounts, but rather in the power that drives Windows Live ID and in the power of service integration and site federation.

Consider what a Live ID really is. It is a key that identifies a user to literally thousands of Live-powered web applications. Since Windows Live ID supports a single sign-on model, each Live ID account is not only unique, but recognizable across all Live-powered applications. Likewise, a Live ID account is a means of entry to other Live services. A single Live ID account comes with all of the Windows Live features, including a page on Live Spaces, an account on Live Expo, search macros, personalized alerts, a chat account, and lots of other tools and features of Live that compliment your online content.

Still, Live ID has its limitations. If your web site requires users to have a Live ID to access your site the accounts aren’t entirely user friendly. They have non-descriptive domain suffixes such as @hotmail.com or @live.com that prevent users from identifying with your application. Sure, users have access to free email, but of course the email is branded as Hotmail, again preventing users from identifying with your service. And of course, there is the not-too-subtle separation of services that keeps a webmaster at arm’s length from account maintenance. Even though you might be consuming Live ID and, with it, allowing people to log into your application, you have no ability to administer the accounts themselves.

Here is where Windows Live Admin Center shines. Admin Center is a service that bridges those otherwise awkward disconnects between your application and Windows Live, resulting in a powerful compromise that facilitates customization while allowing users to take full advantage of the Live ID model. Instead of accounts with hotmail.com names, each corresponds to whichever domain name you choose to register. Instead of hosting your own mail services and authentication servers, Microsoft does it all for you. What’s more, Live IDs created using Admin Center aren’t subject to many of the expirations and maintenance rules that apply to a normal Live ID account. The accounts you create are yours to manage and control.

Online Registration and Account Administration
The best way to familiarize oneself with Admin Center is to jump right in and register an account. First time users should begin by clicking the “Get started” button located towards the bottom of the page. This begins the wizard-like application that helps guide users through the setup process.

	?
Figure 1. Getting Started: Enter your Domain Name or purchase a new one.

The first thing you’ll need to have to begin using Admin Center is your own domain name. Thus, the first page of the wizard allows you to either enter an existing domain name (that you own) or select an option for purchasing a new one (see Figure 1). Managing a domain name requires some understanding of registrars and general web concepts and falls outside of the scope of this article. Microsoft has partnered with a handful of public registrars, such as Melbourne IT and Register.com; however, developers should feel free to use whatever registration service they prefer. If you click the link labeled “I need to purchase a domain,” you’ll be given a choice of roughly four registration services from which to choose (offered in English only, other languages will not have this option), and then the Admin Center registration process stops. Inevitably you’ll be forwarded back to this initial page with a valid domain name to continue.

In this example I have purchased the domain name “coragi.com,” so I will enter that name into the text field at the top of the page and click “Continue.” Notice that I did not change the default mail setting: “Set up Windows Live Hotmail for my domain.” This newer option that comes with later versions of Admin Center allows advanced webmasters to forego the automatic mail service that accompanies an Admin Center account. Since the email that comes with each account is a popular feature, leave that setting alone for now. The next few pages require users to sign in with a valid Windows Live ID and to agree to the terms of use. The Live ID you choose to associate with this account will be the same account you’ll use when administering your accounts through the API. Remember it, because you’ll need it when sampling the API. Be sure to read through each of the terms, and then click the “I Agree” button to continue.

	?
Figure 2. Administration Page: Here’s the Admin Center’s online administration page.

If this is the very first time you are logging in you’ll likely see some warning messages indicating that your account status is “Pending DNS Configuration.” You’ll need to go into your domain host’s administration page (or wherever you keep your DNS records) and add an MX DNS entry pointing to the MX address listed with the status message. Once you’ve done that, your Admin Center account should look like Figure 2. Headings such as “Administrator Status” and “Mail” indicate the Admin Hotmail account status, and whether there is a valid DNS entry for your Hotmail service.

In the upper left-hand side of the page you’ll find a small navigation menu through which you can access some features of your account. Create a new member account by clicking the “Member Accounts” link, and then clicking the “+ADD” button at the top of the page. Enter the requested information. Remember that your domain name gets appended to each name you enter into the “Account Name” field. For example, adding the name “Mike” into your Add-Members page creates an account with a user name of [email protected]. Each account you create is a valid Live ID account. You can experiment with them by going to other Windows Live sites such as Spaces.live.com and log in using the new account name.

Adding and removing Live IDs from your domains is just one of a few cool features of Admin Center. If you’re looking to take advantage of other services in the Windows Live family but you don’t want to give up your own domain URLs, take a gander at the Custom Addresses section. This tool lets you map domain friendly CNAME entries and sub-domains to other Live services such as Hotmail, Live Spaces, and Live Maps. For example, say you want users to be able to come to coragi.com and click a link that shows a map of Philadelphia with a pushpin over 1500 Market Street. You want the link to read “maps.coragi.com,” because that’s simple to remember?but you want the user to be taken to Live Maps directly. With Admin Center, it’s easy! Simply click the Custom Addresses link in the navigation menu, select “maps” from the drop-down list, and then click the Add button.

In the subsequent pop-up window, enter the CNAME entry that you would like your site to use (in this case “maps”), and then enter the address as you would have typed it into maps.live.com. You’ll need to go into the host site or where you administer DNS entries and add a CNAME entry for maps.coragi.com (which should point to go.domains.live.com). Now when you enter maps.coragi.com into a browser, a Windows Live map appears with the focus directly over Center City, Philadelphia, as shown in Figure 3. You can use this feature to create domain-friendly URLs that point to individual Spaces pages, Search Macros, collective email accounts, and more.

	?
Figure 3. Integrating Live Maps: A Custom Address pointing to a specific location on maps.live.com.

One more feature worth mentioning is the co-branding link. Admin Center is all about integrating your site’s content seamlessly with the various services and tools inherent to the Windows Live family. By utilizing Admin Center’s email services, you provide your users with an almost limitless amount of mail space while never having to worry about hosting or email account management. Of course, it might help if the email page users logged into bore some relationship to your site? When you click the co-branding link, that’s precisely what you’ll get. Most basic users will be able to see a link to customize the header. This option allows you to upload a small web site image or logo that will be visible on the headers of all co-brandable pages in Windows Live. As Microsoft expands this capability, you’ll be able to subtly layer in other elements of your web site’s look and feel to maintain the semblance of a single-site user experience.

There are other customizable features available through Admin Center. Some of these features allow you to open your membership model to users interested in creating their own Live IDs (see the sidebar “Open Membership“). Other features may be available only to certain types of Admin Center memberships. Everything I have covered so far pertains to those features available to any web site interested in federating with Windows Live Services; however, other offers that cater to different interest groups may provide different or additional features. Live@edu is one such special offer, allowing schools to outsource their email and online services for students and alumni. Interested parties should visit http://www.liveatedu.com. Other offer types such as Live@net allow network operators to offer enhanced email services to their broadband subscribers. In fact, the web site you just registered, coragi.com, technically falls into the offer known as CommunityBuilder. The point is that Admin Center comes in several different flavors, some of which might offer more features and tools you’ll want to explore. You can find more information on special interest offers here.

Using the Admin Center SDK
The online administrative site that accompanies your account is nice to have, but falls short of delivering the automation you really need to integrate Admin Center accounts into your web site. After all, if you want users to register with your web site and automatically receive a sleek, new Live ID with your domain name in it, you need a way of adding users and managing accounts within your code. For this, you’ll need to access the Admin Center SDK, which comes with API documentation and samples.

Because the scope of this article is necessarily limited, refer to the SDK documentation for the full definitions of all available APIs. The Admin Center API exposes a single web service endpoint containing a flush list of public methods available for all sorts of member service administration. You can use some methods, such as CreateMember and GetMemberNameState, for direct integration with your registration process. Other methods, such as GetMemberCount and GetDomainInfo, are available for more comprehensive administration of your domains and accounts. The trick to really understanding Admin Center lies in knowing which method to use, and when.

Consider a typical registration scenario. You’ve got a great new web site that delivers triathlon information and lets competitors enter their personal stats. Each competitor needs to register with your web site in order to access their personal stats and enter in data from each of their races. You’d like to furnish users with Live IDs so that they can also chat with one another, create blogs and connect them with their Spaces accounts, and maybe even post some flyers on Live Expo. You’ve already got all of the pieces you need to integrate Live ID into your authentication process, but you need to be able to automatically create Admin Center user names each time the user clicks that “register’ button on your site. So the registration process really requires three distinct steps in order to integrate:

• Create an administrative session for authorized management of accounts.
• Check to see if an account name already exists.
• If available, add a new account to your Admin Center domain and activate the Live ID.

That’s a good start for this article. You’ll dig in by setting up a small sample application that demonstrates these tasks. This example uses a C# console application created in Visual Studio .NET 2008. Of course in the real world you’ll more likely be using server code in an ASP.NET application; however, a console piece should prove sufficient for this article.

Setting up the Visual Studio .NET Console Application
You’ll need to first create a Visual Studio .NET Console Application project and create a reference to the Admin Center web service endpoint.

1. Open Visual Studio .NET 2008, and select the New Project option from the File menu.

	?
Figure 4. Create Application: Select the C# console application in Visual Studio .NET 2008.

2. Find the option for creating a C# Console Application and enter a project name of MyAdminCenterSample, as shown in Figure 4. For the purposes of simplicity, leave all other default settings alone.
3. Once loaded, add a web reference to your application by right-clicking the References link in the Solution Explorer and selecting “Add Web Reference” from the pop-up menu.
4. Enter the following URL in the Web Reference URL field:

   https://domains.live.com/service/managedomain2.asmx.

5. Then enter “AdminCenterAPI” as the web reference name. Your screen should look something like Figure 5.

	?
Figure 5. Add Web Reference: The figure shows the process of adding a web reference to the Admin Center web service endpoint.

Author’s Note: The Admin Center service endpoint uses SSL encryption to ensure that the user data sent to the service cannot be read during transport. Click OK in response to the digital certificate pop-up to continue loading the service endpoint.

6. Because you will be making calls to web classes not immediately available within the default application’s scope, add the following using statements to the top of the Program.cs page:

   using System.IO;   using System.Net;

That should be enough to begin. Bear in mind that everything you will be doing from here requires the use of a fully registered, active Admin Center account. While following along, assume that you can replace any calls made to coragi.com or its supporting elements with your own account names and elements.

Creating an Administrative Session
Before you can create user accounts and view domain information, you’ll need to create a valid administrative session. This works similarly to the way you might log into a secure administrative site, only instead of creating a valid session cookie, you’ll be creating an authorized ticket. This process uses three API methods: GetLoginUrl, GetLoginDataTemplate, and VerifyAuthData. The GetLoginUrl call simply returns the specific web address to which your application needs to post in order to create an authorized ticket. The address might change over time and can be different for each application used; however, by calling this method specifically, your code is abstracted from any unpredictable address changes. GetLoginDataTemplate returns the string used specifically by the ticket-generating URL for passing in your administrating Live ID account name and its corresponding password. Note that the format for this string is quite specific. You must make a call to the GetLoginDataTemplate method each time you authenticate to be sure you’re conforming to the expected standards. Once the template is obtained, you’ll need to replace the “Name” and “Password” placeholders with your own credentials. You’ll then pass this new string to the URL provided in the GetLoginUrl method using standard C# web classes to receive your valid session ticket. You then verify that no errors occurred by passing the ticket to the VerifyAuthData method and, if valid, save the valid ticket and associate it with your web reference.

This may seem like a lot of work at first, but it becomes a no-brainer once you get used to it. In the Program.cs file, add the following code directly below your static void Main function:

   private static string CreateAuthTicket()   {   }

You’ll call this function from the Main method directly, isolating all of the requisite tasks for generating the ticket from the Main function’s code.

You’ll need a class-wide reference to the Admin Center Web reference, so go ahead and add the following declaration directly above the static void Main method:

   static AdminCenterAPI.ManageDomain2 srvc;

Now you’ll need to add the code from Listing 1 to the newly created CreateAuthTicket method.

If you follow the code you should find that each step reflects the process I just described. You first create a web object reference named srvc that gives access to the Admin Center service endpoint. You then get the login URL and store it in a local string variable and get the login template as well. The code attempts to replace the template placeholders with your own account name and password, but you’ll need to enter your own credentials where required. You then post the data to the provided URL and verify that it is valid. If valid, you create an instance of the ManageDomain2Authorization class, which is used by Admin Center to hold the authenticated ticket and deliver it to the web reference endpoint. You set the appropriate type (see Admin Center documentation about authentication types) and set the authentication value equal to your new ticket. Finally, you set the web reference’s ManageDomain2AuthorizationValue property equal to the instance of ManageDomain2Authorization, which contains the valid ticket.

If you try to compile this code as is, you’ll get some errors. That’s because you haven’t yet implemented the PostwebData method. This is a standard C# method that accepts a URL and a string template, posts the template to the URL, and returns whatever might come back from said post. Under the CreateAuthTicket method, add the C# code from Listing 2.

Go ahead and compile the code now and everything should come through fine. You’re now ready to start creating your user accounts.

Adding New User Accounts
Since you’re creating a Console Application, it might be best to provision some simple user I/O. Add Listing 3 to the static void Main method.

Again, this seems like a lot of code, but a closer look reveals this sample’s simplicity. The first few lines write out a welcome message, then waits for users to click the Enter key to begin. The code then obtains the authorization ticket using the method you built in the last section. Next, the code gives the user a small menu of tasks from which to choose and sets up an empty switch block to pass focus to whichever function corresponds to the user’s choice. The menu selection option is placed within a large while loop, allowing the user to come back and select other menu options once a previous selection’s task has been completed. This pattern allows you to create individual methods that wrap your sample API calls without overlapping your application’s control code.

Thinking back to your registration scenario, you’ll want to tackle the “Add a New User” option first. This method will require the use of two Admin Center API methods: GetMemberNameState and CreateMember. As discussed previously, a typical scenario demands that a user enters a desired name, which the system first checks for availability. If the name is not available, the user is appropriately told so, and then they are given the opportunity to try a different name. Upon finding an available user name, the system can garner some additional account info from the user and create the new account. Thus, the GetMemberNameState method will be invoked each time a user enters a new name and the CreateMember method is called only when an available name has been determined.

Replace the following code in the main switch block for case #1:

   case "1":      AddNewUser();      break;

Add Listing 4 to your class.

Similar to the code in the static void Main function, you begin with some simple text in the console followed by the beginning of a while loop. You use the loop to take the user back to the initial steps in the event that the user provided an unavailable name. Note that all of the code within the loop has been enclosed with a Try block. There are a number of different errors that can be thrown by Microsoft when attempting to make an API call. Since there is no simple way to handle all of them gracefully, you simply catch any exception when thrown, print the contents of its message to the command line, and then go back to the main menu.

You next present the user with the option of entering a user name they would like to register. They must enter the name as the fully qualified domain name. For example, a user wanting to register the name “Jake” will need to enter Jake@[your domain]. Naturally you should feel free to tinker with the sample code to append the name with your URL as you see fit. Once entered, the system makes a call to GetMemberNameState, passing in the user’s desired name to check for its availability. The return value from this method is not a Boolean as one might expect. Rather, it is an enumeration with a value corresponding to the name’s specific state within Windows Live. Although this code simply checks for availability, users should keep in mind that the GetMemberNameState function can actually return one of five possible values:

• Available.
• Blocked: The member name contains a blocked word.
• In Use: The member name is already registered with Windows Live.
• Hotmail Recycle: The member name was previously used as a Passport account with an associated Hotmail inbox and the account has not been recycled by the Hotmail back end.
• Existing EASI Account: The member name is an unmanaged EASI account and is registered with Windows Live. You can evict this account if you want to create a new account with this member name (this will force the existing EASI member to rename this account on next login).

If the desired username status is anything but Available, the application displays a brief error message and allows the user to try to enter another name. When the user provides an available name, the application prompts the user to provide some optional account details to be saved with the new account name, such as first name, last name, an account password, and whether the user should be forced to change the account password upon their first login. When the user provides the data, the application passes it all to the CreateMember method, and then takes the user back to the main menu.

As you can see, most of the code used in this example simply supports the input and makes it easy to step through. At the heart of the code lie iterative calls to the GetMemberNameState method and a single call to the CreateMember method. Thanks in part to the web reference framework provided by Visual Studio .NET 2008 (which created a proxy class and all of the plumbing needed to invoke the API calls), handling new accounts is as simple as entering a name and passing it to a function.

The rest of the code sample demonstrates other Admin Center API calls, prompting users for various bits of information and passing that information to other web methods. The “View Member List” option maps to a static function that makes a call to EnumMembers. The “Reset Member Password” maps to another function that calls ResetMemberPassword. Other mappings are similar. The samples are limited for the purpose of simplicity; however, readers should feel free to use this model to plug in functions that sample other methods. If you take a few minutes to explore the SDK documentation, you’ll no doubt notice that a good number of the API methods are listed as “Restricted” and require Microsoft approval to use. Remember when I mentioned that Admin Center may provide extra features for different offer programs? These restricted functions were created specifically for these membership types, so most users won’t be able to use them out of the box. Still, there are plenty of unrestricted methods available for you to use, with more on the way. Listing 5 contains the complete sample code.

A Word on Integration
The combination of a Live ID tailored to your URL and the control of a manageable login service makes Admin Center a powerful tool in the Windows Live arsenal. However, wielding that power requires some understanding of Live ID, and to a small degree, something referred to as Personalization.

	?
Figure 6. User Authentication Flow: Here’s the data flow when authenticating with Live ID.

Personalization refers to the act of identifying users when they log in, and delivering user-specific data or a change in the site experience based on that identification. If you are handling Windows Live authentication internally (not using Windows Live ID for authentication), personalization is a non-issue, because you already have the data you need upon authentication. However, a single sign-on model such as Live ID works differently, abstracting the consuming web site from the user’s name and password. Instead of users passing their user name and password directly to a web site, their credentials are forwarded to the Live ID server. The server compares the data passed in with a separate Live ID account and, if valid, passes various other bits of data back to the consuming site. Figure 6 depicts this process graphically. The information sent back to your site is a combination of enciphered Live ID data and context data fed back through from the original sign-in page.

Without delving too deeply into the complexities of Live ID, it may help to familiarize yourself with the general steps a site should take to personalize an account. The process in Figure 6 depicts a login scenario with an existing Live ID account. One of the critical pieces of data received by the consuming web site from the Live ID servers when the user has been authenticated is a unique, pair-wise identifier, matching a user account with the specific website. This unique user ID (referred to here as the “UUID” from now on) is exclusive to a single user and a website; it never changes for the receiving site. No matter how many times an account’s user name, email address, or password might change, the UUID stays the same for that website. However, the UUID contains no identifying characteristics; it is impossible to tell from the UUID just who is logging in. Therefore, it stands to reason that the consuming site will need to store a person’s credentials and their corresponding UUID in a local data store to recognize a valid incoming user and show them personalized information. Getting to the point, all this leads to a specific registration scenario, which ameliorates this disconnected login process.

Most web sites offer a registration page for creating a new account. There, users can provide their personal information such as name, address, phone number, account credentials, likes, dislikes, favorite movies and so on. A web site using Live ID would do the same, storing the personal data locally and forwarding the user to the Live ID sign-in page. Using a context-specific variable in the Live ID SDK, the consuming web site would recognize that the UUID coming back from this user corresponds to the personal data it just saved.

	?
Figure 7. New Registration: Creating a new registration with Live ID is somewhat more complex.

The UUID is added to the personal account, allowing the system to remember the user by UUID each time they come back to their site. See Figure 7 for details.

Personalization using Admin Center works almost exactly the same way, with a few extra steps in the beginning. The consuming site still needs to create an account and wait for the UUID; however, the registration page can also make calls to the Admin Center API to check for an existing user name and create new accounts. Conceptually the process is the same as the C# example you saw earlier. The end user first needs to choose a user name. The system will check to see if that name is taken and, if not, create the Live ID account. The system will still need to remember that the user is logging in for the first time, because the Admin Center API does not provide a method for extracting the UUID from a newly created member.

	?
Figure 8. Registration with Admin Center SDK: Here’s the process that happens when you create a new registration with Live ID using the Admin Center SDK.

Figure 8 shows the new registration process using Admin Center. At this point, the web site’s login is complete. New users can create new accounts that look and feel like a local domain account, but that are actually fully functional Live IDs. What’s more, the Admin Center API helped to make the process seamless, abstracting the user from the many different steps required to create the new member’s account.

By this time, you should start to see some of the power behind Admin Center. There are far more features built into the API than this article covers, and you can do much more with the complete SDK than covered here as well. Remember that Admin Center is, at heart, a tool for web site federation. It’s the glue between you and Microsoft that binds the features exposed by Windows Live with the unique experience of your own web site. For more information about Admin Center, Windows Live ID, Personalization, and other Windows Live features, refer to my book, Professional Windows Live Programming.