Open topic with navigation

T U T O R I A L

Using WS-Security with Visual Studio .NET 2003 v2006.1

This tutorial demonstrates how to use the Microsoft .NET implementation of WS-Security 1.0 called Web Services Enhancements (WSE). See ArcWeb Services authentication for general information on the ArcWeb Services authentication process.

The Microsoft .NET implementation of WS-Security, through WSE, allows you to send authentication information in your request instead of relying on a preliminary request/response from Authentication Web Service. See the MSDN Web site for more information about Microsoft WSE. The first part of this tutorial explains the system requirements and the second part provides step-by-step instructions for using WSE to send authentication information to ArcWeb Services.

System requirements

You must have the following components before sending requests to ArcWeb Services using WSE for .NET.

• PC with Pentium 233 MHz or faster processor (Pentium 300 MHz or faster recommended) and 64 MB of RAM (128 MB or higher recommended)
• One of the following Microsoft Windows operating systems: XP Professional with Service Pack 1 or later, XP Home Edition with Service Pack 1 or later, 2000 Professional with Service Pack 3 or later, 2000 Server with Service Pack 3 or later, 2000 Advanced Server with Service Pack 3, or Server 2003 family.
• Microsoft Internet Information Services (IIS) 5.x or 6.0
• Microsoft Visual Studio .NET 2003
• WSE 2.0 SP3
• Active subscription to ArcWeb Services

How to use Visual Studio .NET 2003

NOTE: These steps assume you have Visual Studio .NET 2003.

1. Verify that Network Time Protocol (NTP) is enabled on your client system. NTP establishes a common clock for all systems connected to the Internet. Since the ArcWeb clock uses NTP, enabling NTP on your system helps prevent unexpected expired token errors.

For more information on how to use NTP to synchronize your system clock, see http://tf.nist.gov/service/pdf/win2000xp.pdf or http://www.akadia.com/services/ntp_synchronize.html.

2. Download WSE 2.0 SP3 and install it (Select the Visual Studio developer option during installation).
3. Create a new client application (any type of project) in Visual Studio 2003. Save your project.
4. Right-click your new project in the Solution Explorer pane and select WSE Settings 2.0.

NOTE: If WSE Settings 2.0 Option is not available, click Start>Programs>Microsoft WSE 2.0 Configuration Editor. New Configuration file dialog appears. Click File>Save As… and save the file to the location of your new project's root folder.

5. Check 'Enable this project for Web Services Enhancement' checkbox. Also check 'Microsoft Web Services Enhancement Soap Extension' checkbox if you are enabling WSE for ASP.NET-based Web services.

6. Click OK. This sets the properties of WSE to work with your Visual Studio 2003 project.

NOTE: If prompted to save the configuration file, save as web.config in the project's root folder.

7. Add a Web reference to the ArcWeb service you want your application to access.

This step creates a proxy class from which you can create objects for calling the URL of the ArcWeb service, usually as a SOAP request. WSE automatically adds a second proxy class, with suffix "Wse," that inherits from the Microsoft.Web.Services.WebServicesClientProtocol class. This second class implements the RequestSoapContext and ResponseSoapContext properties used to access the SoapContext objects for the incoming and outgoing SOAP messages.

1. Click Project and click Add Web Reference.
2. In the Add Web Reference dialog box, type the URL for the ArcWeb service you want your application to access in the Address text box and press Enter. For example:

http://www.arcwebservices.com/services/v2006_1/PlaceFinder.wsdl

3. Change the Web reference name in Web Reference Name text box to the ArcWeb Web reference name you want, for example, PF.

4. Click Add Reference.

NOTE: You need to update your Web references if you created them before installing WSE. Right-click the existing Web reference and select Update Web Reference.

You are now ready to add a security token to your message request.

8. Add the following required namespaces to your code.

C#.NET

using Microsoft.Web.Services2;

VB.NET

Imports Microsoft.Web.Services2

9. Create an instance of the proxy class with the Wse suffix that was automatically created when you added the Web reference (Step 7). For example:

C#.NET

PF.PlaceFinderWse myPlaceFinderWse = new PF.PlaceFinderWse();

VB.NET

Dim myPlaceFinderWse As New PF.PlaceFinderWse

10. Get the SoapContext object of the request message. For example:

C#.NET

SoapContext myContext = myPlaceFinderWse.RequestSoapContext;

VB.NET

Dim myContext = myPlaceFinderWse.RequestSoapContext

11. Use the WS-Security Password Helper to translate your password into a Base64-encoded SHA-1 password.

12. Add UsernameToken to the SoapContext.

NOTE: Set the MustUnderstand attribute to false so ArcWeb understands the security header is not a mandatory header. For example:

C#.NET

UsernameToken token = new UsernameToken ("<ArcWeb username>", "<WS-Security Password from step 11">, PasswordOption.SendHashed);
myContext.Security.Tokens.Add(token);
myContext.Security.MustUnderstand = false;

