How To Update Server Certificates for Shibboleth

X.509 server certificates are usually valid for one year, sometimes a few years. Renewal is essential for the proper function of Shibboleth an therefore for the AAI infrastructure. This page gives advice for Identity Provider and Service Provider Administrators.

Updating the Server Certificate

In general, updating the server certificate involves the same steps as getting a new certificate:

  1. generate the private key
  2. generating a certificate signing request (CSR)
  3. get the signed server certificate
For use with Shibboleth, the certificate should be in PEM format, encoded as X.509 standalone certificates with the certificate chain. Participants of SWITCHpki forward the request to the person responsible for certificates in their organisation. Consult the SWITCHpki Certificate Management pages for instructions.

Identity Provider (IdP) Configuration

The server certificates are used from two main components:

  1. The Shibboleth IdP
  2. The web server listening on https (Apache or Tomcat)
The Single Sign-On system (i.e. CAS or Pubcookie) may also use the certificates.

Shibboleth

The Shiboleth IdP 1.3 can use .key and .crt files in PEM format. A java keystore can be used instead, but is not necessary.

The relevant section in /etc/shibboleth/idp.xml is: 

<Credentials xmlns="urn:mace:shibboleth:credentials:1.0">
  <FileResolver Id="switchaai_cred">
    <Key>
       <Path>file:///etc/shibboleth/www.example.org.key</Path>
    </Key>

    <Certificate>
      <Path>file:///etc/shibboleth/www.example.org.crt</Path>
    </Certificate>
  </FileResolver>
</Credentials>

Apache mod_ssl

After getting a new certificate. Move the server certificate and key files to the appropriate location in the Apache config directory.

  • /etc/ssl/certs/www.example.org.crt (certificate file)
  • /etc/ssl/private/www.example.org.key (key file)
In the httpd configuration, point the variable SSLCertificateFile to the location of the certificate file and SSLCertificateKeyFile to the private key file. (See mod_ssl doc for more information.)

If the Apache web server asking for the certificate passphrase when starting up, remove the passphrase from the key file: 

openssl rsa -in www.example.org.enckey -out www.example.org.key

Pubcookie

Note: If you use Pubcookie, don't forget to update the certificates for Pubcookie.

Tomcat

Create an empty keystore: 

keytool -v -genkey -v -alias 123 -keystore www.example.org.jks
keytool -v -delete -alias 123 -keystore www.example.org.jks
Convert key to pkcs8/DER format: 
openssl pkcs8 -in www.example.org.key -topk8 \
  -nocrypt -outform DER -out www.example.org.der.pkcs8
Import the private key/certificate chain into the java keystore using the extkeytool that comes with the Shibboleth IdP distribution: 
export IDP_HOME=/opt/shibboleth-idp-1.3.1-install/
	/opt/shibboleth-idp-1.3.3-install/bin/extkeytool -importkey \
	   -keystore www.example.org.jks -storepass KEYSTOREPASS \
	   -alias www.example.org -keyfile www.example.org.der.pkcs8 \
	   -keypass KEYSTOREPASS -certfile www.example.org.crt.pem \
	   -provider org.bouncycastle.jce.provider.BouncyCastleProvider
Ignore Messages "attempt to process message to long for cipher": Make sure the certificate has been imported correctly: 
keytool -v -list -keystore www.example.org.jks

The java keystore is configured in the Tomcat connector configuration located in /etc/tomcat/server.xml. 

<!-- Define a SSL HTTP/1.1 Connector on IP_ADDRESS_1 / port 443 
     without client auth for www.example.org -->
<Connector address="IP_ADDRESS_1" port="443" maxHttpHeaderSize="8192"
   maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
   enableLookups="false" disableUploadTimeout="true"
   acceptCount="100" scheme="https" secure="true"
   clientAuth="false" sslProtocol="TLS"
   keystoreFile="/etc/tomcat/www.example.org.jks"
   keystorePass="KEYSTOREPASS"
 />

<!-- Define a SSL HTTP/1.1 Connector on IP_ADDRESS_2 / port 443 
     with client authentication for aai-aa.example.org -->
