Wednesday, 19 September 2012

Getting Started with Windows Azure Active Directory

Windows Azure Active Directory is a cloud identity solution from Microsoft which allows us to achieve Single Sign-on for all online Microsoft services such as Windows Azure, Office 365 and Windows Intune. This custom application can also consume Windows Azure AD for single sign-on solutions.

Microsoft announced Windows Azure Active Directory as a standalone service last week in preview. In this post, I am planning to walkthrough for creating a subscription in preview, creating users and consume it in an MVC application.

Creating Windows Azure AD Subscription
Note: This post intended to provide details about setting up Windows AD for achieving single sign-on in Web Applications. This post does not shown syncing on-premise Active Directory feature.

Step 1: Access the url The browser will re-direct you to the Windows Azure AD service sign-up screen.
Step 2: Once sign-up is completed successfully, there will be a mail to the mentioned Email address. Activate the subscription with the link provided in the mail.

Step 3: Access the Windows Azure AD from the link Login with the user id provided in the screen.

Step 4: When login is successful, switch to domains screen and verify the added domain.

By default, Microsoft provides a domain with the preview when signing up. In preview, we have limited options as of now.

Step 5: Switch to Users & groups screen and add some user addition to the logged in user.

We have many more functionality with this portal. But as of now, I am planning to take the current domain with some users for achieving single sign-on in a Web Application.

Creating an empty MVC application

Step 1: Create an empty MVC application in Visual Studio with project name as WAADTest. (I am creating MVC application with Basic MVC 4 template)
Step 2: Add control by right click the Control folder by selecting Add -> Controler menu. Name the controller as HomeController.
Step 3: Add a folder Home in the View folder by right click the View and selecting New Folder menu.
Step 4: Add a new view under the Home folder and name it as index by right click the Home folder and select View menu.
Step 5: Add the following Index method in the HomeController created in Step 2.
public ActionResult Index()
    return View();
Step 6: The application must run under IIS for using Windows Azure AD capabilities. So open the project properties (double click the Properties folder of the project) and select the Web tab. Select the Use Local IIS Web server under Servers section.Verify the url and press Create Virtual Directory. The Visual Studio will create a virtual directory and link to this project.
Step 7: Run the application and verify runs without error.
Note: Ignore the certificate error as this is for testing. Note the url of the application which will be used in next section.

Creating Service Principal

Service Principal is used to represent the application that access Windows Azure AD. So before consuming WAAD, we must create Service Principal with the details of the application which is consuming the directory.

For creating Service Principal, we need to run PowerShell commands by connecting the Microsoft online services. Below are the steps for preparing the system to run PowerShell commands.

Note: The Microsoft Online Services Module for PowerShell can be installed on Windows 7, Windows Server 2008 R2. It will be extended to new operating systems Windows 8, Windows Server 2012 in future. So consider installing the below installations on Windows 7 or Windows Server 2008 R2.

Step 1: Install the Windows Azure PowerShell using the below url

It will trigger Microsoft Web Platform Installer to install Windows Azure PowerShell cmdlets.

Now you can Import Windows Azure module and connect a subscription and work with that using PowerShell command. For more information about how to import and use, please refer the below link –

Step 2: To work with Windows Azure Active Directory (and Office 365), we need to install two PowerShell Modules i.e., Microsoft Online Services Sign-in Assistant v7.0 + and Microsoft Online Services Module for PowerShell.

So first install Microsoft Online Services Sign-in Assistant. Below is the link for downloading the setup file

Step 3: Install Microsoft Online Services Module for PowerShell. Below is the link for downloading the setup file.
or from direct link

Once the installations are completed successfully, you can start running the PowerShell commands for creating Service Principal and adding redirected urls.

Note: To run the PowerShell commands, you can use command command line window or PowerShell IDE. You can also install PowerGUI Script Editor for running the commands. I am planning to use PowerGUI Script Editor, as I like some nice feature in it.

Creating Service Principal for an application

To achieve Single Sign-in feature with Windows Azure AD, we required to create Service Principal for that application and add the application url into the Service principal. So we are going to create Service Principal by connecting Windows Azure AD.

Step 1: Before creating Service Principal, we need to create a GUID for the Service Principal for making it as unique (i.e., for referring that Service Principal).

Run the below command for getting a Guid and note somewhere.
I got the Guid as 9452e0e4-3f9e-4ae1-98f2-3b7923cd6d60.

Step 2: We need to import two PowerShell Modules for doing any operation with Windows Azure AD (or Microsoft Online Services such as Office 365).
Import-Module MsOnline
Import-Module MSOnlineExtended
Note: These Modules will be available only if the Microsoft Online Services Module for PowerShell installation successful.

Step 3: To connect to a particular Windows Azure tenant (or Office 365 tenant) from PowerShell for creating Service Principal, we need an administrator user. So get an administrator user from the tenant you want to achieve SSO and run the below command.
#Connect-MsolService -Credential $cred
This command will prompt a window for requesting login credentials. I am logging in with my id as below.
If login successful, you are connected to that mentioned tenant and can do related operation on it.

Step 4: Run the below command for creating Service Principal.
New-MsolServicePrincipal -ServicePrincipalNames @("WaadTest/localhost") -AppPrincipalId "9452e0e4-3f9e-4ae1-98f2-3b7923cd6d60" -DisplayName "Windows Azure AD Test Site" -Type Symmetric -Usage Verify -StartDate "08/19/2012" -EndDate "08/18/2013"
Here the WaadTest/localhost is the Service Principal Name and AppPrincipalId as the Guid which got in Step 2. You can change the start date and end date as you required.

