Difference between revisions of "Certificates"

From Studentnet Wiki
Jump to navigation Jump to search
 
(4 intermediate revisions by the same user not shown)
Line 5: Line 5:
  
 
==Requirements==
 
==Requirements==
The database will store certificates in a new table, tracking:
+
*The database will store certificates in a new table, tracking:
Created date
+
**Created date
Expiry
+
**Expiry
Certificate data
+
**Certificate data
Key data
+
**Key data
Name
+
**Name
The Dashboard will add a new UI section allowing users to:
+
*The Dashboard will add a new UI section allowing users to:
List certificates
+
**List certificates
The list will clearly indicate expired certificates
+
***The list will clearly indicate expired certificates
The list will clearly indicate certificates with 1 month left until expiry
+
***The list will clearly indicate certificates with 1 month left until expiry
Create new certificates
+
**Create new certificates
Auto-generate the certificate data
+
***Auto-generate the certificate data
Allow choice of expiry (6 months, 1 year, 2 years, 5 years)
+
***Allow choice of expiry (6 months, 1 year, 2 years, 5 years)
Provide a human-readable name for the certificate
+
***Provide a human-readable name for the certificate
Delete certificates
+
**Delete certificates
The Dashboard will check that the certificate meets the following criteria before deleting:
+
***The Dashboard will check that the certificate meets the following criteria before deleting:
Not the default
+
****Not the default
Not the rollover certificate
+
****Not the rollover certificate
Not used by any specific service
+
****Not used by any specific service
See certain details of the certificate
+
**See certain details of the certificate
The dashboard WILL NOT expose key information, only certificate information
+
***The dashboard WILL NOT expose key information, only certificate information
The dashboard will list any services explicitly using the certificate
+
***The dashboard will list any services explicitly using the certificate
The dashboard will indicate if the certificate is default or rollover
+
***The dashboard will indicate if the certificate is default or rollover
The dashboard will add a new UI section to IDP Settings:
+
*The dashboard will add a new UI section to IDP Settings:
Default certificate
+
**Default certificate
Rollover certificate
+
**Rollover certificate
The dashboard will add a new form allowing the configuration of Signing Certificate and 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
+
*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
+
**None is a valid option
If the certificate is None, the default certificate will be used
+
**If the certificate is None, the default certificate will be used
This behaviour will allow seamless upgrades from the current configuration
+
**This behaviour will allow seamless upgrades from the current configuration
The school initialisation script will import the current default certificate on first run
+
*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 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 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 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 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 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
+
*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:
+
**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
+
***Default certificate has 1 month until expiry date
No rollover certificate exists
+
***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
+
**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:
+
*Multiple new event types will be added to the event types list:
New Certificate Created
+
**New Certificate Created
Certificate Deleted
+
**Certificate Deleted
Default certificate rollover
+
**Default certificate rollover
Certificate expiring
+
**Certificate expiring
Nightly cron job will create Default certificate rollover event when rolling over
+
*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
+
*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
+
**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
+
**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
+
*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
+
*Administration Events report will be updated to display the new event types
  
 
==Out of Scope==
 
==Out of Scope==
Line 69: Line 69:
 
There are 4 different scenarios to consider when approaching rollover:
 
There are 4 different scenarios to consider when approaching rollover:
  
#Automated metadata
+
;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
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
+
;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.
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
+
;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.
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
+
;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.
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.
 
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.

Latest revision as of 04:50, 5 July 2024

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.