China CloudFront SSL Plugin

What does this solution do?

Solution Overview

Close

Architecture Description

Operation Manual

• Step 1 - Solution Deployment
  

  1. Initialize Deployment
  

  Deploy the template through the CloudFormation service by clicking this deployment link , which will redirect you to the China Region CloudFormation console to create a stack. Click [Next] in the bottom right corner.

  2. Enter Deployment Parameter
  

  Specify details for the stack, paying attention to the following parameters:
  

  • Stack Name: Name your stack, for example "cloudfront-ssl-plugin-v2". The stack name must be unique within the region for your current account.
  • Access Key: Specify an Access Key as the key for your API Gateway. The API Gateway key ensures that only authorized users can call backend functions through the API Gateway.

  

  After confirming the information, click Next to proceed to Step 3 "Configure Stack Options".

  3. Confirm Deployment Information
  

  At the bottom of the current page, check the "I acknowledge" box in the blue window, and then click "Next" in the bottom right corner to proceed to Step 4 "Review and Create".

  

  Please review your deployment information on the current page. After confirming all details are correct, click the "Submit" button in the bottom right corner of the page to submit your deployment.

  

  After submitting, you will see in the stack events panel that the resources within the stack are being created one after another. Wait for approximately 1 minute, and when the stack status changes to CREATE_COMPLETE, the creation process is finished.
  

  4. View Stack Outputs
  

  You can view quick links provided by the solution in the stack's "Outputs" tab:
  

  • CloudfrontConsole: Access the Amazon CloudFront console to quickly bind the issued certificates
  • ManagementWebURL: Access the certificate management frontend page, where you'll see the frontend page with no project data and a dialog box for entering the key.

  

  You can view the created resources by clicking on the Resources tab, which includes Lambda function resources with main functions as shown in the following table.

  

  Lambda Functions and Their Corresponding Features
  

  Lambda Function Name	Feature	Lambda Function Name	Feature
  AddEmail	Add notification email addresses for a specified project	DeleteProject	Delete certificate issuance project and associated sub-stacks
  Authorizer	Management interface and API authentication	Frontend	Function for running the frontend management page
  CheckCertState	Search DynamoDB by project name to get the latest certificate issuance status	GetCertByPath	Get associated information for all certificates under a certificate path
  CheckStackState	Get the status of associated stacks by project name	GetMailByProject	Get associated email addresses by project name
  DataProvider	Get homepage data and list items	Master	Create certificate issuance stack based on project name, email address, and other information
  DeleteCert	Input certificate name and delete it	TriggerCertbot	Trigger certificate issuance function, used for manually renewing certificates
  DeleteEmail	Delete notification emails for a specified project by inputting email address	UpdateProject	Update project information, i.e., related information of the certificate issuance stack

• Step 2 - Project Creation
  

  1. Access the Certificate Management Page
  

  In the stack "Output" tab, find the ManagementWebURL, click on the URL link to enter the certificate management page.
  

  

  Enter the access key (the Access Key specified in the parameters when creating the stack) to enter the certificate management page for operations.
  

  

  2. Create a New Project
  

  Click on any of the "Create New Project" buttons
  

  

  In the "Create New Project" dialog box, specify the following parameters:
  

  • Project Name: Cannot be the same as other projects in the project list
  • Domain(s) (separated by commas): All domains involved in the project (separated by commas), for which we will apply for SSL certificates.
  • Email: Email used to receive certificate issuance information. Only one email can be specified during the project creation stage, more emails can be added later.
  • SSL Certificate Renewal Interval (days, 1-89 days, 30 days recommended): Specify an integer as the SSL certificate renewal interval, the default value is 30.

  After specifying all parameters, click [Create] in the bottom right corner to start creating the project.
  

  

  After clicking "Create Project," the certificate management platform will create a stack dedicated to this project in your account. Resources created in the stack include Lambda functions for issuing/renewing SSL certificates, EventBridge rules, SNS topics for sending certificate issuance status, and more.
  

  3. Subscribe to Notification Service Promptly
  

  During the project creation process, you will receive an email from in your inbox, inviting you to subscribe to the SNS topic. Please check your inbox while waiting for the stack deployment and click the subscription confirmation link as soon as possible to receive SNS notifications in a timely manner, otherwise you may miss information about the first certificate issuance.
  

  

  After successful subscription, the prompt will be as follows.

  

  4. Check Stack Deployment Progress

  After completing the subscription, you can return to the certificate management page to check the project creation progress. You can also view the stack status in the CloudFormation console. When the certificate management page displays "Succeeded," or when the <project name>-CertBot stack status in the CloudFormation console shows CREATE_COMPLETE, it indicates that the project has been created successfully.

  

  

  5. Check Certificate Issuance Status

  If you subscribed to the notification service in Step 3 in a timely manner, shortly after the project is successfully created, you will receive an email from <no-reply@sns.amazonaws.com>. The email will display the certificate issuance status and CloudFront update information. If the certificate is successfully issued, the email will show the certificate name and ID. The certificate name consists of the stack name and the SSL certificate expiration time. For example: certificate name WebApp-2025-04-28-1324 corresponds to a certificate expiration time of April 28, 2025, at 1:24 PM.

  

  After the certificate is successfully issued, you can find the corresponding certificate in the CloudFront console using the certificate name/certificate ID. The next step is to bind CloudFront with the successfully issued SSL certificate.

  6. Bind SSL Certificate in Amazon CloudFront Console
  

  Open the CloudFront console, create or select your existing distribution, and find the option to edit alternate domain names and SSL certificates.

  

  In the settings menu, enter the domain name for which you applied for the SSL certificate in the "Alternate Domain Names" field, and select the corresponding SSL certificate from the "Custom SSL Certificate" dropdown menu. Then save the changes.

  

  After deployment is complete, you can access the site accelerated by Amazon CloudFront through the alternate domain name from your browser, and view the SSL certificate information issued by Let's Encrypt.
  

  

