With the recent update to the WCF Service Reference tool in the VS Marketplace, support has been added for downloading metadata for a web service where the metadata exchange (MEX) endpoint has been secured with IIS authentication.
The purpose of MEX endpoints is to allow clients to discover the service capabilities, including security aspects of the service, and usually this endpoint can be accessed by an anonymous request. This is not a problem in general as the actual service resources can be exposed on secured endpoints. Still, there are cases in which the metadata might be considered sensitive information and so the MEX endpoint must also be secured, allowing only authorized clients to discover the service capabilities.
We need to differentiate between these two levels of authentication; the MEX authentication is usually processed by the server’s pipeline (IIS) while other service requests are authenticated by the web service host’s pipeline (WCF). If authentication is enabled at both levels, the same type of authentication must be used.
In this article, we will demonstrate the new IIS Authentication feature in the WCF Web Service Reference tool and how it is related to the web service authentication feature in WCF.
To illustrate let’s step through an example: I have created a simple WCF Service Application (DemoWebService) using Visual Studio 2017. I deployed the service to my local IIS, and configured it with Digest authentication using the IIS Management Console, as illustrated in the picture below.
In order for my service to work with this server configuration, it must be configured with transport security, I edited the service configuration as follows:
Notice in particular the configuration settings for the binding in lines 20-26 in the web.config file above. By default, VS configures the service to expose metadata over HTTP, line 32.
Now I will add a service reference to a .net core console application (NetCoreDemoServiceClient) using the WCF Service Reference tool.
The user credentials dialog box is presented. After I provide my credentials I can successfully add the service reference to my client application.
When the web server is setup to require a client certificate, the WCF Service Reference tool will look for a suitable certificate in the CurrentUser.My certificate store location, the certificate must be set with client authentication key usage and have a private key. If more than one certificate is available a dialog box will be presented to the user to choose the right certificate.
The generated code configures the endpoint binding security and the address using the SSL URL scheme. A snippet of the generated code is presented below, observe the binding security configuration at lines 97-98 and the default https address at line 108.
However, in order to access the service endpoint operations, we still need to get the user credentials. That’s where the partial method at line 78 above comes in handy.
The partial configuration method is implemented in the user code, the generated code should never be edited as it might need to be regenerated while the service is in development. The interesting code is shown in lines 26-27 below where the client credentials are provided. The mechanism for obtaining the user credentials is out of the scope of this article.
Given that the binding has been configured with transport credentials, SSL authentication will occur for the server hosting the service as well, in the following code server authentication validation is provided in line 30, the sample code just accepts any server certificate as valid.
The WCF Service Reference provider supports the following IIS Authentication types: Basic, Digest, Integrated Windows Authentication and Client Certificate Mapping. We just demonstrated how to configure a client for a service protected with Digest authentication but the configuration for other authentication types is very similar:
- Basic Authentication: Populate the ClientCredentials.UserName property with client username and password.
- Windows Authentication: If the calling application runs under a Windows domain-authenticated context then likely nothing else needs to be done, lines 26-27 would not be needed. However, if the application is running in a different security context, the ClientCredentials.Windows.ClientCredential property must be populated with the user domain, username and password.
- Client Certificate: similarly, the client needs to provide a certificate suitable for authenticating the user by calling ClientCredentials.ClientCertificate.SetCertificate method with the right certificate parameters.
Install the WCF Service Reference update today and let us know what you think of the new MEX Endpoint Authentication feature (and other functionality), instructions can be found in the feedback and questions section of the download page.