AUSTRALIAN ACCESS FEDERATION
Identity Provider Certificates
The certificates this guide is concerned with are those use to provide the trust in the federation, the Trust fabric certificate.
The AAF recommends the use of long-life self-signed certificates with a key length of 2048 bits.
This guide will describe how to use the tools provided by Shibboleth and the AAF to create and manage certificates and keys with minimal impact to the ongoing operation of your Shibboleth IdP. For other technologies the overall process will remain the same, but integrating the certificates into the technology will vary. Please consult your specific technology documentation for details.
Your Initial Key and Certificate
When you install a Shibboleth IdP for the first time a set of self-signed certificates and keys are created for you with the following characteristics.This initial certificate is suitable for use within the AAF and can be used in the Federation Registry tool when Registering a new Identity Provider.
| Characteristic | Description or value |
|---|---|
| File path and name | Signing .../credentials/idp-signing.crt- Public Certificate .../credentials/idp-signing.key - Private key Encryption .../credentials/idp-encrytpion.crt- Public Certificate .../credentials/idp-encrytpion.key - Private key Back Channel .../credentials/idp-backchannel.crt- Public Certificate .../credentials/idp-backchannel.p12 - Private key |
| Private key length | 2048 bits |
| Validity | 20 years |
| Issuer | Self Signed |
| Subject | A CN with the fully qualified hostname of the Shibboleth Identity Provider server, for example, CN=example.aaf.edu.au |
| Subject Alternative Name | A URI with the entityID of the Identity Provider, for example, URI:https://example.aaf.edu.au/idp/shibboleth |
The install script will also provides shibboleth configuration with the certificate and key integrated and a local metadata file that describes the new IdP which includes these certificates.
As part of the installation and configuration process port 8443 is configured to be protected by the backchannel certificate. This can be achieved in two ways. The currently recommended approach is to use Tomcat/Jetty to listen on the port access the certificate and key via the Java key store. The alternative is to use Apache to listen of the port and proxy through to Tomcat/Jetty.
Finally the certificates are required when the IdP is registered in the AAF Federation Registry tool. This will result in the certificates being placed into the AAF Federation Metadata making it available to all participants in the federation. In doing so it allows them to perform the signing, validation, encryption and decryption that is the federation trust.
The following table describes all the locations where the certificate, key and key store are referenced from or are required.
| Location | Files | Description |
|---|---|---|
conf/idp.properties | idp-signing.key idp-signing.crt idp-encryption.key idp-encryption.crt idp-backchannel.crt idp-backchannel.p12 | Settings for public/private signing and encryption key(s) which the IdP uses to perform its various cryptographic functions. |
| metadata/idp-metadata.xml | Copy of the idp certificates | Local IdP metadata |
| conf/idp.properties (jetty.ssl.port=8443) | sealer.jks | The <Connector port="8443"... /> references the IdP's Java Key store which is uses to enable SSL on the port. The keys store password must be provided in the Connector's configuration. |
| Apache SSL configuration | server.crt intermediate.crt server.key | SSL configurations |
| AAF Metadata | IdP certificates | IdP Certificates loaded into the federation registry will be published into the AAF Metadata. Changes in the Federation Registry appear in the AAF Metadata approximately 30 minutes after the change has been approved. Some changes do not require approval and will flow into the metadata within 30 minutes. The Metadata should be consumed be all IdPs and SP within 24 hours, but this is dependent on the individual IdP and SP administrators. The AAF recommends that the AAF Metadata be refreshed at least every 2 hours. |
From the table above it is obvious that care is required when updating and changing an IdPs certificate to ensure there are no service outages as a result. The next section in this guide provides a simple process that will reduce the possibility of a service disruption caused by a certificate update.
When to replace a certificate
Your certificates will need to be replaced periodically (near it's expiry date) or as a result of a compromise of your server.
- Certificate about to expire
All certificates have a limited life time which is set when the certificate is created. The expiry date can be found using the openssl tools to show the contents of your certificate as follows:
$ openssl x509 -in idp.crt -noout -text
Validity
Not Before: Nov 8 00:53:24 2018 GMT
Not After : Nov 8 00:53:24 2038 GMT
The validity section show the date range when the certificate is active.
The Federation Registry will also highlight when a certificate is about to expire as per the following table.
Alert Level | Timing |
|---|---|
| Critical (Red) | One month prior or certificate has passed the expiry date |
| Warning (Yellow) | Between three months and one month of the expiry date. |
| Information (Blue) | Between 6 months and 3 months of the expiry date. |
- Your Certificate have become Compromised
Your certificate is compromised when your private key is no longer private, i.e has been stolen. As soon as you become aware that your certificate has been compromised you should replace as soon as possible.
The AAF recommended that you contact support@aaf.edu.au to discuss additional activities that should be actions as a result of a certificate compromise.
- Changing to Self Signed Certificate
A number of organisations (early adopters) choose to use CA signed certificates for the server to server components of their IdP and in general used the same certificate / key pair that used on the client facing side of their web server.
The AAF recommends that all server-to-server certificates be self signed and all organisations not using a self signed certificate move to do so in a reasonable time frame.
Inter-operation of Identity Providers and Service Providers may be adversely impacted because of the use of CA signed certificates in particular Extended Validation (EV) certificates are known to cause issues.
Certificate Replacement
This explains how to replace a certificate for an Identity Provider without any service disruptions.
- Create a new certificate and key in the installer assets area
Set Java HOME export JAVA_HOME="/usr/lib/jvm/java" Backup the old files cd /opt/shibboleth-idp-installer/repository/assets/[IDP-HOST-NAME]/idp/credentials/ mv idp-signing.crt idp-signing.crt.bak mv idp-signing.key idp-signing.key.bak Create a new certificate /opt/shibboleth/shibboleth-src/current/bin/keygen.sh --certfile idp.crt --keyfile idp.key --hostname example-idp3.edu.au
2. Install the new certificate using the update_idp.sh script
/opt/shibboleth-idp-installer/repository/update_idp.sh
3. Before the Identity Provider can actually use the new certificate to sign assertions, the Service Providers in the federation first must know about this new certificate. The new certificate has to be included into the federation metadata.
To add the new certificate to the IdP description, go to the AAF Federation Registry and add the new certificate to the Identity Provider. You must be one of the Identity Provider administrators to perform this function.
- From your Dashboard select the Identity Provider from the list under "My Identity Providers"
Note:If the IdP is not listed here you will not be able to add a new certificate.
- Select the "Certificates" tab from the IdP tabs
- Select "Add Certificate" at the bottom of the page
- Enter a name for the Certificate, this name is only used within the Federation Registry to assist you keep track of your certificates.
- Cut and Paste the certificate into the area provided. The certificate MUST contain the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.
- The default setting for Signing (ticked) and Encryption (not ticked) should be left unchanged.
- Click the "+ Add" to add the certificate. This will save the certificate.
After the certificate has been saved the AAF metadata file will be populated with two certificates for your IdP, the current certificate that is being replaced and the new certificate. Now, it should take at most 24 hours until every SP to have refreshed there metadata file and thus be aware of the new certificate.
4. Updating bilateral Service Providers
Service that your have connected directly to your IdP through bilateral agreements will need to have their version of your IdP certificate updated. Each service will record details of your certificate differently. You will to consult the documentation of each such service provider to determine how this is achieved.
Please note: The AAF can offer only very limited support for IdPs and SPs that are configured as part of a bilateral agreement (with the service provider not being a subscriber to the AAF).
5: Removing the old certificate from metadata
To avoid any possible issues it is recommended that you remove your old certificate from the AAF Federation Registry after you have restarted your Identity provider.
To remove,
- Select your IdP in the AAF Federation Registry.
- Navigate to the Certificates tag in bottom have of the screen.
- Click the Delete button. You will receive the following warning, click Accept if you are sure you wish to proceed.
"Removing this certificate may cause connectivity problems. Please ensure your remaining certificate list is valid before proceeding"
- Within 30 minutes the old certificate will be removed from the AAF Metadata, and within 24 hours all the certificate should be removed from all subscribers.