How to: Create My First Claims-Aware ASP.NET Application Using ACS

  • Article

Updated: June 19, 2015

Applies To: Azure

Important

ACS namespaces can migrate their Google identity provider configurations from OpenID 2.0 to OpenID Connect. Migration must be completed before June 1, 2015. For detailed guidance, see Migrating ACS Namespaces to Google OpenID Connect. Until you perform migration, this tutorial can be completed using another identity provider, such as Facebook.

Applies To

  • Microsoft Azure Active Directory Access Control (also known as Access Control Service or ACS)

Overview

This topic describes the scenario of integrating ACS with an ASP.NET relying party application. By integrating your web application with ACS, you factor the features of authentication and authorization out of your code. In other words, ACS provides the mechanism for authenticating and authorizing users to your web application.

In this practice scenario, ACS authenticates users with a Google identity into a test ASP.NET relying party application.

Steps for Integrating ACS with an ASP.NET Relying Party Application

Important

Before performing the following steps, make sure that your system meets all of the .NET framework and platform requirements that are summarized in ACS Prerequisites.

To integrate ACS with an ASP.NET relying party application, complete the following steps:

  • Step 1 - Create an Access Control Namespace

  • Step 2 – Launch the ACS Management Portal

  • Step 3 – Add Identity Providers

  • Step 4 – Add a Relying Party Application

  • Step 5 - Create Rules

  • Step 6 - Review the Application Integration Information

  • Step 7 - Create an ASP.NET Relying Party Application

  • Step 8 – Configure Trust Between ACS and Your ASP.NET Relying Party Application

  • Step 9 – Test the Integration Between ACS and Your ASP.NET Relying Party Application

Step 1 - Create an Access Control Namespace

For detailed instructions about how to create an Access Control namespace, see How to: Create an Access Control Namespace.

Step 2 – Launch the ACS Management Portal

The ACS Management Portal allows you to configure your Access Control namespace by adding identity providers, configuring relying party applications, defining rules and groups of rules, and establishing the credentials that your relying party application trusts.

