|
Requesting and using a client certificate
IMPORTANT:
Middleware's web services are secured by using client certificates at the transport layer (SSL) and by the
IP address of the clients. Certificates authenticate and ensure privacy of the data exchanged and the
IP address security makes sure the request is originating from an authorized host.
Your client language / toolkit must support accessing web services with SSL certificates or you will
not be able to use MST web services. As of this time, clients that support this are Perl, PHP,
Java, and .NET (with special instructions, see below).
You will have one certificate for testing and and one for production.
The process for getting and using certificates is as follows.
Get your test/development certificate first:
1. Generate a certificate signing request file (".csr", see below)
2. Submit the contents of the webservices.csr file to the MST Web Services "TEST" Root Certificate Authority at https://sslcatest.services.wisc.edu
3. Watch your email and wait for your signed certificate ("###.pem", where ### is your unique serial number) to be returned by our CA as an email attachment.
4. Install the signed certificate, key and MST Web Services Root CA certificate into your test application.
5. Make sure the proper MST Web Services Root CA certificate is used. Use this one for the testing environment.
6. E-mail mst-ws@lists.wisc.edu with the IP address(es) of your test machines so we may authorize them for the example 'Test' services.
7. Try out MST's 'Test' web service at http://rpctest.services.wisc.edu/Test.wsdl
The process for obtaining production certificates is similar.
In step 1, instead of 'xxxx Application Web Services Test Client', create a .csr with 'xxxx Application Web Services Production Client'
In step 2, submit the contents of your .csr file to https://sslca.services.wisc.edu
In step 5, use the production Web Services Root CA certificate, available here.
Getting Your Signed Certificate:
To create a private key and a certificate signing request run the following on any unix box with openssl installed (or use the linked Windows executable):
openssl req -new -nodes -newkey rsa:1024 -keyout webservicesclient.key -out webservicesclient.csr
You will be prompted for the following information. When prompted for an email address, you can put
your personal email address or the email list address of your application service team. Correspondence
from the MST Web Service team about changes and updates to web services and certificate expirations
will be sent to this address. When asked for the 'Common Name', please do not put in a server name
like openssl suggests, this is not a server certificate.
Country Name (2 letter code) [GB]:US
State or Province Name (full name) [Berkshire]:Wisconsin
Locality Name (eg, city) [Newbury]:Madison
Organization Name (eg, company) [My Company Ltd]:University of Wisconsin - Madison
Organizational Unit Name (eg, section) []:Department of Information Technology
Common Name (eg, your name or your server's hostname) []:FooBar Application Web Services Test Client
IMPORTANT NOTE: Use 'xxxx Application Web Services Test Client' for the Common Name, where xxxx is the name of your application.
Resist the temptation to type in your server's name or host here. This is not a host based SSL certificate.
Email Address []:admincontact@doit.wisc.edu
- For Integrated Test Environment certificate requests, go to
https://sslcatest.services.wisc.edu
For Production certificate requests, go to
https://sslca.services.wisc.edu/
- Select Web Services at the "Type of certificate" drop down menu.
- Paste contents of webservices.csr file into the box provided.
- Enter your name, email and telephone number.
- Wait for your certificate to be signed and emailed back to you, along with the appropriate Web Services Root CA certificate.
Important Note: KEEP the certificate signing request ".csr" file for each environment around.
You will need it again (in about a year) to renew your certificate.
Information for Windows / .NET Clients:
1. You must combine your signed certificate and key into one file. (PKCS#12 format)
To combine your key with your signed certificate file to produce a PKCS#12 formatted file:
openssl pkcs12 -export -inkey webservicesclient.key -in ###.pem -out webservicesclient.p12
Note: Do not use a password on the resulting file, but keep the file in a secure location.
2. The combined certificate/key .p12 file and the MST Web Services Root CA Certificate is imported into the Windows with Microsoft Management Console and WinHttpCertCfg.exe tool.
The MST Web Services Root CA Certificate should be sent along with your signed certificate as 'cacert.pem'
If you need it you can get a copy of it here for test, or here, for production.
For further instructions on importing Client and Root CA certificates for web services in Windows, visit: http://msdn2.microsoft.com/en-us/library/aa302408.aspx
Note: In Microsoft documention the PKCS#12 ".p12" file is sometimes called a ".pfx" pfxfile.
Note: Ignore the section "To request a client certificate from Microsoft Certificate Services and install in the local machine store"... you already have one.
Note: The WinHttpCertCfg.exe tool is available here or here.
Quick Start Commands for Client Certs:
C:\WINDOWS>openssl pkcs12 -export -inkey webservicesclient.key -in ###.pem -out webservicesclient.p12
C:\WINDOWS>WinHttpCertCfg.exe -i webservicesclient.p12 -c LOCAL_MACHINE\MY
C:\WINDOWS>WinHttpCertCfg.exe -g -c LOCAL_MACHINE\MY -s "FooBar Application Web Services Test Client" -a "NT AUTHORITY\NetworkService"
C:\WINDOWS>WinHttpCertCfg.exe -g -c LOCAL_MACHINE\MY -s "FooBar Application Web Services Test Client" -a "MyDomain\MyAccount"
|
