$Id$

CAS requires HTTPS be used for all operations, with the certificate used
having been signed by a certificate in the cacerts files shipped with Java.

If you're using a HTTPS certificate signed by a well known authority
(like Verisign), you can safely ignore the procedure below (although you
might find the troubleshooting section at the end helpful).

The following demonstrates how to create a self-signed certificate and add
it to the cacerts file. If you just want to use the certificate we have
already created and shipped with Spring Security, you
can skip directly to step 3.


1. keytool -keystore keystore -alias acegisecurity -genkey -keyalg RSA -validity 9999 -storepass password -keypass password

What is your first and last name?
  [Unknown]:  localhost
What is the name of your organizational unit?
  [Unknown]:  Spring Security
What is the name of your organization?
  [Unknown]:  TEST CERTIFICATE ONLY. DO NOT USE IN PRODUCTION.
What is the name of your City or Locality?
  [Unknown]:
What is the name of your State or Province?
  [Unknown]:
What is the two-letter country code for this unit?
  [Unknown]:
Is CN=localhost, OU=Spring Security, O=TEST CERTIFICATE ONLY. D
O NOT USE IN PRODUCTION., L=Unknown, ST=Unknown, C=Unknown correct?
  [no]:  yes


2. keytool -export -v -rfc -alias acegisecurity -file acegisecurity.txt -keystore keystore -storepass password

3. copy acegisecurity.txt %JAVA_HOME%\lib\security

4. copy keystore %YOUR_WEB_CONTAINER_LOCATION%

   NOTE: You will need to configure your web container as appropriate.
   We recommend you test the certificate works by visiting
   https://localhost:8443. When prompted by your browser, select to
   install the certificate.

5. cd %JAVA_HOME%\lib\security

6. keytool -import -v -file acegisecurity.txt -keypass password -keystore cacerts -storepass changeit -alias acegisecurity

Owner: CN=localhost, OU=Spring Security, O=TEST CERTIFICATE ONL
Y. DO NOT USE IN PRODUCTION., L=Unknown, ST=Unknown, C=Unknown
Issuer: CN=localhost, OU=Spring Security, O=TEST CERTIFICATE ON
LY. DO NOT USE IN PRODUCTION., L=Unknown, ST=Unknown, C=Unknown
Serial number: 4080daf4
Valid from: Sat Apr 17 07:21:24 GMT 2004 until: Tue Sep 02 07:21:24 GMT 2031
Certificate fingerprints:
         MD5:  B4:AC:A8:24:34:99:F1:A9:F8:1D:A5:6C:BF:0A:34:FA
         SHA1: F1:E6:B1:3A:01:39:2D:CF:06:FA:82:AB:86:0D:77:9D:06:93:D6:B0
Trust this certificate? [no]:  yes
Certificate was added to keystore
[Saving cacerts]


7. Finished. You can now run the sample application as if you purchased a
   properly signed certificate. For production applications, of course you should
   use an appropriately signed certificate so your web visitors will trust it
   (such as issued by Thawte, Verisign etc).

TROUBLESHOOTING

* First of all, most CAS-Acegi Security problems are because of untrusted
  SSL certificates. So it's important to understand why. Most people can
  load the Acegi Security webapp, get redirected to the CAS server, then
  after login they get redirected back to the Acegi Security webapp and
  receive a failure. This is because the CAS server redirects to something
  like https://server3.company.com/webapp/login/cas?ticket=ST-0-ER94xMJmn6pha35CQRoZ
  which causes the "service ticket" (the "ticket" parameter) to be validated.
  net.sf.acegisecurity.providers.cas.ticketvalidator.CasProxyTicketValidator
  performs service ticket validation by delegation to CAS'
  ProxyTicketValidator class. The ProxyTicketValidator class will perform a
  HTTPS connection from the web server running the Acegi Security webapp
  (server3.company.com) above to the CAS server. If for some reason the
  web server keystore does not trust the HTTPS certificate presented by the
  CAS server, you will receive various failures as discussed below. NB: This
  has NOTHING to do with client-side (browser) certificates. You need to
  correct the trust between the two webserver keystores alone.

* A "sun.security.validator.ValidatorException: No trusted certificate
  found" indicates the cacerts is not being used or it did not correctly
  import the certificate. To rule out your web container replacing or in
  some way modifying the trust manager, set the
  CasProxyTicketValidator.trustStore property to the full file system
  location to your cacerts file.

* If your web container is ignoring your cacerts file, double-check it
  is stored in $JAVA_HOME\lib\security\cacerts. $JAVA_HOME might be
  pointing to the SDK, not JRE. In that case, copy
  $JAVA_HOME\jre\lib\security\cacerts to $JAVA_HOME\lib\security\cacerts