To launch the ACS Management Portal

  1. Go to the Microsoft Azure Management Portal (https://manage.WindowsAzure.com), sign in, and then click Active Directory. (Troubleshooting tip: "Active Directory" item is missing or not available)

  2. To manage an Access Control namespace, select the namespace, and then click Manage. (Or, click Access Control Namespaces, select the namespace, and then click Manage.)

Step 3 – Add Identity Providers

This section describes how to add identity providers to use with your relying party application for authentication. For more information about identity providers, see Identity Providers.

To add identity providers

  1. In the ACS Management Portal, click Identity Providers in the tree on the left-hand side or click the Identity Providers link under the Getting Started section.

  2. On the Identity Providers page, click Add, select Google as the identity provider, and then click Next.

  3. The Add Google Identity Provider page prompts you to enter login link text (the default is Google) and an image URL. This URL points to a file of an image that can be used as the login link for this identity provider. Editing these fields is optional. For this exercise, do not edit them, click Save.

Step 4 – Add a Relying Party Application

This section describes how to add and configure a relying party application. For more information about relying party applications, see Relying Party Applications.

To set up a relying party application

  1. In the ACS Management Portal, click Relying Party Applications in the tree on the left-hand side or click the Relying Party Applications link under the Getting Started section.

  2. On the Relying Party Applications page, click Add.

  3. On the Add Relying Party Application page, do the following:

    • In Name, type the name of the relying party application. For this exercise, type TestApp.

    • In Mode, select Enter settings manually.

    • In Realm, type the URI that the security token issued by ACS applies to. For this exercise, type https://localhost:7777/.

    • In Return URL, type the URL that ACS returns the security token to. For this exercise, type https://localhost:7777/.

    • In Error URL (optional), enter the URL that ACS can post to if an error occurs during sign in. For this exercise, leave this field blank.

    • In Token format, select a token format for ACS to use when issuing security tokens to this relying party application. For this exercise, select SAML 2.0. For more information about tokens and token formats, see Token Formats Supported in ACS and “Token Format” in Relying Party Applications.

    • In Token encryption policy, select an encryption policy for tokens issued by ACS for this relying party application. For this exercise, accept the default value of None. For more information about token encryption policy, see “Token Encryption Policy” in Relying Party Applications.

    • In Token lifetime (secs), specify the amount of time for a security token issued by ACS to remain valid. For this exercise, accept the default value of 600. For more information, see “Token Lifetime” in Relying Party Applications.

    • In Identity providers, select the identity providers to use with this relying party application. For this exercise, accept the checked defaults (Google and Windows Live ID).

    • In Rule groups, select the rule groups for this relying party application to use when processing claims. For this exercise, accept Create New Rule Group that is checked by default. For more information about rule groups, see Rule Groups and Rules.

    • In the Token Signing Settings section, select whether to sign SAML tokens with the certificate for the Access Control namespace or with a custom certificate specific to this application. For this exercise, accept the default value of Use service namespace certificate (standard). For more information about token signing, see “Token Signing” in Relying Party Applications.

  4. Click Save.

Step 5 - Create Rules

This section describes how to define rules that determine how claims are passed from identity providers to your relying party application. For more information about rules and rule groups, see Rule Groups and Rules.

To create rules

  1. On the ACS Management Portal Home page, click Rule Groups in the tree on the left-hand side or click the Rule Groups link under the Getting Started section.

  2. On Rule Groups page, click Default Rule Group for TestApp (since you named your relying party application TestApp).

  3. On the Edit Rule Group page, click Generate.

  4. On the Generate Rules: Default Rule Group for TestApp page, accept the identity providers selected by default (in this exercise, Google and Windows Live ID), and then click the Generate button.

  5. On the Edit Rule Group page, click Save.

Step 6 - Review the Application Integration Information

You can find all of the information and code necessary to modify your relying party application to work with ACS on the Application Integration page of the ACS Management Portal.

To review the application integration information

  • On the ACS Management Portal Home page, click Application Integration in the tree on the left-hand side or click the Application Integration link under the Getting Started section.

    The ACS URIs that are displayed on the Application Integration page are unique to your Access Control namespace.

    For this exercise, it is recommended that you keep this page open in order to perform the remaining steps quickly.

Step 7 - Create an ASP.NET Relying Party Application

This section describes how to create an ASP.Net Relying Party application that you want to eventually integrate with ACS.

To create an ASP.NET relying party application

  1. To run Visual Studio 2010, click Start, click Run, type the following text, and then press Enter:
    devenv.exe

  2. In Visual Studio, click File, and then click New Project.

  3. In New Project window, select either the Visual Basic or the Visual C# template, and then select ASP.NET MVC 2 Web Application.

  4. In Name, type the following text, and then click OK:
    TestApp

  5. In Create Unit Test Project, select No, do not create a unit test project, and then click OK.

  6. In Solution Explorer, right-click TestApp, and then select Properties.

  7. In the TestApp properties window, select the Web tab, under Use Visual Studio Development Server click Specific port, and then change the value to 7777.

  8. To run and debug the application you just created, press F5. If no errors were found, your browser renders an empty MVC project.

    Keep Visual Studio 2010 open in order to complete the next step.

Step 8 – Configure Trust Between ACS and Your ASP.NET Relying Party Application

This section describes how to integrate ACS with the ASP.NET Relying Party application that you created in the previous step.

To configure trust between the ASP.NET relying party application and ACS

  1. In Visual Studio 2010, in Solution Explorer for TestApp, right-click TestApp, and then select Add STS Reference.

  2. In the Federation Utility wizard, do the following:

    1. On the Welcome to the Federation Utility Wizard page, in Application URI, enter the application URI and then click Next. In this demo, the application URI is https://localhost:7777/.

      Note

      The trailing slash is important because it matches the value you entered in the ACS Management Portal for your relying party application. For more information, see Step 4 – Add a Relying Party Application.

    2. A warning pops up: ID 1007: The Application is not hosted on a secure https connection. Do you wish to continue? For this demo, click Yes.

      Note

      In a production environment, this warning about using SSL is valid and should not be dismissed.

    3. On the Security Token Service page, select Use Existing STS, enter the WS-Federation Metadata URL published by ACS, and then click Next.

      Note

      You can find the value of the WS-Federation Metadata URL on the Application Integration page of the ACS Management Portal. For more information, see Step 6 - Review the Application Integration Information.

    4. On the STS signing certificate chain validation error page, click Next.

    5. On the Security token encryption page, click Next.

    6. On the Offered claims page, click Next.

    7. On the Summary page, click Finish.

    Once you successfully finish running the Federation Utility wizard, it adds a reference to the Microsoft.IdentityModel.dll assembly and writes values to your Web.config file that configures the Windows Identity Foundation in your ASP.NET MVC 2 Web Application (TestApp).

  3. Open Web.config and locate the main system.web element. It might look like the following:

    <system.web>
    <authorization>
      <deny users="?" />
    </authorization>

    Modify Web.config to enable request validation by adding the following code under the main system.web element:

        <!--set this value-->
    <httpRuntime requestValidationMode="2.0"/>

    After you perform the update, this is what the above code fragment must look like:

    
   <system.web>
    <!--set this value-->
    <httpRuntime requestValidationMode="2.0"/>
    <authorization>
    <deny users="?" />
    </authorization>

Step 9 – Test the Integration Between ACS and Your ASP.NET Relying Party Application

This section describes how you can test the integration between your relying party application and ACS.

To test the integration between the ASP.NET relying party application and ACS

  1. Keeping Visual Studio 2010 open, press F5 to start debugging your ASP.NET relying party application.

    If no errors are found, instead of opening the default MVC application, your browser is redirected to a Home Realm Discovery page hosted by ACS that asks you to choose an identity provider.

  2. Select Google.

    The browser then loads the Google logon page.

  3. Enter your test Google credentials, and accept the consent UI shown on the Google website.

    The browser then posts back to ACS, ACS issues a token, and posts that token to your MVC site.

See Also

Concepts

ACS How To's