Passing Credentials for Authentication to Web Services

Passing Credentials for Authentication to Web Services

When you call a Web service, you do so by using a Web service proxy; a local object that exposes the same set of methods as the target Web service.

You can generate a Web service proxy by using the Wsdl.exe command line utility. Alternatively, if you are using Visual Studio .NET you can generate the proxy by adding a Web reference to the project.

Note

If the Web service for which you want to generate a proxy is configured to require client certificates, you must temporarily switch off that requirement while you add the reference, or an error occurs. After you add the reference, you must remember to reconfigure the service to require certificates. An alternate approach would be to keep an offline Web Services Description Language (WSDL) file available to consumer applications. You must remember to update this if your Web service interface changes.

Specifying Client Credentials for Windows Authentication

If you are using Windows authentication , you must specify the credentials to be used for authentication using the Credentials property of the Web service proxy. If you do not explicitly set this property, the Web service is called without any credentials. If Windows authentication is required, this will result in an HTTP status 401, access denied response.

Using DefaultCredentials

Client credentials do not flow implicitly. The Web service consumer must set the credentials and authentication details on the proxy. To flow the security context of the client’s Windows security context (either from an impersonating thread token or process token) to a Web service you can set the Credentials property of the Web service proxy to CredentialCache.DefaultCredentials as shown below.

proxy.Credentials = System.Net.CredentialCache.DefaultCredentials;

Consider the following points before you use this approach:

§  This flows the client credentials only when you use NTLM, Kerberos, or Negotiate authentication.

§  If a client-side application (for example, a Windows Forms application) calls the Web service, the credentials are obtained from the user’s interactive logon session.

§  Server-side applications, such as ASP.NET Web applications, use the process identity, unless impersonation is configured in which case the impersonated caller’s identity is used.

Using Specific Credentials

To use a specific set of credentials for authentication when you call a Web service, use the following code.

CredentialCache cache = new CredentialCache();

cache.Add( new Uri(proxy.Url), // Web service URL

           "Negotiate",  // Kerberos or NTLM

           new NetworkCredential("username", "password", "domainname") );

proxy.Credentials = cache;

In the above example, the requested Negotiate authentication type results in either Kerberos or NTLM authentication.

Request a Specific Authentication Type

You should request a specific authentication type as illustrated above. Avoid direct use of the NetworkCredential class as shown in the following code.

proxy.Credentials = new NetworkCredential("username", "password", "domainname");

This should be avoided in production code because you have no control over the authentication mechanism used by the Web service and as a result you have no control over how the credentials are used.

For example, you may expect a Kerberos or NTLM authentication challenge from the server but instead you may receive a Basic challenge. In this case, the supplied user name and password will be sent to the server in clear text form.

Set the PreAuthenticate Property

The proxy’s PreAuthenticate property can be set to true or false. Set it to true to supply specific authentication credentials to cause a WWW-authenticate HTTP header to be passed with the Web request. This saves the Web server denying access on the request, and performing authentication on the subsequent retry request.

Note

Pre-authentication only applies after the Web service successfully authenticates the first time. Pre-authentication has no impact on the first Web request. private void ConfigureProxy( WebClientProtocol proxy,                              string domain, string username,                              string password ) {   // To improve performance, force pre-authentication   proxy.PreAuthenticate = true;   // Set the credentials   CredentialCache cache = new CredentialCache();   cache.Add( new Uri(proxy.Url),              "Negotiate",                new NetworkCredential(username, password, domain) );   proxy.Credentials = cache;   proxy.ConnectionGroupName = username; }

Using the ConnectionGroupName Property

Notice that the above code sets the ConnectionGroupName property of the Web service proxy. This is only required if the security context used to connect to the Web service varies from one request to the next as described below.

If you have an ASP.NET Web application that connects to a Web service and flows the security context of the original caller (by using DefaultCredentials or by setting explicit credentials, as shown above), you should set the ConnectionGroupName property of the Web service proxy within the Web application. This is to prevent a new, unauthenticated client from reusing an old, authenticated TCP connection to the Web service that is associated with a previous client’s authentication credentials. Connection reuse can occur as a result of HTTP KeepAlives and authentication persistence which is enabled for performance reasons within IIS.

Set the ConnectionGroupName property to an identifier (such as the caller’s user name) that distinguishes one caller from the next as shown in the previous code fragment.

Note

If the original caller’s security context does not flow through the Web application and onto the Web service, and instead the Web application connects to the Web service using a fixed identity (such as the Web application’s ASP.NET process identity), you do not need to set the ConnectionGroupName property. In this scenario, the connection security context remains constant from one caller to the next.

Calling Web Services from Non-Windows Clients

There are a number of authentication approaches that work for cross-browser scenarios. These include:

§  Certificate Authentication. Using cross platform X.509 certificates.

§  Basic Authentication. For an example of how to use Basic authentication against a custom data store (without requiring Active Directory), see http://www.rassoc.com/gregr/weblog/stories/2002/06/26/webServicesSecurityHttpBasicAuthenticationWithoutActiveDirectory.html.

§  GXA Message Level Approaches. Use the Web Services Development Toolkit to implement GXA (WS-Security) solutions.

§  Custom Approaches. For example, flow credentials in SOAP headers.

Proxy Server Authentication

Proxy server authentication is not supported by the Visual Studio .NET Add Web Reference dialog box (although it will be supported with the next version of Visual Studio .NET). As a result you might receive an HTTP status 407: “Proxy Authentication Required” response when you attempt to add a Web reference.

Note

You may not see this error when you view the .asmx file from a browser, because the browser automatically sends credentials.

To work around this issue, you can use the Wsdl.exe command line utility (instead of the Add Web Reference dialog) as shown below.

wsdl.exe /proxy:http://<YourProxy> /pu:<YourName> /pp:<YourPassword> /

pd:<YourDomain> http://www.YouWebServer.com/YourWebService/YourService.asmx

If you need to programmatically set the proxy server authentication information, use the following code.

YourWebServiceProxy.Proxy.Credentials = CredentialsCache.DefaultCredentials