Certificates

Certificate Renewal in Cloudwork

Overview

Signing certificates for the oldest Cloudwork schools are coming up for renewal, starting in October. This project will move signing certificates into the dashboard, where a school can then manage their signing certificates themselves, and more easily manage the certificate rollover.

Requirements

• The database will store certificates in a new table, tracking:
  • Created date
  • Expiry
  • Certificate data
  • Key data
  • Name
• The Dashboard will add a new UI section allowing users to:
  • List certificates
    • The list will clearly indicate expired certificates
    • The list will clearly indicate certificates with 1 month left until expiry
  • Create new certificates
    • Auto-generate the certificate data
    • Allow choice of expiry (6 months, 1 year, 2 years, 5 years)
    • Provide a human-readable name for the certificate
  • Delete certificates
    • The Dashboard will check that the certificate meets the following criteria before deleting:
      • Not the default
      • Not the rollover certificate
      • Not used by any specific service
  • See certain details of the certificate
    • The dashboard WILL NOT expose key information, only certificate information
    • The dashboard will list any services explicitly using the certificate
    • The dashboard will indicate if the certificate is default or rollover
• The dashboard will add a new UI section to IDP Settings:
  • Default certificate
  • Rollover certificate
• The dashboard will add a new form allowing the configuration of Signing Certificate and Rollover Certificate
• The dashboard will add new config options to SAML services allowing an Administrator to indicate which certificate the SAML service will use
  • None is a valid option
  • If the certificate is None, the default certificate will be used
  • This behaviour will allow seamless upgrades from the current configuration
• The school initialisation script will import the current default certificate on first run
  • The script will check if a default certificate exists, and if it does, no action will be taken
• The IDP config API endpoint will include the default certificate and the rollover certificate
• The SAML Metadata API endpoint will include explicit certificates for services that have selected explicit certificates
• The API will refer to Certificates by database ID
• The IDP will save certificates to the certs directory using the naming structure of <id>.cert and <id>.key
• The cron container will have a new nightly cronjob
  • This cron job will examine the default certificate and create a new rollover certificate when the following conditions are met:
    • Default certificate has 1 month until expiry date
    • No rollover certificate exists
  • This cron job will examine the default certificate and automatically set the new default certificate to be the existing rollover certificate, and removing the existing rollover certificate when the default certificate has 1 day until expiry
• Multiple new event types will be added to the event types list:
  • New Certificate Created
  • Certificate Deleted
  • Default certificate rollover
  • Certificate expiring
• Nightly cron job will create Default certificate rollover event when rolling over
• Nightly cron job will check expiry on all active certificates and generate Certificate expiring events
  • An active certificate is one that is Default, Rollover, or specifically assigned to a service
  • Expiring events should be generated when certificates hit the following thresholds: 1 day, 7 days, 2 weeks, 1 month, 2 months from expiration date
• Dashboard will create New Certificate Created and Certificate Deleted Events on admin actions
• Administration Events report will be updated to display the new event types

Out of Scope

The following items are currently out of scope, though some may be important future improvements

• Automated rollover for services that have a specifically assigned certificate
• Moving expiry notices into their own event type
• Service-specific metadata links that include that service’s specific certificates

Rollover Strategy

There are 4 different scenarios to consider when approaching rollover:

Automated metadata

Some services may monitor the metadata URL and automatically update on a fixed schedule. These services will automatically pick up the new certificates, and no extra work should be required. Extensive testing may be needed beforehand, and depending on the schedule, the service may need to be treated according to the following scenarios

Support for multiple certificates

Services that support multiple signing certificates will need to import the new metadata after the signing certificate is generated. Once the rollover is complete, the school should then remove the old certificate, leaving only the new certificate. No other action will be required.

Manually configured services that only support one certificate

Some services will not be monitoring the metadata endpoint and will only support configuring one signing certificate. For these services, careful coordination will be required. These services SHOULD be updated before rollover. You will need to edit the service in Cloudwork and configure it to use the rollover certificate. The service itself needs to have the new signing certificate uploaded as well. The duration between which one side has been updated and the other hasn’t, authentication will fail, so it is best to schedule in a specific time to update these services.

Sensitive services

It can be convenient for a school to configure a longer duration for the default certificate. Certain high profile applications may benefit from the increased security of shorter duration certificates. For these services, a school can generate and clearly name a certificate with a shorter duration, and manually the service in Cloudwork to use that specific certificate, similar to #3.

Schools are not limited to starting the rollover one month out - a school could manually generate a new certificate, set it as the rollover, and start as early as they like.

We don’t know what services an individual school may be using without looking, and we may not have documentation on every configured service, especially if a school was able to configure it without our help, so it will largely be dependent on the schools, either individually or in coordination with Studentnet to make sure that all services have a clear migration strategy.