Securely Invoking Web Services with X.509 Certificates

This post is about how Web services are invoked using X.509 certificates. Especially as a very basic troubleshooting guide for when configuring clients. (Which as should already be known can be desktop applications or Web Applications).

Background.

Security is a key element in building web services, especially when those web services are exposed on the internet.

To build secure web services, various identity authentication and certification methods can be used, some of them include:

· Custom Security Tokens

· Security Context Tokens

· Kerberos Tickets

· Username and Password

· and X.509 Certificates, which are the ones we are interested in today.

Un X.509 certificate is basically an encryption key issued and certified by a valid certification authority, without going too much into definitions that can be found in more detail on the Internet, the certificate is a file issued to me by a recognized entity, and it is basically a unique number they have given me to hand over to my clients and know that they are the ones calling my service.

Scenario.

A client asks me to invoke a secure web service from my own web application, (for example to show the values of a combobox), this client provides me with an X.509 certificate and informs me of the encryption and authentication policy for this service.

Solution.

1. I must install the Digital certificate on the development Machine, in the test environment and on the Production server, it is possible that the client provides me with two web addresses, one for testing, another for development, that is independent of the certificate.

2. The certificate can be installed in several ways, a very easy one is to copy the certificate to a path on the machine where you want to install it, then right-click with the mouse and follow the wizard

The wizard's next question is whether you want to place the certificate in a specific store or whether you want the wizard to install it based on the certificate information, this is one of those typical questions that you don't really know how to answer or what it means. The certificate repository is divided into levels.

The first level indicates whether you want to store the certificate on the local machine, in the user's profile, or in the service account with which the OS runs.

then comes a second level that includes personal, authorities, certification authorities, active directory, among several others, so the first thing is to know where to place the certificate, a good guide is this one which shows the default locations used to search for digital certificates, so, if the application is a web service or a desktop application trying to sign or encrypt the message it will search in the User Personal Store.

3. Now that I have the server installed I must configure the webconfig and the policy I want to follow for this certificate. (there are many ways to do it, some do not use the web config, but instead create the policy at runtime, etc. this is just one way to approach the problem). In the web config goes something like this:

<!– WSE 2.0 –>
<section name=”microsoft.web.services2″ type=”Microsoft.Web.Services2.Configuration.WebServicesConfiguration, Microsoft.Web.Services2, Version=2.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35″ />

In the configuration part – </configSections> (note, this in VS2003, in VS2005 it may vary)

and of course, the section where I actually do the configuration (in web config)

<microsoft.web.services2>
<diagnostics>
<detailedErrors enabled=”true” />
<trace enabled=”true” />
<policyTrace enabled=”true”
input=”receivePolicy.webinfo”
output=”sendPolicy.webinfo”/>
</diagnostics>
<tokenIssuer>
<autoIssueSecurityContextToken enabled=”true” />
</tokenIssuer>
<policy>
<cache name=”policyCache.config” />
</policy>
<security>
<x509 storeLocation=”LocalMachine” verifyTrust=”false” allowTestRoot=”false” allowRevocationUrlRetrieval=”true” allowUrlRetrieval=”false” />
</security>
</microsoft.web.services2>

this is the development or test version, as you can see the policy trace is enabled <policyTrace enabled=”true”… and files are being generated with information about the requests and responses (input=”receivePolicy.webinfo” output=”sendPolicy.webinfo”). For these files to be created, they are super useful, the account with which the application is running (ASP.NET generally) must be enabled to write in the directory where it is being executed.

The other important thing about this segment is the name of the policy, in this case policyCache.config. what is being said here is that the complete definition of the policy will be in that config file, there can be as many policies as you want. and of course, the security using X.509 and saying in which store the certificate is (storeLocation),

Now the policy file is like this:

<?xml version=”1.0″ encoding=”utf-8″?>
<policyDocument xmlns=”http://schemas.microsoft.com/wse/2003/06/Policy”>
<mappings xmlns:wse=”http://schemas.microsoft.com/wse/2003/06/Policy”>
<!–The following policy describes the policy requirements for the service: http://algo.asmx .–>
<endpoint uri=”algo.asmx”>
<defaultOperation>
<request policy=”” />
<response policy=”” />
<fault policy=”” />
</defaultOperation>
</endpoint>
<endpoint uri=http://algo.asmx>
<defaultOperation>
<request policy=”#Encrypt-X.509″ />
<response policy=”” />
<fault policy=”” />
</defaultOperation>
</endpoint>
<endpoint uri=http://algo.asmx>
<defaultOperation>
<request policy=”#Encrypt-X.509″ />
<fault policy=”” />
</defaultOperation>
</endpoint>
</mappings>
<policies xmlns:wsu=”http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd” xmlns:wsp=”http://schemas.xmlsoap.org/ws/2002/12/policy” xmlns:wssp=”http://schemas.xmlsoap.org/ws/2002/12/secext” xmlns:wse=”http://schemas.microsoft.com/wse/2003/06/Policy” xmlns:wsse=”http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd” xmlns:wsa=”http://schemas.xmlsoap.org/ws/2004/03/addressing”>
<wsp:Policy wsu:Id=”Encrypt-X.509″>
<!–The Confidentiality assertion is used to ensure that the SOAP Body is encrypted.–>
<wssp:Confidentiality wsp:Usage=”wsp:Required”>
<wssp:KeyInfo>
<!–The SecurityToken element within the KeyInfo element describes which token type must be used for Encryption.–>
<wssp:SecurityToken>
<wssp:TokenType>http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3</wssp:TokenType>
<wssp:TokenIssuer>C=US, O=”VeriSign, Inc.”, OU=VeriSign Trust Network, OU=Terms of use at https://www.verisign.com/rpa (c)05, CN=VeriSign Class 3 Secure Server CA</wssp:TokenIssuer>
<wssp:Claims>
<!–By specifying the SubjectName claim, the policy system can look for a certificate with this subject name in the certificate store indicated in the application’s configuration, such as LocalMachine or CurrentUser. The WSE X.509 Certificate Tool is useful for finding the correct values for this field.–> <wssp:SubjectName MatchType=”wssp:Exact”>C=US, S=Wisconsin, L=Milwaukee, O=CLIENTE Company, OU=IS Technical Services, CN=www.cliente.com</wssp:SubjectName>
<wssp:X509Extension OID=”2.7.34.87” MatchType=”wssp:Exact”>0GJdsds3UdP3fsdtretterERFE4=</wssp:X509Extension>
</wssp:Claims>
</wssp:SecurityToken>
</wssp:KeyInfo>
<wssp:MessageParts Dialect=”http://schemas.xmlsoap.org/2002/12/wsse#part”>wsp:Body()</wssp:MessageParts>
</wssp:Confidentiality>
</wsp:Policy>
</policies>
</policyDocument>

Where I have put in bold the values that are key, they come from the certificate and can be located using one of the tools listed below.

You could already see from here the introduction to concepts like endpoint that would later be even more complete in WCF but that is another story.

Tools.

Utility to view certificate information (with source code)

Set up a console to manage digital certificates.

The certificate information management tool included with WSE*

Reference

How to Sign a Message using an X.509 certificate

I hope this saves you a couple of hours, in summary, the certificate is installed in one of the default search locations or you have to change the configuration in the config files. Then the webconfig file and the policy files are modified with the information taken from the certificate using one of the listed tools, and to be able to check for errors, the trace services are enabled.

Juan Peláez

Software Architect

keywords: Web Services, WSE, X.509 certificates, encrypt, sign, web services, tools to configure digital certificates, configuration policies, digital certificates. security in web services, secure services, client identification, client identity.