Exercise 1: Use Access Control Service for Accepting Users from Multiple Identity Providers

In the first exercise you will familiarize with ACS’ basic settings and terminology. Your task is to secure access to a newly created ASP.NET Web site. The Web site will accept users from Google, Yahoo! and Windows Live ID. As you will see in a minute, ACS makes it real easy.

Task 1 – Creating the Initial Solution

  1. Open Microsoft Visual Studio 2010 with administrator privileges. From Start | All Programs | Microsoft Visual Studio 2010, right-click Microsoft Visual Studio 2010 and select Run as administrator.
  2. Open the WebSiteACS.sln empty solution file located inside the Source\Ex01-AcceptUsersFromMultipleIPs\Begin folder of this Lab.
  3. Create a new empty website. To do this, right-click the WebSiteACS solution and select Add | New Web Site, select Visual C# in Installed Templates section and then click ASP.NET Web Site. Change the Web location field to use HTTP and set the value with https://localhost/WebSiteACS and click OK.

    Figure 2

    Add New Web Site

  4. Go to Solution Explorer and delete the following folders from the web site:

    • Account
    • Scripts

    And the following files:

    • About.aspx
    • Global.asax

    Figure 3

    Solution Explorer

  5. Open Site.master file and remove the DIV with class named “loginDisplay” and the NavigationMenu menu control.

    ASP.NET

    ... <div class="page"> <div class="header"> <div class="title"> <h1> My ASP.NET Application </h1> </div> <div class="loginDisplay"> <asp:LoginView ID="HeadLoginView" runat="server" EnableViewState="false"> <AnonymousTemplate> [ <a href="~/Account/Login.aspx" ID="HeadLoginStatus" runat="server">Log In</a> ] </AnonymousTemplate> <LoggedInTemplate> Welcome <span class="bold"><asp:LoginName ID="HeadLoginName" runat="server" /></span>! [ <asp:LoginStatus ID="HeadLoginStatus" runat="server" LogoutAction="Redirect" LogoutText="Log Out" LogoutPageUrl="~/"/> ] </LoggedInTemplate> </asp:LoginView> </div> <div class="clear hideSkiplink"> <asp:Menu ID="NavigationMenu" runat="server" CssClass="menu" EnableViewState="false" IncludeStyleBlock="false" Orientation="Horizontal"> <Items> <asp:MenuItem NavigateUrl="~/Default.aspx" Text="Home"/> <asp:MenuItem NavigateUrl="~/About.aspx" Text="About"/> </Items> </asp:Menu> </div> </div> ...

    The code should look like the code bellow:

    ASP.NET

    ... <div class="page"> <div class="header"> <div class="title"> <h1> My ASP.NET Application </h1> </div> <div class="clear hideSkiplink"> </div> </div> ...

  6. Open Web.config file and remove the following sections:

    • connectionStrings
    • system.web/authentication
    • system.web/membership
    • system.web/profile
    • system.web/roleManager

    The Web.config should look like the code bellow.

    XML

    <?xml version="1.0"?> <!-- For more information on how to configure your ASP.NET application, please visit http://go.microsoft.com/fwlink/?LinkId=169433 --> <configuration> <system.web> <compilation debug="false" targetFramework="4.0" /> </system.web> <system.webServer> <modules runAllManagedModulesForAllRequests="true"/> </system.webServer> </configuration>

    Note:
    All this cleanup is not strictly necessary, but it helps to keep things simple and highlight the code that will be required for integrating with ACS.

  7. Press F5 to run the Web site and ensure that it works as expected. If an alert about “Debugging Not Enabled” appears, select “Modify the Web.config file to enable debugging” and click OK.

    Figure 4

    “Debugging Not Enabled” Alert

    Figure 5

    Running Application

  8. The Web site is, as expected, without any access control mechanism. You can close the browser.

Task 2 – Signing-up for Windows Azure AppFabric Access Control Service and Creating the Service Namespace