• Step 3 - Project Management and Certificate Management
  

  1. Project Management
  

  1.1 View Project Basic Information
  

  

  The specific meaning of each column is as follows:
  

  • Domain: The collection of domains involved in the project, which are also the domains for which you apply for SSL certificates.
  • Certificate List: Basic information about all certificates for the current domain, including certificate name, certificate ID, update time (certificate issuance time), and expiration time.

  

  • Certificate Issuance Status: Click to view the record of the last certificate issuance status.
  • Update Time: The most recent update time among all certificates owned by this domain.
  • Expiration Time: The most recent expiration time among all certificates owned by this domain.
  • S3 URI: The S3 directory that stores all certificates for this project. When you enter this directory, you can see compressed files named after the certificate issuance time. Download and extract this file to get a folder named "tmp".

  

  • Access the path /tmp/certbot/config/archive/ssl in the extracted folder to see the generated SSL certificate, certificate private key, certificate chain, and other files.
    

  

  • Notification Email List: All email addresses that have subscribed to the message notification service.
    

  

  • Stack Status: The status of the stack for this project, consistent with the stack status displayed in the CloudFormation console. Each project corresponds to one stack, which contains Lambda functions responsible for certificate issuance and renewal for the project, EventBridge rules, message notification services responsible for sending certificate issuance status, etc.

  1.2 Modify Project
  

  Select the project you want to modify, and click [Modify Project] in the upper right corner to make changes to the project.
  

  

  After each project modification, an SSL certificate will be reissued. The parameters that can be modified include:
  

  • Domain name: Note that the modified domain name must include the domain name before modification, otherwise the newly issued SSL certificate after modification will not include the previous domain names, which may cause a mismatch between the SSL certificate and the website domain name.
  • SSL certificate renewal time interval

  

  The successful result of the update record is shown in the figure:

  

  The meaning of the data structure is as follows:
  

  • Previous_IAM_SSL_Info: Information about the previously issued SSL certificate.
  • Matched_CloudFront: The Amazon CloudFront distribution ID matched using the previously issued SSL certificate information. In the example below, the previously issued certificate was already bound to a CloudFront distribution starting with "E", so the Matched_CloudFront field contains the ID of that CloudFront distribution.
  • Update_CloudFront_Status: Amazon CloudFront update status, please compare with the matched Amazon CloudFront ID information. In the example below, the CloudFront distribution starting with "E" has an update status of "Success", indicating that the certificate for that CloudFront distribution has been replaced with the latest certificate.
  • Delete_Previous_IAM_SSL_Cert: If there are no matching Amazon CloudFront distributions or all Amazon CloudFront distributions have been successfully updated, the previously issued SSL certificate will be automatically deleted. In the example below, since the new certificate was successfully issued and the Amazon CloudFront distribution was successfully updated, the status of the old certificate in the Delete_Previous_IAM_SSL_Cert field is successfully deleted.

  1.3 Deleting a Project
  

  Before deleting a project, you need to check whether the certificates in the project are associated with CloudFront distributions. If associations exist, you must first remove these associations. After ensuring all associations are removed, manually delete all certificates from the certificate list; otherwise, the project cannot be deleted.

  

  After all certificates in the project have been deleted, select the project you want to delete, and click "Delete Project" in the upper right corner.

  

  Enter the project name and then click "Delete" in the lower right corner.

  

  After clicking delete, the project's data and stacks will also be deleted.
  

  

  After successful deletion, you will see a prompt on the certificate management page as shown in the figure below.

  

  2. Certificate Management
  

  2.1 Automatic Certificate Renewal
  

  This solution can automatically renew SSL certificates before they expire, and automatically replace the certificates associated with Amazon CloudFront based on the ID and certificate name generated from the previous certificate.
  Note: Each generated free certificate is valid for 90 days. After the initial SSL certificate is generated, a new certificate will be automatically generated after a specified number of days (default is 30 days) through Amazon EventBridge rules, and a notification email will be sent regarding the successful SSL certificate issuance and Amazon CloudFront SSL certificate update record.
  
  Email addresses subscribed to the SNS topic will receive a message about the certificate issuance status and CloudFront update information.
  

  

  The meaning of each field in the certificate issuance status in the email is as follows:
  

  • Previous_IAM_SSL_Info: Information about the previously issued SSL certificate.
  • Matched_CloudFront: The Amazon CloudFront distribution ID matched through the previously issued SSL certificate information.
  • Update_CloudFront_Status: Amazon CloudFront update status, please compare with the matched Amazon CloudFront ID information.
  • Delete_Previous_IAM_SSL_Cert: If there is no matching Amazon CloudFront distribution or all Amazon CloudFront updates have been successful, the previously issued SSL certificate will be automatically deleted.

  Please read this email carefully and note the following:
  

  • If the certificate is updated successfully, the certificate stored in IAM SSL storage will be automatically deleted to save quota, but the backup certificate in the Amazon S3 bucket will not be deleted.
  • If certificate issuance fails or Amazon CloudFront SSL certificate update fails, please replace it manually in time to avoid interruption to your website access.
  • The CloudFront SSL Certificate Renew Records in the email is a JSON object containing CloudFront certificate update information displayed on the certificate management page, and the meaning of each field is described above.

  If you encounter certificate issuance failure during automatic certificate renewal, please resolve the associated issues, and it is recommended that you manually issue a certificate following the steps in section 2.2.
  

  2.2 Reissue Certificate
  

  In the certificate list, click [Reissue] in the upper right corner and click [Confirm] in the pop-up window.

  

  

  After clicking confirm, the certificate management page will trigger a Lambda function to issue the certificate and replace the certificate bound to CloudFront with the newly issued certificate. You can see the execution progress of this Lambda function on the certificate management page.
  

  

  When the certificate management page displays "Succeeded", it indicates that the certificate has been successfully issued. The JSON object below records the information about the CloudFront certificate update.
  

  

  The meaning of the data structure is as follows:
  

  • Previous_IAM_SSL_Info: Information about the previously issued SSL certificate.
  • Matched_CloudFront: Amazon CloudFront distribution IDs that match the previously issued SSL certificate information.
  • Update_CloudFront_Status: Amazon CloudFront update status, please compare this with the matched Amazon CloudFront ID information.
  • Delete_Previous_IAM_SSL_Cert: If there are no matching Amazon CloudFront distributions or all Amazon CloudFront distributions have been successfully updated, the previously issued SSL certificate will be automatically deleted.

  Similarly, email addresses subscribed to the SNS topic will receive an email about the certificate issuance status and CloudFront update information.
  

  2.3 Deleting a Certificate
  

  In the certificate list, select the certificate you want to delete, click [Delete Certificate] in the upper right corner, and then enter the certificate name in the popup window before clicking [Delete].
  

  

  

  Note: Before deleting a certificate, please ensure that no CloudFront distribution is bound to the certificate. Otherwise, the deletion operation will result in a 500 error as shown in the image below, and the deletion cannot proceed.

  

  3. Managing Subscription Emails
  

  When creating a project, you can specify an Email to receive certificate issuance and update information. Later, you can click on "x Email subscriptions" in the notification Email list to manage the Email addresses subscribed to the message notification service.
  

  

  3.1 Adding Email
  

  After clicking "x Email subscriptions", a pop-up window titled "Email Notification List" will appear as shown in the image. Click [Add Email].
  

  

  Enter the Email address you want to add in the box, such as somebody@example.com, then click [Add].
  

  

  After clicking add, you will see that the status of the Email address somebody@example.com is "PendingConfirmation".
  

  

  Later, you will receive a subscription invitation email from in the somebody@example.com mailbox. Click "Confirm subscription" to confirm the subscription.
  

  

  After successful subscription, you can see the page shown in the image below.
  

  

  Return to the certificate management page and click the refresh button in the top right corner. We can now see that the subscription status has changed to "Confirmed".
  

  

  3.2 Resend Confirmation Email
  

  If the subscription invitation email was accidentally deleted before confirming the subscription, you can select that Email address and click [Resend Confirmation Email].
  

  

  3.3 Delete Email
  

  Select the Email address you want to delete, then click [Delete Email] in the top right corner.
  

  

  Enter the Email address you want to delete in the dialog box for confirmation, then click [Delete] in the bottom right corner.
  

  

