Getting the Browser-Facing Certificate

Overall, the procedure for obtaining the browser-facing certificate is:

  • choose a CA
  • create a private key
  • submit a Certificate Signing Request (CSR) to the CA
  • CA creates signed certificate and sends it back

Choosing the CA

The following issues should be considered when deciding which CA to use:

  • Jisc-connected organisations will normally choose to use the Jisc Certificate Service certificates rather than purchase from a commercial supplier, unless the same certificate is also to be used to secure financial transactions.
  • In general, any commercial CA can be used, provided the CA's root certificate is built in to common browsers (this is true for all the well-known CAs: VeriSign, Thawte, etc.)
  • In some cases a local campus CA can be used, but only if you are certain that all the users of your identity or service provider will have their browsers configured to trust this campus CA; otherwise users will receive confusing pop-up error messages. Commercial certificates avoid this issue because they are trusted by most browsers.

Making the Private Key

You will need to generate a public/private key pair manually. If you don't already have a suitable key pair, you can create one using OpenSSL: 

 openssl genrsa 2048 > my.key

The contents of the private key file must be kept secret. Otherwise, supposedly secure communications can be intercepted or faked. At a minimum:

  • Only those responsible for maintenance of the server should be allowed access to the key file.
  • Never email it to anybody. Email is not secure.
  • Make the key file inaccessible to other users. This is not the default on some Unix systems.

To make a file inaccessible by other users except system administrators (Unix systems only): 

 chmod go= my.key

It is also possible to encrypt the key with a password. However, because the web server will need to read the key, the password must usually be put into its configuration files, so this is not as helpful as it seems. It may even make things worse, if those configuration files can be read by other users. For details of this option, see this documentation about making keys.

The key file should also be kept safe. If you lose it, you will need to get a new certificate. At a minimum:

  • Ensure there is a backup of the key file and that it is equally secret.

Generating the Certificate Signing Request (CSR)

Using the key you made above, you must now create a Certificate Signing Request (CSR) file containing your public key, the DNS name to be certified and the name of your organisation. A CSR file can be generated using OpenSSL: 

 openssl req -new -key my.key -out my.csr

When you run this command, OpenSSL should prompt you to input Country Name (GB), your Organisation Name, Organisational Unit and Common Name.

  • The CN or Common Name given must be the fully qualified domain name part of the URLs that you intend to use the certificate for. In simple cases this will just be the DNS name of the server, e.g., shibbox.uni.ac.uk.
  • The Organisation Name must exactly match the full formal name of your organisation as known to the CA. For Jisc Certificate Service certificates, your local contact who deals with Jisc Certificate Service certificate requests (the proxy) should be able to tell you the exact string to use: Jisc will check this against public lists of educational organisations. For other CAs, the name must match the supporting paperwork which the CA will request from you.
  • The Organisational Unit given should reflect any existing practice within your organisation (faculty, department, etc.) For Jisc Certificate Service certificates, guidelines may be available from your local proxy.
  • You may enter a contact email address or leave it blank, as you choose
  • Finally, OpenSSL may also ask for a "challenge password" and optional company name; we recommend you leave both of these empty.

Make sure all of the information entered into the Certificate Signing Request is exactly what you want: it can't be changed after the certificate is issued.

Submitting the Certificate Signing Request

Once you have made the CSR file, you need to send it to the Certification Authority. You must also prove to the CA that you are a legitimate user of the requested Organisation and DNS names. The procedure for submitting the CSR will be described in the CA's published documentation. For the particular case of the Jisc Certificate Service, please see the documentation about requesting a Jisc Certificate Service certificate.

Expect to spend a fair amount of time on the certification process (days rather than minutes or hours). The objective is not to issue the certificate in the shortest time possible but for the CA to make extensive manual checks to ensure that the information in the certificate is genuine and correct and prevent the issue of a certificate in your organisation's name to a fraudster wanting to pass themselves off as that organisation to unsuspecting users on the web.

When you receive the CA certificate

When the CA send your server certificate they will also include a certificate bundle containing their intermediate certificate chain and their root certificate. The bundle normally takes the form of a .pem format text file comprising several certificates concatenated together. The server certificate and the intermediate certificate chain need to be configured for TLS (SSL) on the server's port 443. The root certificate should not be included in the certificate chain, however; if it is in the certificate bundle file then it should be edited out of the file.

Apache

