China CloudFront SSL Plugin

What does this solution do?

Solution Overview

Close

Architecture Overview

Deployment Guide

• 1. Deploy Solution
  

  1.1 Initialize Deployment
  

  Click on the link (link), which will then jump to the China region CloudFormation console to create the stack. Then click the [Next] button at the lower right corner.
  

  

  1.2 Input Deployment Details
  

  Please specify stack details for the following parameters.

  • Stack Name: Specify a name for the stack.
    
  • Email: Input your Email address to receive SNS notification, so that you can know about your certificate issue and renewal status. Only one address is supported here.
    
  • Domain Name：Your domain names for applying SSL certificate. Use commas (,) to separate multiple domains. eg.: www.example.cn,exmaple.cn,*.example.com.
    
  • SSL Renew Interval Days: Default is 80 days. SSL certificate issued by Let’s Encrypt gets expired after 90 days. Please make sure the number is between 1 - 89 so that the certificate can be renewed on time.

  After confirming the information, please click Next to go directly to step 4 to review stack.

  

  1.3 Confirm Deployment
  

  Please confirm your deployment information on the page and check the "I acknowledge" box at the bottom of the page. Then click the [Submit] button at the bottom right corner to submit stack deployment.
  

  

  When the submission is complete, you will see the resources in the stack being created one by one in the event bar for that stack. Wait about 3 minutes.
  Once submitted deployment, you will see resources being created in the stack. Stack deployment will take about 3 minutes.

  1.4 Subscribe to Amazon Simple Notification Service (SNS)
  

  Please check your mailbox while waiting for stack deployment. You should receive an email confirmation from no-reply@sns.amazonaws.com for SNS subscription. Please click on the confirm subscription link as soon as possible in order to receive timely notifications from SNS. Otherwise you may miss your first certificate issuance.
  

  

  You should see the following prompted out after you successfully subscribed to SNS.
  

  

  1.5 Check Stack Deployment Progress
  

  Once the subscription is complete, you can return to the stack and continue to check stack status. Stack deployment is succeeded when stack status changed to CREATE_COMPLETE.
  We provided some useful links in the Output section of the stack:

  • CloudfrontConsole: Check IAM SSL certificate and use it in Amazon Cloudfront.
    
  • ManagementWebURL：URL to access the SwaggerUI. You can check all the existing certificates and delete certificates from this SwaggerUI.
    
  • S3BucketURL：URL of the S3 bucket that contains the generated SSL certificate generated. You can download the certificates from S3 if needed.

  

  1.6 Configure CloudFront Distribution to Use SSL Certificate
  

  Once stack deployment is completed, an SSL certificate will be automatically requested for your domain name. If you have subscribed to SNS topic timely, you would receive an email notification from no-reply@sns.amazonaws.com informing you that the SSL certificate was successfully issued. The certificate name is a combination of the stack name and the expiration date. For example, Certbot-2023-11-14-1540. The number after the stack name means that the certificate will be expired at 15:40pm, Nov 14, 2023.

  

  Open CloudFront console, create or select your existing distribution and edit your settings. 
  

  

  Please fill in the Alternate Domain Name with the domain name for which you are applying for an SSL Certificate, and then select the corresponding SSL Certificate in the Custom SSL Certificate drop-down menu. Then save your changes.
  

  

  Once the changes are saved, you can access the site accelerated by Amazon CloudFront from your browser, and view information about your SSL certificate issued by Let's Encrypt. The certificate is valid for 90 days.
  

  

