000025215 - Protecting IIS Web Services

Document created by RSA Customer Support Employee on Jun 16, 2016Last modified by RSA Customer Support Employee on Apr 21, 2017
Version 2Show Document
  • View in full screen mode

Article Content

Article Number000025215
Applies ToRSA ClearTrust Agent 4.5 for Microsoft IIS
Microsoft Windows Server 2003
.NET Web services
IssueProtecting IIS Web Services
java.lang.SecurityException: no credentials for realm
Error: "Unhandled exception class System.Net.WebException"
CauseA Web service has been protected by ClearTrust. However, a client has been configured to consume the Web services has not been set up to send any authentication credentials.

There is currently no de-facto mechanism to configure security in a Web service until options such as WS-Security or SAML (e.g. RSA FIM) are widely adopted. If your client base is totally under your control, then this may be managed easily. However, if the service has a wider, public consumer base, this is often not practical. The alternative is to use transport authentication (i.e. HTTP authentication mechanisms); a default ClearTrust Agent manages this with a minimum of configuration requirements.

Given a system where RSA FIM is not being used, the choice of HTTP authentication must also be dictated by the amount of control that is available over the consumer base. These options are managed within the webagent.conf file, and may be set globally or for specific sections of the Web site.

For the most straightforward option, the default option is:


Where a stronger form of authentication may be dictated, then this should always override the default. For example, if a specific Web service is only going to be used by a preset group of users (all of whom are configured with SSL client certificates), then the following might be configured:


Although possible, it is unlikely (for the current time) that SECURID would be selected as an option, since this is more commonly used for authentication with a standard Web browser client.

For similar reasons, if the Web service is available for public consumption, the option of Integrated Web authentication (IWA) is less likely to be appropriate, since this would require all public users to be registered in the company Active Directory.

The steps outlined below show what must be done to Web services client programs to allow authentication into the ClearTrust protected resource. These examples show how basic authentication takes place; however, the same paradigm is applicable if SSL client certificates are used. The outline examples assume that a simple Web service has been deployed and has a single method of "HelloWorld" that simply returns a string saying "Hello World". This particular example is a .NET Web service, but that is transparent to any client system and the WSDL is accessed as:



If the Web service client is a Microsoft .NET client, then the Web reference would be imported into the application. The following code shows how a C# client might then make use of the Web service:

    WebService1 ws = new WebService1();
    label1.Text = ws.HelloWorld();

Note: Be careful how you import the web reference.  Remember to follow the same FQDN constraints when setting up the web reference as you use on your netowkr.  For example, if your ClearTrust agent has een installed to generate cookies for .acme.com, then ensure that the web reference that you generate is for www.acme.com and not  You can check this (and change it at a later date by reviewing the generated web reference link and update the Web Reference URL appropriately.


If the Web service client is written in Java, then the code will vary depending on the chosen Web services toolkit. The examples used here use TME GLUE (http://themindelectronic.com) and is used in Microsoft documentation ".NET and J2EE interoperability toolkit" (Microsoft Press). Many other toolkits offer the same facilities (such as Apache AXIS or WebLogic). Generate the client stub code using the WSDL2Java convertor:

    java ?cp glue.jar electric.wsdl.tools.WSDL2Java


Then, using the code to actually call the Web service:

    String url = "http://www.acme.com/WebService1/WebService1.asmx?wsdl";
    IWebService1Soap ws  = (IWebService1Soap)Registry.bind( url,

Steps for both Java and .NET (C#)

Now, the following steps show what is required from start to finish to protect this Web service with ClearTrust and to allow authentication from both a .NET and Java client:

1. Install and configure the ClearTrust Agent 4.5 for IIS as detailed in the Installation Notes

2. Configure the ClearTrust Agent for non-forms-based authentication (since the client code will not understand the HTML). Do this by changing this configuration parameter to read as follows:


Note: Failure to change this parameter will generate a System.Net.WebException error, for example:

                  Unhandled Exception: System.Net.WebException
                            at System.Web.Services.Protocols.SoapHttpClientProtocol.ReadResponse(SoapClientMessage message, WebResponse response, Stream responseStream, Boolean asyncCall)
                            at System.Web.Services.Protocols.SoapHttpClientProtocol.Invoke(String methodName, Object[] parameters)

3. Add the IIS Web server into the ClearTrust entitlements manager

4. Create an application for this Web server called "Sample1"

5. Add a resource to the "Sample1" application of:


NOTE: This example assumes that the virtual directory contains nothing but the sample Web service created as a .NET component

6. Configure 3 users and specifically grant access to user1, specifically deny access to user2, and do not configure any entitlements for user3

7. Test the Web service and authentication by using the HTML interface - to do so, connect with a Web browser to the following:


Any user should be challenged for authentication, but only user1 will be allowed to actually access the web service interface after successfully authenticating.

8. Now modify the C# client code to include basic authentication. This can be achieved by changing your code to look as follows:

        WebService1 ws = new WebService1();
        // Create a new instance of CredentialCache.
        CredentialCache credentialCache = new CredentialCache();

        // Create a new instance of NetworkCredential using the client
        // credentials reading  the username and password values from
        // dialogbox components.

        NetworkCredential credentials = new

        // Add the NetworkCredential to the CredentialCache.
        credentialCache.Add(new Uri(ws.Url),"Basic",credentials);

        // Add the CredentialCache to the proxy class credentials.
        ws.Credentials = credentialCache;
        label1.Text = ws.HelloWorld();

Notice that in production code, this would probably be wrapper in a try/catch constructs to cater for failed authentications.

9. Modify the Java client code in a similar manner:

        Context ctx = new Context();

        String url = " http://www.acme.com/WebService1/WebService1.asmx?wsdl ";
        IWebService1Soap ws  = (IWebService1Soap)Registry.bind( url,

WorkaroundApplication written in Java or C# is trying to access a Web service that requires ClearTrust authentication
Legacy Article IDa20212