If port 443 is being served by the Apache web server then you can configure the .pem format private key, server certificate and intermediate certificate bundle files as they are in the Apache VirtualHost configuration for port 443. Please see this page for configuration guidance:

http://www.ukfederation.org.uk/content/Documents/Setup2IdPApacheHttpd

Load balancers and proxies

If port 443 is being served by a hardware or software load balancer or proxy or similar technology then please consult the documentation for your product; some products can be configured using the .pem format files like Apache, whereas others may require a keystore, in a similar way to IIS and Java servlet containers.

IIS and Java Servlet containers

If port 443 is being served by Microsoft's IIS web server or a Java servlet container (typically Tomcat or Jetty) then you need a keystore. We recommend that you use the OpenSSL command and the .pem format files documented in previous sections of this page to create a PKCS12 file.

The intermediate certificate file in the command given below has a .pem filename extension, but yours may have a different extension. The following command should still work for you, however. Please contact the federation support team if you have difficulties.

Please note that as mentioned above you should not include the CA's root certificate in the intermediate certificate bundle, because some TLS clients might not verify the certificate chain correctly if the root certificate is present. You should edit the root certificate out of the intermediate certificate file if necessary. If you are not sure which certificate to remove from the file then please feel free to contact the federation support team for advice.

Creating a PKCS12 keystore file for the CA certificate

To create a PKCS12 keystore file ssl-certificate.pkcs12 given an existing private key file ssl-private-key.key, certificate file ssl-certificate.crt and the CA's intermediate certificate file intermediate.pem, where all filenames are relative to the current directory or folder, you can use the following OpenSSL command. You can change the filenames as appropriate for your needs.

You will need to enter a password for the keystore when prompted so you should choose a password and take a note of it before running the command. The password will need to be included in the configuration of the keystore in the Java servlet container or web server configuration. Using a blank password does not work. 

 
 openssl pkcs12 -export -in ssl-certificate.crt -inkey ssl-private-key.key 
 -certfile intermediate.pem -out ssl-certificate.pkcs12

The keystore file resulting from this command called ssl-certificate.pkcs12 contains the private key, the certificate and the intermediate certificate. Nothing will be overwritten by this command unless you already have a file called ssl-certificate.pkcs12 in the current working directory.

Please note that the keystore file ssl-certificate.pkcs12 should be kept secret and definitely not emailed to anybody, because it contains your private key. All the security precautions that apply to your private key file also apply to your keystore file.

Of course, if you are familiar with Java keystores then you can use your preferred mechanism for creating the keystore file.

Configuring a PKCS12 keystore file on port 443

For Shibboleth IdP v2 and v3 running in Tomcat 7 or 8 please see our Tomcat configuration guidance; please note that although that page is intended for Shibboleth IdP v2.x deployers, the port 443 configuration is also valid for Shibboleth IdP v3. Configuration is also given for Tomcat 6, but please be aware that Tomcat 6 is end of life and should not be installed for a new deployment. If you have a legacy Tomcat 6 deployment then we strongly recommend it is replaced with Tomcat 7 or 8.

For Shibboleth IdP v3 running in Jetty on Linux the keystore will typically be configured in the jetty-base/modules/ssl.mod configuration file. For Shibboleth IdP v3 running on Windows and installed using the msi installer with the "Install Jetty" box ticked it must be configured in the idp.ini file in C:\Program Files\Shibboleth\IdP\jetty-base\start.d or C:\Program Files (x86)\Shibboleth\IdP\jetty-base\start.d as appropriate. Please see the Shibboleth IdP v3 installation documentation for more information.

For Microsoft's IIS you can use the "Certificate Import Wizard" to import the PKCS12 keystore into IIS. You will also need to bind the certificate to your website. Please consult Microsoft's documentation for details, and please note that in their documentation Microsoft refer to PKCS12 as PFX.

Certificate Renewal

Browser-facing certificates issued by a CA have a short lifetime, usually one, two or three years, and must be renewed when their expiry date approaches (browsers will raise warning or error messages on encountering expired certificates). We recommend that you create a new private key when you renew the certificate. When the certificate is renewed your configuration can be updated by first taking a back-up copy of the old certificate and key files and (if appropriate) keystore file and then copying the new ones over them.

This is a purely local reconfiguration: the federation is not involved at all (even if you switch to a different CA).

Please note, though, that if you are also using the browser-facing certificate as a trust fabric certificate that you should contact the UK federation and ask for the new certificate to be added to the entity's metadata before you update your IdP or SP configuration.