You are now going to subscribe to ACS.

  1. Navigate to https://windows.azure.com/. You will be prompted for your Windows Live ID credentials if you are not already signed in.
  2. Click on the Service Bus, Access Control & Caching button on the lower left corner. You will land on the page below

    Figure 6

    Portal Access Control Service

  3. Select the Service Bus, Access Control & Caching item on the Navigation menu
  4. Now you will add a new Access Control Service Namespace. An Access Control Service Namespace is the unique component of the addresses at which all your endpoints on the Access Control Service will be available. To do this, ensure the AppFabric root element is selected on the left pane and click the New Namespace button on the top left corner.

    Figure 7

    Add Namespace

  5. The portal displays a dialog. Type in a name for your Namespace, choose your Country/Region and a Connection Pack Size, and click the Create Namespace button. Make sure to validate the availability of the name first. Service names must be globally unique as they are in the cloud and accessible by whomever you decide to grant access.

    Figure 8

    Creating New Service Namespace

  6. Please be patient while your service is activated. It can take a few minutes while all the necessary resources are provisioned.

    Figure 9

    Active Service Namespace

Task 3 – Configuring the Allowed Identity Providers, the Relying Party and the Signing Certificate

  1. With the Namespace selected, click the Access Control Service – Manage button on the top toolbar. Make sure that appservices.azure.com is allowed to show popups in your browser.

    Figure 10

    Click the Access Control Service – Manage button

  2. This launches (in another browser window or tab) the Access Control Service Management Portal, shown in the figure below.

    Figure 11

    Access Control Service Management Portal

  3. The Management Portal, and specifically the left-hand navigation menu, offers you a global view of all the settings you can change in ACS. In the typical application development flow, such as the one you are creating in this exercise, there is a natural order you can follow for providing ACS with the information it needs to set up authentication for you. Click the Identity Providers link in the Trust Relationships section of the menu. The main area of the management portal will display a page which helps you to manage the identity providers from where your application users will come from.

    Figure 12

    Identity Providers

  4. Click the Add link above the Identity Providers table, choose the identity providers you want to add in your Access Control Service namespace and click Next. Windows Live ID is there by default. For this exercise please pick Google and Yahoo! as well.

    Figure 13

    Adding an Identity Provider

  5. Leave the default settings and click Save.

    Figure 14

    The Yahoo Identity Provider configuration page

  6. You can follow the same steps to add Google as an Identity Provider. You’ll end up with the Identity Providers list shown below.

    Figure 15

    Identity Providers configured

  7. Click the Relying Party Applications link on the navigation menu in order to register your Web site with ACS. ”Relying Party” is identity speak for application, the entity which consumes identities, whereas as you already guessed “Identity Provider” indicates one entity which stores identities and is capable of authenticating users.

    Figure 16

    Relying Party Applications

  8. Click the Add link on top of the Relying Party Applications table and fill the form with the following values:

    • Name: WebSiteACS
    • Mode: Enter settings manually
    • Realm: https://localhost/WebSiteACS/
    • Return URL: https://localhost/WebSiteACS/Default.aspx
    • Error URL: leave the field empty
    • Token format: SAML 1.1
    • Token encryption policy: None
    • Token lifetime (secs): 600
    • Identity Providers: Google, Windows Live ID, Yahoo!
    • Rule groups: Create New Rule Group
    • Token signing: Use service namespace certificate (standard)

    Figure 17

    Add Relying Party Application

  9. Click the Save button.
  10. In the Trust Relationships section of the navigation menu, click the Rule Groups link in order to select the default rule group for your application.

    Figure 18

    The current rule groups list contains just the default rule group

    Figure 19

    An example of how ACS receives a token as proof of authentication (in this case from Google, but it can come from any recognized IP) and can emit for the application a token containing the original claims

    Note:
    When a user successfully authenticates with one identity provider, ACS receives from that identity provider an artifact (called “security token”) which represents the proof that authentication took place. You don’t need to know the details of how a security token looks like: the only information relevant at the moment is that the token contains information about the authenticated user, the so-called claims, which help ACS to establish who the current user is.

    ACS can process the incoming claims in various ways: you will see a simple example of that in the next exercise. In the current exercise we will configure ACS to enforce its default behavior, that is to say making sure that your application receives the claims as they came from the original identity providers. How does it do that? The ACS itself emits a token that your application is configured to consume (as you will see in just few steps). All it needs to do is to copy the incoming claims as is into the outgoing token.

  11. Click Default Rule Group for WebSiteACS, and then click the Generate link. Then select all three identity providers you want to automatically generate rules for, based on available claim types and click Generate. Different identity providers offer different claims: ACS knows that and generates the default rules accordingly. Finally click Save again.

    Figure 20

    Generating Rules

    Figure 21

    Default Rules Generated

  12. Under the Development section of the navigation menu, click the Application Integration link. Here there are various URIs that come in handy when configuring your application to take advantage of ACS.
  13. Go to Endpoint Reference section and copy the value for WS-Federation Metadata. You will discover what that is and what it is used for right at the beginning of the next step.

    Figure 22

    Copying WS-Federation Metadata

