Code Sample: ASP.NET Web Service

Article
11/09/2015

Updated: June 19, 2015

Applies To: Azure

This samples illustrates how to integrate Microsoft Azure Active Directory Access Control (also known as Access Control Service or ACS) into a simple web service. It uses ASP.NET as a web service host and a command line client. The ASP.NET web service requires a SWT token issued by ACS. The client requests a token from ACS with a user name and password registered with ACS. The code for this sample is located in the ASPNETSimpleService (C#\WebServices\ASPNETSimpleService) subdirectory of the Microsoft Azure Active Directory Access Control (ACS) Code Samples package.

Prerequisites

To run this sample, you will need:

To create an account at the Azure homepage and create an Access Control namespace.
Visual Studio 2010 (any version)

For more details, see ACS Prerequisites (https://go.microsoft.com/fwlink/?LinkId=221065).

Configuring the Sample

The ACS configuration required for this sample can be performed using either the ACS Management Portal or the ACS Management Service. This topic describes both options.

Option 1: Configuring the Sample Using the ACS Management Portal
Option 2: Configuring the Sample Using the ACS Management Service

Option 1: Configuring the Sample Using the ACS Management Portal

To configure the sample using the ACS Management Portal

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)
To create an Access Control namespace, click New, click App Services, click Access Control, and then click Quick Create. (Or, click Access Control Namespaces before clicking New.)
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.)

This action opens the Access Control Service management portal.
To register your application with ACS, click Relying party applications, click Add, and then enter the following information in the form:
- In the Name field, enter ASPNET Simple Service.
- In the Realm field, enter https://localhost:8000/Service/
- In the Return URL field, enter https://localhost:8000/Service/
- Select SWT from the Token format drop-down list box.
- In the Token Signing Key field, click Generate to create a token signing key. Copy this key for use later in the configuration.
- In the Expiration Date field, enter an appropriate expiration date for the key. The key will no longer be valid on this date
- Leave the other fields at their default values.
Click Save and then click Home to return to the home page of the Access Control Service management portal.
With your relying party registered, it is now time to create the rules that determine the claims that ACS will issue to your application. In this sample, we will create a rule that grants any registered user name and password an action claim with a value of reverse. To create this rule, click Home to return to the home page of the Access Control Service management portal, , click Rule Groups, and then click Default Rule Group for ASP.NET Simple Service. Add a new rule with the following settings:
- In the Claim issuer section, select Access Control Service.
- In the Input claim type section, select Any.
- In the Input claim value section, select Any.
- In the Output claim type section, select Enter type and type action in the field.
- In the Output claim value section, select Enter value and type reverse in the field.
In contrast to the web site samples, this sample relies on credentials managed by ACS. The last step in configuring ACS is registering the user name and password for the client application to use. To configure a new user name and password, click Home to return to the home page of the Access Control Service management portal, click Service identities, click Add, and fill out the form. For this sample, use the user name acssample, the Credential Type Password, and the password pass@word1.
Click Save and then click Home to return to the home page of the Access Control Service management portal.

Option 2: Configuring the Sample Using the ACS Management Service

The Visual Studio sample solution has a console application called ConfigureSample which uses the ACS Management Service and the common helpers defined in the Common class library. This application can be used to configure an Access Control namespace for use with this sample.

To configure the sample using the ACS Management Service

To configure the sample, open SamplesConfiguration.cs (acs\Management\ManagementService\Common). Replace the placeholders in the SamplesConfiguration class in the Common class library with information about your Access Control namespace. You can find the information in the ACS Management Portal.

To navigate to the ACS Management Portal: 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) 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.)
- ServiceNamespace - Enter the name of your Access Control namespace.
- ManagementServiceIdentityName - Enter the name of an ACS management service account. The default is ManagementClient.
  
  To find the management service account name, in the ACS Management Portal, click Management service. The accounts are listed by name under Management Service Accounts.
- ManagementServiceIdentityKey - Enter the password for the management service account.
  
  To find the management service account password, in the ACS Management Portal, click Management service. Click the name of a management service account, and then, under Credentials, click Password. The password appears in the Password field. To copy the password, click Show Password.
Run the ConfigureSample application in Visual Studio. This will configure ACS to run this sample.
When the ConfigureSample application completes, it will output the generated relying party signing key to the console. Copy this key to the clipboard.

Running the Sample

To run the sample

Open the sample in Visual Studio. The solution consists of two projects: Service and Client.
If you have not already done so, enter your Access Control namespace details in Common\SamplesConfiguration.cs. For more information, see step 1 of Option 2: Configuring via the ACS Management Service. This file is also used by the Service and Client projects.
Open the web.config file in the Service project. Enter your token signing key in the appropriate AppSettings elements. If you configured ACS using the Management Service, this is the value that you copied to the clipboard. To obtain the token signing key, refer to the Certificates and Keys area of the portal. Below is a code snippet showing this area of the Service web.config file.
```
<appSettings>
    <add key="IssuerSigningKey" value="...update to your signing key..."/>
  </appSettings>
```
Open the app.config file in the Client project. Enter your user name and password in the appropriate AppSettings elements. To obtain the user name and password you previously registered, refer to the Service Identities area of the portal. Below is a code snippet showing this area (properly updated) of the Client app.config file.
```
  <appSettings>
    <add key="OAuthUserName" value="acssample" />
    <add key="OAuthPassword" value="pass@word1" />
    <add key="ServiceAddress" value="https://localhost:8000/Service/Default.aspx" />   
  </appSettings>
```
To run the sample, start the service and then start the client. At the client, enter a string to reverse. The client console window should then show output indicating that it has received a token from ACS.

Share via