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

  • Article

Updated: June 19, 2015

Applies To: Azure

Applies To

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

Overview

Note

This topic pertains to a legacy technology. To create XML Web services and XML Web service clients, see https://go.microsoft.com/fwlink/?LinkID=220304.

This topic describes how to integrate a simple ASP.NET web service with ACS. By integrating your web service with ACS, you factor the features of authentication and authorization out of your code. ACS provides the mechanism for authenticating and authorizing clients to your web service. For more information, see Web Services and ACS

In a web service scenario, it is assumed that a web service client does not have access to a browser and is acting autonomously (without user participation). Also, in a web service scenario, a client can gain access to a web service using either a service identity or an enterprise identity. In the exercise described in this topic, a client gains access to a sample ASP.NET web service using a service identity credential type configured in ACS.

In order to perform the steps in this topic, you must download a sample ASP.NET service. For more information, see Code Sample: ASP.NET Web Service.

Steps for Integrating ACS with an ASP.NET Web Service

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 this sample ASP.NET web service, complete the following steps:

  • Step 1 - Create an Access Control Namespace

  • Step 2 – Launch the ACS Management Portal

  • Step 3 – Add a Relying Party Application

  • Step 4 - Create Rules

  • Step 5 – Configure a Service Identity

  • Step 6 – Configure Trust Between ACS and Your ASP.NET Web Service

  • Step 7 – Test the Integration Between ACS and Your ASP.NET Web Service

Step 1 - Create an Access Control Namespace

For detailed instructions, 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 a Relying Party Application

This section describes how to add 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 ASPNET Simple Service.

    • 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:8000/Service.

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

    • 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 SWT. For more information about tokens and token formats, see Token Formats Supported in ACS and “Token Format” 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 about token lifetimes, see “Token Encryption Policy” in Relying Party Applications.

    • In Identity providers, you can select the identity providers to use with this relying party application.

      For this exercise, however, no identity providers are used, the client gains access to the web service with a service identity, so make sure to clear the check box next to Windows Live ID.

      For more information about service identities, see Service Identities.

    • 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.

    • Under Token Signing Settings, in Token signing key, click the Generate button to generate a 256-bit symmetric key for this relying party.

  4. Click Save.

Step 4 - Create Rules

Rules determine how claims are passed from identity providers or ACS (if ACS is the claims issuer) 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 Rule Groups link under the Getting Started section.

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

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

  4. On the Add Claim Rule page, do the following:

    • In the If section, under Claim issuer, select Access Control Service.

    • In the If section, under Input claim type, leave the default selection of Any.

    • In the If section, under Input claim value, leave the default selection of Any.

    • In the Then section, under Output claim type, select Enter type and then type action, because that is the claim type that is specified in the code of the ASP.NET web service sample that you are using in this exercise: requiredClaimType = “action”. You can find this string in the sample code, in Default.aspx.cs, under acs\WebServices\ASPNETSimpleService\Service.

    • In the Then section, under Output claim value, select Enter value and then type reverse, because that is the claim type that is specified in the code of the ASP.NET web service sample that you are using in this exercise: requiredClaimValue = “reverse”. You can find this string in the sample code, in Default.aspx.cs, under acs\WebServices\ASPNETSimpleService\Service.

    • Click Save.

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

Step 5 – Configure a Service Identity

In the exercise described in this topic, the client requests an ACS-issued Simple Web Token (SWT) from ACS with a username and password registered with and managed by ACS, in other words, an ACS service identity. This section describes how to configure an ACS service identity, or how to configure credentials hosted by ACS that the client can use to request a token from ACS. For more information, see Service Identities. For this exercise, set the service identity name to acssample (the ASP.NET service client uses this value as a username when requesting a token from ACS) and the password to pass@word1.

To configure a service identity

  1. On the ACS Management Portal Home page, click Service Identities in the tree on the left-hand side.

  2. On the Service Identities page, click Add.

  3. On the Add Service Identity page, do the following and then click Save:

    1. In Name, type acssample.

    2. In Type, select Password.

    3. In Password, type pass@word1.

    4. Leave the default values unchanged in Effective date and Expiration date.

  4. On the Edit Service Identity page, click Save.

Step 6 – Configure Trust Between ACS and Your ASP.NET Web Service

This section describes how to integrate ACS with your sample ASP.NET service. For more information, see Code Sample: ASP.NET Web Service.

To configure trust between ACS and the ASP.NET web service

  1. Locate ASPNETSimpleService.sln in the sample you downloaded and open it in Visual Studio® 2010.

  2. In Visual Studio 2010, in Solution Explorer, under Solution ‘ASPNETSimpleService’, double-click web.config.

  3. In web.config, enter the Access Control namespace name and the token signing key that you configured in ACS in the previous steps above. To view the token signing key, click Certificates and Keys in the ACS Management Portal.

    The following code snippet shows the elements of the web.config file that you need to update.

    <appSettings>
    <add key="AccessControlHostName" value="accesscontrol.windows.net"/>
    <add key="AccessControlNamespace" value="...enter your Access Control namespace name..."/>
    <add key="IssuerSigningKey" value="...enter your signing key..."/>
  </appSettings>

  4. Save the updated web.config file.

  5. In Visual Studio 2010, in Solution Explorer, under Solution ‘ASPNETSimpleService’, double-click the app.config file.

  6. In the app.config file, enter the name of your Access Control namespace and the username and password of the service identity that you configured in ACS in the previous steps. To view the username and the password, click Service Identities in the ACS Management Portal.

    The following code snippet show the elements of the app.config file that you need to change.

    <appSettings>
    <add key="AccessControlHostName" value="accesscontrol.windows.net"/>
    <add key="AccessControlNamespace" value="...enter your Access Control namespace name..."/>
    <add key="WrapPassword" value="...update to your password..."/>
    <add key="WrapUsername" value="...update to your username..."/>
    <add key="ServiceAddress" value="https://localhost:8000/Service/Default.aspx" />
  </appSettings>

  7. Save the updated app.config file.

Step 7 – Test the Integration Between ACS and Your ASP.NET Web Service

This section describes how you can test the integration between your ASP.NET web service and ACS.

To test the integration between ACS and your ASP.NET web service

  1. To run the ASP.NET service, in Visual Studio 2010, press F5.

  2. To run the ASP.NET web service client, right-click Client in the Solution Explorer, then Debug, and then select Start New Instance.

    A command line window opens with the following message in it: Enter a string to reverse, then press <ENTER>.

  3. Enter any string, for example, hello world!, and then press enter.

    If your input was hello world!, you should see the following response on the console application: !dlrow olleh.

See Also

Concepts

ACS How To's