Once the command ran, it will provide information about the Service Principal created in the console. You can keep this information for reference.

Note: In sometime, powershell will raise error "Get-MsolServicePrincipal : The term 'Get-MsolServicePrincipal' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again. when using any MSOnlineExtended powershell commands such as Get-MsolServicePrincipal, New-MsolServicePrincipal. In such situation, required to import the MSOnlineExtended module with Force as below.
Import-Module MSOnlineExtended –Force

Step 5: Now we have created the Service Principal, but we need to say the url of our application to Service Principal for replying back to the application once the authentication successful.

Run the below command with the application url.
$replyUrl = New-MsolServicePrincipalAddresses –Address " https://localhost/WaadTest/"
Set-MsolServicePrincipal –AppPrincipalId "9452e0e4-3f9e-4ae1-98f2-3b7923cd6d60" –Addresses $replyUrl
Step 6: You can verify the created Service Principal using the following command.
Get-MsolServicePrincipal -AppPrincipalId "9452e0e4-3f9e-4ae1-98f2-3b7923cd6d60"
Note: Here the AppPrincipalId refers the Guid.

Step 7: We also need the tenant Id of the Windows Azure AD for the SSO configuration. So to get the tenant Id, run the following command.
Now the Service Principal created successfully. We can configure our application to consume the directory and implement Single Sign On.

Configuring the Application for Waad SSO

Below steps can be done in any system which had Visual Studio 2010/2012 and WIF SDK installed. These steps are not required to be done in Windows 7 / Windows Server 2008 R2 system as we have done in previous section. I am using Windows Vista with Visual Studio 2010 for the following steps.

Note: Make sure WIF and WIF SDK installed in the system and Add STS reference enabled in the menu when right click the application. Sometimes the Add STS reference menu won’t be enabled even the WIF SDK installed. To enable the menu, open the Visual Studio Command Prompt and navigate to the Common\IDE folder of Visual Studio installation path. For 32 bit system the path will be C:\Program Files\Microsoft Visual Studio 10.0\Common7\IDE.

Run the following command and restart the Visual Studio.
devenv /ResetAddin Microsoft.IdentityModel.Tools.VS.VSAddin.FederationAddin
Step 1: Switch to the project. Right click the project and select Add STS reference menu. Visual Studio will open Federation Utility window.

Step 2: Fill the application url which was set in Project properties (Creating an empty MVC application -> Step) and press Next.
Step 3: In the Security Token Service Screen select the Use an existing STS option and fill the STS WS-Federation metadata as below
Note: Replace the realm part to your tenant name. For Ex: to
Press Next.

Step 4: Select Disable certificate chain validation in the STS signing certificate chain validation error window and press Next.
Step 5: Select No encryption in the Security token encryption window and press Next.
Step 6: Press Next in Offered Claims window.
Step 7: Verify the summary in the Summary window and press Finish.
Visual Studio will configure required settings for enabling SSO with Windows Azure AD.
Note: As this example is a POC, I am not enabling the certificate validation and token encryption.

Step 8: If you run the project, you may be getting the following error. We still need some more configurations with the application Web.Config file
Step 9: Change the URL of the audienceuris value in spn format.

The spn format must be in AppPrincipalId@Tenant Id. We already got both the values in previous section I.e., the AppPrincipalId is the Guid we created in Step 1 and the Tenant Id will be the value we got in Step 7 of Creating Service Principal for an application.

So the spn value for my POC is,

Change the spn realm to audienceurls section under microsoft.identityModel\service node in Web.Config.
  <add value="spn:9452e0e4-3f9e-4ae1-98f2-3b7923cd6d60@9d4a6f28-b577-4000-8000-d40b8dcd2ea7" />
Step 9: Change realm attribute with the spn realm and add reply attribute with the application url in the wsFederation node as below.
  <wsFederation passiveRedirectEnabled="true" 
                requireHttps="false" />
  <cookieHandler requireSsl="false" />
Step 10: Now run the application and verify the output. Once the certification validation error confirmation done, it will re-direct to the for login to the application.

Step 11: Login with any of the user of your Waad domain created.
Step 12: The browser may provide some error as below.
This is because we required to add httpRuntime validation mode in configuration. So open the Web.Config and add below node under System.Web section.
<httpruntime requestvalidationmode="2.0">
Step 13: If you run the project now, you will be re directed to the login page. When login successful, it will again redirected back to the application home page.
Step 13: The home page does not show the claims got from the Windows Azure AD. To display the claims, change the index.cshtml page as below.
    Layout = null;

<!DOCTYPE html>

    <meta name="viewport" content="width=device-width" />
       @if (User.Identity.IsAuthenticated)
            @foreach (string claim in ((Microsoft.IdentityModel.Claims.IClaimsIdentity)this.User.Identity).Claims.Select(c => c.ClaimType + " : " + c.Value))
Step 14: Now run the application and login with any user of Windows Azure AD. When login successful,
Step 15: When login with user credential which added with other domain, you will be getting the below error.
Now we have enabled Single Sign In capability with our application. This was we can consume the Windows Azure AD for many other Single Sign In requirements.

This post provides a startup for Windows Azure AD and configuring Single Sign-On. In future post, I will explain exploring more on Windows Azure AD.

0 Responses to “Getting Started with Windows Azure Active Directory”

Post a Comment