VB.NET

Dim token As New UsernameToken("<ArcWeb username>", "<WS-Security Password from step 11">, PasswordOption.SendHashed)
myContext.Security.Tokens.Add(token)

myContext.Security.MustUnderstand = False

13. Test your implementation of WSE. For example (using the Place Finder Web Service method findPlace):

NOTE: The token from the ArcWeb Authentication Service is no longer required in your requests. In this example, findPlace:token is set to empty string ("").

C#.NET

PF.PlaceFinderWse myPlaceFinderWse = new PF.PlaceFinderWse();
SoapContext myContext = myPlaceFinderWse.RequestSoapContext;
UsernameToken token = new UsernameToken ("<ArcWeb username>", "<WS-Security Password from step 11">, PasswordOption.SendHashed);
myContext.Security.Tokens.Add(token);
myContext.Security.MustUnderstand = false;

PF.PlaceFinderOptions myPlaceFinderOptions = new PF.PlaceFinderOptions();
myPlaceFinderOptions.dataSource = "ArcWeb:ESRI.Gazetteer.World";
PF.GeocodeInfo myLocationInfo myPlaceFinderWse.findPlace("Redlands",myPlaceFinderOptions, "");

VB.NET

Dim myPlaceFinderWse As New PF.PlaceFinderWse
Dim myContext = myPlaceFinderWse.RequestSoapContext
Dim token As New UsernameToken("<Arcweb username>", "<WS-Security Password from step 11">, PasswordOption.SendHashed)
myContext.Security.Tokens.Add(token)
myContext.Security.MustUnderstand = False

Dim myPlaceFinderOptions As New PF.PlaceFinderOptions
myPlaceFinderOptions.dataSource = "ArcWeb:ESRI.Gazetteer.World"

Dim myLocationInfo As PF.GeocodeInfo myPlaceFinderWse.findPlace("Redlands", myPlaceFinderOptions, "")

Below is an example of a complete SOAP request to Place Finder Web Service using WSE (with the Password Type set to "PasswordDigest"). Note that the timestamp information and username are not valid values so you cannot send this request as is.

<?xml version="1.0" encoding="utf-8" ?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/03/addressing"
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<soap:Header>
<wsa:Action></wsa:Action>
<wsa:MessageID>uuid:f8fc3a54-8a51-4742-8546-7c933b2189c8</wsa:MessageID>
<wsa:ReplyTo>
<wsa:Address>http://schemas.xmlsoap.org/ws/2004/03/addressing/role/anonymous</wsa:Address>
</wsa:ReplyTo>
<wsa:To>http://www.arcwebservices.com/services/v2006_1/PlaceFinder</wsa:To>
<wsse:Security>
<wsu:Timestamp wsu:Id="Timestamp-d8314f69-5f56-49e4-8bd3-85ac8d1f693f">
<wsu:Created>2006-11-17T20:15:10Z</wsu:Created>
<wsu:Expires>2006-11-17T20:20:10Z</wsu:Expires>
</wsu:Timestamp>
<wsse:UsernameToken xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id="SecurityToken-f8eab4d8-f6ba-48b6-806a-f24d4900c669">
<wsse:Username>ArcWeb username</wsse:Username>
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordDigest">Base64-encoded SHA-1 password</wsse:Password>
<wsse:Nonce>Pjda1MsyO30kLfGlkB7Qhw==</wsse:Nonce>
<wsu:Created>2006-11-17T20:15:10Z</wsu:Created>
</wsse:UsernameToken>
</wsse:Security>
</soap:Header>
<soap:Body>
<findPlace xmlns="http://www.arcwebservices.com/v2006_1">
<placeName>Redlands</placeName>
<placeFinderOptions>
<resultSetRange xsi:nil="true" xmlns="http://www.arcwebservices.com/v2006_1/com.esri.aws.dto.placefinder/" />
<filterType xsi:nil="true" xmlns="http://www.arcwebservices.com/v2006_1/com.esri.aws.dto.placefinder/" />
<dataSource xmlns="http://www.arcwebservices.com/v2006_1/com.esri.aws.dto.placefinder/">ArcWeb:ESRI.Gazetteer.World</dataSource>
<filterExtent xsi:nil="true" xmlns="http://www.arcwebservices.com/v2006_1/com.esri.aws.dto.placefinder/" />                                  
<filterCountry xsi:nil="true" xmlns="http://www.arcwebservices.com/v2006_1/com.esri.aws.dto.placefinder/" />
<searchType xsi:nil="true" xmlns="http://www.arcwebservices.com/v2006_1/com.esri.aws.dto.placefinder/" />
</placeFinderOptions>
<token />
</findPlace>
</soap:Body>
</soap:Envelope>

Visit the Feedback page to give comments or suggestions about the ArcWeb Developer's Guide.

ArcWeb site | ArcWeb support | support.esri.com

Copyright © ESRI