Creating a browser-facing certificate for Shibboleth IdP using Java keytool

This page will take you through creating a browser facing certificate using Java Keytool. This will allow you to create a private key within a Java keystore and a seperate certificate request (CSR), you then pass this to a Certificate Authority (CA) for signing, import it into the Java keystore and this JKS file within Jetty as part of the Shibboleth IdP Windows Installer.

Note: we use idp.example.ac.uk as the FQDN for your Shibboleth IdP in this example. you should replace this with the one you intended to use.

1. From a command prompt on Windows or shell session on Linux, execute the keytool command to confirm that it is in the path. If it is not then you maybe able to temporarily adjust the path based on the JAVA_HOME environment variable.
   • Windows

 Path=%Path%;%JAVA_HOME%\bin;

• Linux

 export PATH=$PATH:$JAVA_HOME/bin

2. Change to the folder of the %{idp-home} on Windows this maybe C:\Program Files (x86)\Shibboleth\IdP and on Linux this maybe /opt/shibboleth-idp
3. Create a folder called browser-cert in the the credentials folder and change to that folder
   • Windows;

 mkdir credentials\browser-cert
 cd  credentials\browser-cert

• Linux;

 mkdir credentials/browser-cert && cd credentials/browser-cert

4. The following command will generate the Java keystore and keypair.

 keytool -genkey -alias idp.example.ac.uk -keyalg RSA -keystore idp.example.ac.uk.jks -keysize 2048 -validity -1096

5. You will be prompted for a number of details.
   • Keystore Password - generate a random and secure password for this, and make a note of it for later configuration
   • First and Last name? - idp.example.ac.uk
   • Organizational Unit? e.g. IT Department
   • Organszation? e.g. Example College
   • City or Locality?
   • State or Province?
   • Two letter country code? GB
6. You now need to generate a Certificate Signing Request (CSR) to send to the relevant Certificate Authority (CA).

 keytool -certreq -alias idp.example.ac.uk -keystore idp.example.ac.uk.jks -file idp.example.ac.uk.csr

7. Submit the 'idp.example.ac.uk.csr' to the relevant Certificate Authority. For example the Jisc Certificate Service
8. Once the certificate request has been completed your CA will provide you with a number of files, this will include the public key of the certificate and any intermediate or root certificates that maybe required, copy the files to your browser-cert folder. For the Jisc Certificate you will be provided the following files idp.example.ac.uk.crt , QuoVadisOVIntermmediateCertificate.crt and QuoVadisOVRootCertificate.crt, in this case we only need the first two files.
9. Import the intermediate certificate(s) as follows;

 keytool -import -trustcacerts -alias intermediate -keystore idp.example.ac.uk.jks -file QuoVadisOVIntermmediateCertificate.crt

10. Import the public key certificate idp.example.ac.uk.crt

 keytool -import -trustcacerts -alias idp.example.ac.uk -keystore idp.example.ac.uk.jks -file idp.example.ac.uk.crt

11. Verify the contents of the keystore and verify the two entriies

 keytool -list -v -keystore idp.example.ac.uk.jks

• Alias name 'Intermediate', and entry type 'trustedCertEntry'
• Alias name 'idp.example.ac.uk' and entry type 'PrivateKeyEntry'

13. Update your Java webserver configuration;
    • For Shibboleth IdP using the Windows installer, then the Jetty configuration can be updated in %{idp-home}/jetty-base/start.d/idp.ini.

 jetty.sslContext.keyStorePath= C:/Program Files (x86)/Shibboleth/IdP/credentials/browser-cert/idp.example.ac.uk.jks
 jetty.sslContext.keyStorePassword= password
 jetty.sslContext.keyStoreType=JKS

14. You can now restart the Shibboleth IdP.
    • On Windows - Go to C:\Program Files(x86)\Shibboleth\ProcRun and choose shibd_idpw.exe and Click Start [If it as already running you may need to hit Start].
    • On Linux - this will depend on the Linux distribution
      • For Ubuntu

 sudo service tomcat8 restart

• For CentOS and Redhat Enterprise Linux

 systemctl restart tomcat

15. Visit your IdP status page at https://idp.example.ac.uk/idp/status in a Browser. If you are testing without the relevant external DNS records and firewalls in place you might wish to temporarily add an entry to your system hosts file C:\Windows\System32\drivers\etc\hosts so that you can test.