<Connector address="IP_ADDRESS_2" port="443" maxHttpHeaderSize="8192"
   maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
   enableLookups="false" disableUploadTimeout="true"
   acceptCount="100" scheme="https" secure="true"
   clientAuth="true" sslProtocol="TLS"
   keystoreFile="/etc/tomcat/www.example.org.jks"
   keystorePass="KEYSTOREPASS"
   truststoreFile="/etc/tomcat/truststore.jks"
   truststorePass="KEYSTOREPASS"
 />

CAS (Central Authentication System)

In case you use CAS as an SSO for your IdP server, you may have to update your configuration. Check if the certificate you use is from a certification authority(CA) which is trusted by Tomcat: The CA certificate has to be in one of the following Java keystores:

  1. Java's default CA certificate keystore which comes with the JVM 
    $JAVA_HOME/jre/lib/security/cacerts
  2. The keystore configured with the JVM startup option 
    -Djavax.net.ssl.trustStore
    when starting Tomcat (check CATALINA_OPTS in the Tomcat startup scripts).
  3. The keystore configured for Tomcat's SSL Connector (check the Tomcat configuration for a truststoreFile attribute in the Connector element).

Verifying the correct installation of the server's certificate

To check if your server is correctly configured, you can use OpenSSL's s_client command: 

openssl s_client -connect www.example.org:443 -showcerts

which should then show output similar to the following (sample output when connecting to https://www.switch.ch):

CONNECTED(00000003)
depth=1 /C=BE/O=Cybertrust/OU=Educational CA/CN=Cybertrust Educational CA
verify error:num=20:unable to get local issuer certificate
verify return:0
---
Certificate chain
 0 s:/C=CH/O=Switch - Teleinformatikdienste fuer Lehre und Forschung/CN=www.sw
itch.ch
   i:/C=BE/O=Cybertrust/OU=Educational CA/CN=Cybertrust Educational CA
-----BEGIN CERTIFICATE-----
MIIEnzCCA4egAwIBAgILAQAAAAABChuxkLwwDQYJKoZIhvcNAQEFBQAwXzELMAkG
A1UEBhMCQkUxEzARBgNVBAoTCkN5YmVydHJ1c3QxFzAVBgNVBAsTDkVkdWNhdGlv
[...]
LCNaWldj+Ft8NcBAFsgVAnPt9hm6KAa9aREYEFrT5mMwvE80j2P5UDtu3eYExmLY
Z3zgb2AXUYQRNy5DGGLe7u0d6hnruMNxnx30XxKi1zIoKos=
-----END CERTIFICATE-----
 1 s:/C=BE/O=Cybertrust/OU=Educational CA/CN=Cybertrust Educational CA
   i:/C=US/O=GTE Corporation/OU=GTE CyberTrust Solutions, Inc./CN=GTE CyberTru
st Global Root
-----BEGIN CERTIFICATE-----
MIIEQjCCA6ugAwIBAgIEBAAD+zANBgkqhkiG9w0BAQUFADB1MQswCQYDVQQGEwJV
UzEYMBYGA1UEChMPR1RFIENvcnBvcmF0aW9uMScwJQYDVQQLEx5HVEUgQ3liZXJU
[...]
cnVzdCBTb2x1dGlvbnMsIEluYy4xIzAhBgNVBAMTGkdURSBDeWJlclRydXN0IEds
b2JhbCBSb290MB4XDTA2MDMxNDIwMzAwMFoXDTEzMDMxNDIzNTkwMFowXzELMAkG
-----END CERTIFICATE-----
---
Server certificate
subject=/C=CH/O=Switch - Teleinformatikdienste fuer Lehre und Forschung/CN=www
.switch.ch
issuer=/C=BE/O=Cybertrust/OU=Educational CA/CN=Cybertrust Educational CA
---
No client certificate CA names sent
---
SSL handshake has read 2968 bytes and written 332 bytes
---
[...]

Make sure that the server sends the certificate chain (at least your server's certificate plus intermediate certificates).

For example, if you are using SWITCHpki SCS certificates, make sure that two certificates (i.e. the blocks enclosed by ----BEGIN CERTIFICATE-----/-----END CERTIFICATE-----) appear in this output - the server certificate itself and the one for the intermediate CA ("Cybertrust Educational CA"). It's not necessary to include the root certificate ("GTE CyberTrust Global Root"), as this is (pre)installed on the client.