Use Let's Encrypt Certificates

Publish hosted websites with browser-trusted Banyan-managed Let's Encrypt certificates

This article describes features that require Banyan Netagent v1.37.0+.

Overview

Banyan provides three options to specify the TLS server certificate used for your Hosted Websites:

  1. Banyan PKI (default) - Banyan manages a Private PKI (Public Key Infrastructure), also known as an Internal Certificate Authority, for your organization named {orgname} Banyan Private Root CA. By default, Hosted Websites use a TLS server certificate issued by this Private PKI, and require devices be registered and possess a trusted device certificate.

  2. Custom Certificates - You may procure and upload your own Public or Private CA issued server certificate onto the Access Tier VMs in lieu of using the Banyan PKI, via our Custom Certificates capability. This option enables you to use default-browser-trusted certificates but requires additional configuration and ongoing management of the certificates.

  3. Let’s Encrypt Certificates - In this option, Hosted Websites use a TLS server certificate issued by the free and open CA, Let’s Encrypt and Banyan manages issuance, renewal, and revocation of the certificates. Let’s Encrypt certificates are browser-trusted by default, providing better support both registered and unregistered devices connecting to Banyan-secured services.

To use Banyan-managed Let’s Encrypt certificates, you must follow the steps below to first register your specific Hosted Website domain with Banyan before publishing it to your end-users.

How It Works

Banyan leverages Let’s Encrypt and the ACME protocol to configure the Access Tier and the Cloud Command Center automatically obtain browser-trusted certificates from a Public CA without any human intervention.

A key element of the ACME protocol is a domain validation procedure which allows infrastructure software to obtain certificates without user interaction. In Banyan, this procedure is called Domain Registration. Once your domain is registered via the Banyan Command Center, we facilitate procurement and management of TLS server certificates that auto-renew every 90 days (or sooner). Read more about how Let’s Encrypt works at the Let’s Encrypt tutorial.

Please note in mind that Banyan does not issue Let’s Encrypt certificates for the following:

Steps

At a high level, you will:

Prerequisites

Before proceeding through the steps below, ensure you have configured a Register Domain. In order to publish a Hosted Website that uses a Let’s Encrypt certificate, its Service Domain Name must match your Registered Domain patterns.

Ensure you have set up a Registered Domain that points to the applicable Access Tier for your Hosted Website.

You can set up an individual CNAME records as well as wildcard CNAME records:

*.yourdomain.com   CNAME access_tier_site_address.iaas.com
foo.yourdomain.com CNAME access_tier_site_address.iaas.com

Ensure you have set up a Registered Domain for your Hosted Website. You may need to configure a Custom Domain if your Hosted Website uses an FQDN that doesn’t fall under your Banyan-provided Org Domain.

If you’re using a custom domain, you can set up an individual CNAME records as well as wildcard CNAME records:

*.yourdomain.com   CNAME *.orgname.banyanops.com
foo.yourdomain.com CNAME *.orgname.banyanops.com

Step 1. Confirm your Registered Domain status is Verified

1.1 In the Banyan Command Center, navigate to Directory & Infrastructure > Registered Domains, and click on the Registered Domain you will use for your Hosted Website.

1.2 Ensure that the domain status for your Registered Domain shows Verified.

You may use wildcards (such as *.example.com) while registering your domains; however, Let’s Encrypt certificates can only be issued to single-domain web services and not multi-domain (aka wildcard) web services.

Step 2. Configure your Hosted Website to Obtain a Let’s Encrypt Certificate

2.1 Navigate to Manage Services > Hosted Websites, and then click + Register Service and select the Standard Website template.

2.2 Configure the Service Details, such as name, description and link shown to end users, icon, and cluster.

3.3 Configure the Service Attributes accordingly. Ensure you click the Let’s Encrypt checkbox and enter a Service Domain Name that matches a domain configured in Step 1.3.

Multi-domain (Wildcard) Web Services cannot be used in conjunction with Let’s Encrypt. If your organization would like to configure a wildcard web service, you must use a certificate issued via Banyan PKI or a Custom Certificate.

2.3 Optionally, attach a policy.

2.4 Click Register Service.

Step 3. Review the Certificate Status

3.1 While still on the Directory & Infrastructure section, navigate to Issued Certificates.

3.2 Ensure the domain’s certificate status is Verified.

Certificates can have a status of Verified, Pending, or Failed. Please allow up to 10 minutes while we validate the domain and procure the certificate.

That’s it! You have successfully obtained a Let’s Enrypt certificate for your hosted website.


Notes

Certificate Status is Failed

Sometimes, you may see a certificate issuance failure when publishing a Hosted Website that uses a Let’s Encrypt certificate. A common error message is:

failed_reason: "error: one or more domains had a problem: [foo.example.com] [foo.example.com] acme: error presenting token: time limit exceeded: last error: Get "http://foo.example.com/.well-known/acme-challenge/Kv42PobsQ-ggnPiosH1HYt35QwFiTd2CfW-dXNAnyxk": dial tcp 35.247.123.123:80: connect: connection refused"

This is typically because the ACME protocol requires the Netagent to respond to a HTTP request from the Let’s Encrypt CA at the path .well-known/acme-challenge/ on Port 80 but traffic isn’t reaching the Netagent and times out.

Ensure that the Access Tier can receive traffic from the internet on Port 80, and that the Netagent binary is listening on that port. You can confirm by issuing a curl to the domain name of the your Hosted Website. You should get a 302 redirect to the corresponding HTTPS path.

curl http://foo.example.com/bar
<a href="https://foo.example.com/bar">Found</a>.

Another common error message is:

couldn't verify challenge for domain: foo.example.com, token: rIrwHK-Q2t6L64aYctU3ovCS7_Y1-BDdkRClw5gcMdw, err: time limit exceeded: last error: couldn't verify challenge
[INFO] [foo.example.com] acme: Could not find solver for: tls-alpn-01

In this case, ensure that you’re on Banyan Netagent v1.37.0+ in order for the Let’s Encrypt certificate issuance to succeed.

Confirm which CA is Used

You can confirm what type of certificate is being used by your Hosted Website by clicking on the lock icon on your browser’s URL bar. Select Certificate Details to see more information about the server certificate, and note the Issuer specifics.

When a certificate is issued by the Let’s Encrypt CA, the Issuer Common Name will be R3 and the Organization will be Let's Ecnrypt.

In contrast, when a certificate is issued by Banyan’s Private PKI, the Issuer Common Name will be {orgname} Banyan Private Root CA.



Last modified: Sep 28, 2021