• Common Questions and Troubleshooting
  

  Common Questions
  

  • How many certificates can be generated for one domain name? Are there rate limits?
    According to Let's Encrypt documentation, you can issue up to 50 certificates per registered domain per week, and up to 5 certificates for duplicate domains per week. For details, please check the documentation: https://letsencrypt.org/docs/rate-limits/.
  • How many SSL certificates can be stored in IAM?
    According to documentation, there are limits on certificates in the IAM service. By default, each account cannot upload more than 20 SSL certificates. This quota can be increased to 1,000. Please click the link "Server certificates per account" to submit an IAM certificate quota request.
  • What if I cannot access the certificate management interface?
    Please ensure you have completed the ICP filing process. If you deployed this solution before completing the ICP filing, you may need to redeploy the solution.

  Troubleshooting Certificate Issuance Process
  

  During new project creation, certificate reissuance, or automatic certificate renewal operations, the backend will submit certificate issuance requests and update the certificates bound to CloudFront distributions (removing the association between CloudFront distributions and old certificates and binding them to new certificates). During this process, you may encounter the following common errors:
  
  

  • Error message: "acme.messages.Error: urn:ietf:params:acme:error:rateLimited :: There were too many requests of a given type ::"

  If you see an error message as shown in the image below on the certificate management page:
  

  

  Or if you see a similar error message in an email:
  

  

  This indicates that you have applied for certificates for your domain 5 times within a short period (exceeding Let's Encrypt's limit of issuing only 5 certificates per week for repeated domains), therefore the certificate issuance request failed.
  

  • The email shows that the certificate application was successful, but the Delete_Previous_IAM_SSL_Cert field in the CloudFront update record in the email or certificate management page shows "Delete_IAM_Cert_Error: ..." or "Delete_SSL_Res_Error: ..." information

  This information indicates that the backend failed to delete the old certificate in the IAM Certificate service. The reason for the failure can be found in the specific content after "Delete_IAM_Cert_Error:" or "Delete_SSL_Res_Error:".
  

  • The email shows that the certificate application was successful, but the Matched_CloudFront field in the CloudFront update record in the email or certificate management page shows "Error"

  This indicates that the backend encountered an error while searching for CloudFront distributions bound to the old certificate. The reason for the failure can be found in the specific content of the "Error" field.
  

  • The email shows that the certificate application was successful, but the Update_CloudFront_Status field in the CloudFront update record in the email or certificate management page shows "Failed"/"Update_Dist_Error"/"Get_Dist_Error"

  If in the Update_CloudFront_Status field, content other than "Success" appears after a CloudFront distribution ID (such as "Failed"/{"Update_Dist_Error": "..."}/{"Get_Dist_Error": "..."}), it indicates that the backend encountered an error when updating the certificate for that distribution.
  

  • If there are error messages in the email that are not mentioned above, how should I troubleshoot?
    You can check the execution logs of the Certbot Lambda Function. The specific method is as follows:

  1. In the resources tab of the stack, search for "Lambda::Function" and select the Function that begins with CertBot.
  

  

  2. After clicking into the function, go to the monitoring tab at the bottom of the page, then click on "View CloudWatch Logs" on the right side.

  

  3. Based on the trigger time, look at the log streams tab at the bottom of the page and click to view the log information to troubleshoot the execution logs.

  

