How to automate SSL certificate operations
SSL certificates can be requested and renewed automatically via an API
Warning: This facility is in pilot / beta-testing
Some of the API-based certificate facilities shown here, and all of the instructions, are in beta-testing and may require further development. If we have contacted you to request participation in this pilot then please send any corrections or other feedback to ITS3.
Warning: Only for use by competent IT Support Staff
You must ensure that you have a thorough understanding of public key infrastructure and digital certificates before using this service - see the related links on this page. Incorrect specification, installation, or use of certificates - even inadvertently - can have an immediate, severe, and potentially irreversible impact on your unit, staff and students, and the wider University.
You should also have a sound understanding of the operating system and server application that you are deploying your certificate to. We are not, in general, able to offer technical support for the systems that you are responsible for managing.
Status
Our Entrust certificate signing service supports a limited implementation of the ACME protocol. This has been tested successfully with the CertBot client under Debian Linux. It does not currently work
with the dehydrated client; We submitted details to Entrust Certificate Services in February 2024 and have been advised that they will prioritise testing and resolution of the issues.
Automation with CertBot
These instruction are provided as a generic guide, but will probably need to be customised to suit your particular deployment environment. Do not run the CertBot commands without making sure you know what you are doing first - these could stop an existing
webserver from running and modify / delete critical configuration files.
- Make sure you are familiar with the ACME protocol, CertBot and the CertBot plugin for your webserver / deployment environment
- Install CertBot on your system and configure it to work with your webserver
- Obtain the Entrust EAB credentials from the ITSS wiki, and decide which email address you would like Entrust ACME notifications to be sent to. Under no circumstances may you save the EAB credentials locally - they only need to be used using the one-off registration step that follow
- Run the following command to register CertBot as an Entrust ACME client and link it to Oxford's Entrust account:
$ certbot register --server https://acme.entrust.net/acme2/directory --email <your email> --no-eff-email --eab-kid <EAB_KID> --eab-hmac-key <EAB_HMAC_KEY>
- Run the appropriate command for your environment to configure your webserver and install an initial certificate. For example:
$ certbot run --apache --server https://acme.entrust.net/acme2/directory -d domain1[,domain2[,...]]
- Test certificate renewal:
$ certbot renew --apache
- Configure automated CertBot certificate renewal as appropriate for your system
Warning: Do NOT save EAB credentials
You must not save the EAB credentials locally, either as part of a script or configuration management system. These credentials only need to be used during the one-off registration step. The credentials will be changed from time-to-time and without
notice, so you will need to obtain the latest version from the ITSS wiki each time you use them. Once you have registered your ACME client, it will have its own account and credentials, which are stored in the CertBot configuration file. You may
choose to store these as part of a secure configuration management system so that they can be validated and redeployed as required.
HTTP challenge source IP addresses
As with most ACME providers, Entrust uses a changing pool of global IP addresses to verify HTTP domain ownership challenges. It it not therefore possible to restrict access to a source IP range. However, you may choose to restrict the time when such HTTP
connections are accepted to match the period when a challenge is expected.
We are currently developing the local processes required to enable automated certificate management for our Sectigo-based service.
Warning: Do NOT save EAB credentials
You must not save the EAB credentials locally, either as part of a script or configuration management system. These credentials only need to be used during the one-off registration step. The credentials will be changed from time-to-time and without
notice, so you will need to obtain the latest version from the ITSS wiki each time you use them. Once you have registered your ACME client, it will have its own account and credentials, which are stored in the ACME client configuration file. You may
choose to store these as part of a secure configuration management system so that they can be validated and redeployed as required.
Let's Encrypt provides domain validation certificates and has a mature ACMEv2 API. You can use this to obtain and manage certificates for University services. The main difference between obtaining certificates from Let's Encrypt rather than Entrust or Sectigo is that there is no organisational approval or oversight, so your certificate has a somewhat lower level of assurance associated with it. This is unlikely to affect the operation or security of certificates used for web servers.
To use Let's Encrypt we recommend that you:
- Read the Let's Encrypt How It Works guide
- Follow the Let's Encrypt documentation in conjunction with the document for your chosen certificate automation client
Warning: Do NOT save EAB credentials
You must not save the EAB credentials locally, either as part of a script or configuration management system. These credentials only need to be used during the one-off registration step. The credentials will be changed from time-to-time and without notice, so you will need to obtain the latest version from the ITSS wiki each time you use them. Once you have registered your ACME client, it will have its own account and credentials, which are stored in the ACME client configuration file. You may choose to store these as part of a secure configuration management system so that they can be validated and redeployed as required.
HTTP challenge source IP addresses
As with most ACME providers, Let's Encrypt uses a changing pool of global IP addresses to verify HTTP domain ownership challenges. It it not therefore possible to restrict access to a source IP range. However, you may choose to restrict the time when such HTTP connections are accepted to match the period when a challenge is expected.
Severs that are not accessible from the public internet cannot employ the HTTP-based domain ownership check, but may still require a publicly valid certificate. This can usually be acheived with a DNS-based domain ownership check, and you can automate this using the Hydra API. Community-maintained details and sample scripts are available in our automated DNS-based domain ownership with Let's Encrypt guide.
Appliances that support ACME should be configurable to work with Entrust or Let's Encrypt.
Some appliances do not have any functionality for certificate lifecycle management automation, or implement protocols that none of Entrust, Sectigo or Let’s Encrypt offer. In these cases we recommend you speak to your supplier. The 90-day lifetime limit will affect those appliances for all customers, worldwide, rendering the appliances effectively end-of-life (or requiring an alternative approach) unless the OEM develops a solution.
Another option could be to sit the appliance behind a web application firewall which handles the SSL/TLS offloading. This has the side-benefit of creating an additional later of protection, noting that you may have concerns about the overall security and assurance approach of OEMs that do not provide industry-standard automated certificate management in their products.
Get support
If you cannot find the solution you need here then we have other ways to get IT support
Submit a suggestion, compliment or complaint