Task 4 – Configuring a Website to Accept Tokens from Access Control Service

  1. By now you know that ACS takes care of accepting tokens in different formats via different protocols from a number of possible identity providers, and normalizes the incoming information in a different token that your Web site will consume. ACS can emit different token types on various protocols. For Web sites, the default protocol is WS-Federation. There’s no need to go in the fine details: suffice to say that WS-Federation is a protocol that is natively understood by Windows Identity Foundation (WIF), an extension to the .NET framework that allows you to easily outsource application authentication to tokens sources such as the ACS itself. In particular, WIF extends Visual Studio with a wizard which can automatically configure your application to outsource authentication without requiring you to write a single line of code. All it needs is the address of a machine-readable description of the token source to be used: in our case, that description is the WS-Federation Metadata address you saved at the end of Task 3.
  2. In this task you will use the WIF wizard to outsource authentication to ACS.
  3. Back to Visual Studio and in the Solution Explorer, right-click the https://localhost/WebSiteACS/ project and select Add STS reference….
  4. When the Federation Utility window shows up, please go through the following tasks for each step in the wizard.
    1. On the Welcome page click Next to continue using the pre-populated fields.

      Figure 23

      Welcome

    2. On the STS options page select the third radio button "Use an existing STS" option, paste the endpoint address taken from Task 3 – Step 13 in Endpoint Reference,WS-Federation metadata field and click Next.

      Figure 24

      Use an Existing STS option

    3. On the STS signing certificate chain validation error page select Disable certificate chain validation and click Next.

      Figure 25

      Disable certificate chain validation option

    4. On the Security token encryption page select No encryption and click Next.

      Figure 26

      Security Token encryption

    5. On the Offered claims page click Next.

      Figure 27

      Offered Claims

      Note:
      The WS-Federation Metadata can contain descriptions of the claims that the endpoint offers. The wizard shows those to you so that you will know what information about incoming users you will be able to process in your application. In this case ACS declares that it can release information about which identity provider was actually used for authentication and a user identifier.

    6. On the Summary page review the changes that will be made and click Finish.

Exercise 1: Verification

It’s time to give your newly secured Web site a spin. In order to verify that you have correctly performed all steps in exercise one, proceed as follows:

  1. Start debugging by pressing F5. The relying party application (https://localhost/WebSiteACS/) will redirect to the Access Control Service to authenticate.
  2. Choose an Identity Provider; you will be redirected to the identity provider’s Web site where you will be prompted for entering your credentials. In this example we will use Windows Live ID: choosing other options will lead to comparable experiences.

    Figure 28

    Choosing your Favorite Identity Provider

  3. In the Windows Live ID website enter your Live ID and password.

    Figure 29

    Login with Windows Live ID

  4. Upon successful authentication you will be redirected to ACS (observe the address bar) which will briefly process and redirect back to your Web site.
  5. The process is entirely transparent to the user, but the Web site is now configured to verify that a valid token from the ACS is present in the call: that is the case, hence you are granted access and the default page finally appears in the browser.

    Figure 30

    User Authenticated

  6. Close the browser.

Exercise 1: Summary

In the first exercise you learned the ropes of using ACS for handling authentication for you. At the same time, you learned how to use WIF for automatically configure a Web site to outsource authentication to external entities. The process is exactly the same whether you point your application to ACS, an internal identity provider such as ADFS2, and any product complying with WS-Federation.

Once you outsourced authentication to ACS, you can start changing settings (such as which identity providers should be used) directly at the ACS portal without the need to touch the application code.