• 2. SSL Certificates Download, Update and Management
  

  2.1 Certificates Download
  

  Please use the output of the cloudformation stack (S3BucketURL) in Step 5 of the manual to directly jump to corresponding SSL certificate bucket, and select the SSL certificate file you need to download.
  

  Note: last_iam_ssl_info.txt is used to store the last generated certificate information to match the bound Amazon CloudFront information. Do not modify or delete this file.
  

  

  Unzip the downloaded files mentioned above and access the folder in the/tmp/certbot/config/archive/ssl path in th unzipped folder to see the generated SSL certificate, certificate private key, certificate chain, and other files.
  

  

  2.2 Tips for SSL certificates automatic update
  

  This solution can automatically update the SSL certificate before it expires, and automatically replace the certificate already associated with Amazon CloudFront based on the ID and certificate name generated from the previous certificate.
  

  Note: Each generated free certificate has a validity period of 90 days. After the first SSL certificate is generated, a new certificate will be automatically generated through the rules of Amazon Eventbridge after the specified number of days (default is 80 days), and a notification email will be sent indicating the successful issuance of the SSL certificate and the update record of Amazon CloudFront SSL certificate.
  

  

  Please read this email carefully and pay attention to the following:

  • If the certificate update is successful, the certificate stored in the IAM SSL storage will be automatically deleted to save the limit, but the backup certificate in the Amazon S3 bucket will not be deleted.
    
  • If the certificate issuance fails or the Amazon CloudFront SSL certificate update fails, please replace it manually in a timely manner to avoid interruption of your website access.

  The description of updating the data structure of records:

  • Get_Last_IAM_SSL_Info: The last_iam_ssl_info.txt in S3 bucket, from the last SSL certificate issued information.
    
  • Matched_CloudFront: Based on the SSL certificate information issued last time, match the Amazon CloudFront assigned ID.
    
  • Update_CloudFront_Status: Please compare the update status of Amazon CloudFront with the matching Amazon CloudFront ID information.
    
  • Delete_Last_IAM_SSL_Cert: f there are no matching Amazon CloudFront assignments or if both have been successfully updated, the last issued SSL certificate will be automatically deleted.

  2.3 SSL Certificates Management (Option)
  

  The following optional content includes querying the list of generated SSL certificates and deleting SSL certificates.
  If due to reasons such as certificate update failure, you may need to manually delete the certificate. The ManagementWebURL prompted in the Output after the deployment of the browser access stack is completed

  

  Certificate query generated: Select the List API, click "Try it out" → Execute, and all information stored in the IAM SSL certificate will be listed.
  

  

  

  You can find the expired SSL certificate and copy the SSL certificate name.
  

  

  Certificate deletion: Click on the Delete API, paste the name that has just been copied and replace the certName, and trigger the API execution. You will see the following prompt message, indicating successful deletion.
  

  

  

  

• FAQ and Troubleshooting
  

  FAQ
  

  • How many certificates can be generated for one domain, and 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 per duplicate domain per week. For more details, please refer to the documentation: Rate Limits, Duplicate Certificate Limits.
      
      
  • How many SSL certificates can be stored in IAM?
    
    • According to Amazon Web Services documentation, there is a limit on the number of server certificates that can be stored in IAM. By default, each account cannot upload more than 20 SSL certificates. This limit can be raised to 1000. To increase the limit, please visit the "Server certificates per account" link in the documentation.
      
      
  • What should I do if I can't access the SSL management interface?
    
    • Please ensure that you have completed the ICP filing process. If you deployed this solution before completing ICP filing, you might need to redeploy the solution.

  Troubleshooting
  

  • How do I delete stack resources / What should I do if I encounter an error during stack deletion?
    
    • Please ensure you empty the contents of the corresponding Amazon S3 bucket before deleting the stack.

  

  • The certificate has been issued, but I haven't received the certificate issuance notification. What should I do?
    
    • If this is your first time deploying the stack, you might miss the notification due to delayed confirmation of subscription. If you haven't received the certificate update notification, ensure that you have received the subscription email and clicked on the confirmation link. You can search for "SNS::Topic" on the stack's resource tab to find the corresponding notification service and check its confirmation status.

  

  

  • If I have confirmed the subscription status but still haven't received the issuance/update emails, what should I do?
    
    • If there was an error during the issuance process, you can check the logs of the Certbot Lambda Function. If the automatic triggering rule wasn't executed successfully, please review the Amazon EventBridge monitoring.
      
  • If the received email contains error information, how can I troubleshoot?
    
    • You can check the logs of the Certbot Lambda Function.
      
  • How can I view Lambda Function log information?
    
    • You can use CloudWatch log monitoring. Search for "Lambda::Function" on the stack's resource tab and select the Function starting with CertBot.

  

  • After clicking related Physical ID to enter Lambda Function, on the Monitor tab at the bottom of the page, click "View CloudWatch Logs" on the right side.
    

  

  • Based on the trigger time, navigate to the Log Streams tab at the bottom of the page, and click related log stream item to access the log information and troubleshoot the runtime logs.
    

  

  • How do I view Amazon EventBridge monitoring?
    • On the stack's resource tab, search for "Events::Rule" select the rule starting with CertScheduledRule, click to enter, navigate to the Monitoring tab, and select the desired time range to view Invocation status.

  

  

  • How can I manually trigger certificate issuance or renewal?
    • You can manually trigger the SSL certificate issuance/renewal process by clicking "Test" in the Lambda Function. On the stack's resource tab, search for "Lambda::Function," and select the Function starting with CertBot.
      

  

  • Afterward, on the "Test" tab, click the orange "Test" button to complete the manual certificate issuance process.
    

  

  • You can also reach out for assistance through the "Contact Us" option.
    

  Reference Documents
  

  • 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/