• Other Troubleshooting
  

  What if I get an error message during the stack deletion process?
  Please empty the contents of the corresponding Amazon S3 bucket first, and then proceed with deleting the stack.

  

  What should I do if the certificate has been issued but I haven't received the certificate issuance notification?
  If you are creating a project, you may miss the notification because you confirmed the subscription too late. If you haven't received information about certificate updates, please make sure you have received the subscription email and clicked to subscribe. You can search for "SNS::Topic" in the resource tab of the stack to find the corresponding notification service and check the confirmation status.

  

  

  • What should I do if I've confirmed the subscription status but still haven't received the issuance/renewal email?
    If an error occurred during the issuance process, you can check the execution logs of the Certbot Lambda Function. If the issue is due to the automatic trigger rule not executing successfully, please check the Amazon EventBridge monitoring.
  • How do I check Amazon EventBridge monitoring?
    In the resources tab of the stack, search for "Events::Rule", select the rule starting with CertScheduledRule, click to enter, and view the monitoring tab. Choose the time period to check the Invocation status.

  

  

  • You can also get help with your issues through "Contact Us".

  Reference Documentation
  

  •  https://letsencrypt.org/zh-cn/how-it-works/
  • https://letsencrypt.org/zh-cn/docs/challenge-types/
  • https://certbot.eff.org/pages/about
  • https://certbot-dns-route53.readthedocs.io/en/stable/
  • https://letsencrypt.org/zh-cn/docs/