Bring your own certificate

Introduction

Instead of using the default Let’s Encrypt certificate provided by Browsolate, administrators can specify their own x509 certificate and private key. This is done by uploading the certificate and key to AWS Secrets Manager and providing the ARN during the setup process.

Important Information

• Bringing your own certificate will disable automatic domain registration with Route 53 and the use of the browsolate.com domain. You are responsible for managing your own domain name and DNS settings.

Steps Overview

1. Obtain your x509 private key and certificate.
2. Concatenate the private key and certificate into a single file.
3. Upload the concatenated file to AWS Secrets Manager.
4. Retrieve the ARN of the stored secret.
5. Specify the ARN in the HttpsConfig parameter during setup (either in CloudFormation or the Marketplace).

Step 1: Obtain Your x509 Certificates

You need to have both an x509 private key and an x509 certificate ready. These should be in .pem format (or a similar format). These files are usually provided by your Certificate Authority (CA) when you purchase an SSL certificate.

• Private key: The private key associated with your domain.
• Certificate: The x509 certificate authenticating your domain, signed by a trusted CA.

Step 2: Concatenate the Private Key and Certificate

Browsolate requires the private key and certificate to be combined into a single file for ease of use. You can do this easily in a terminal.

Command to Concatenate the Files

# Concatenate the private key and certificate
cat my_private_key.pem my_certificate.pem > my_combined_cert.pem

This will create a new file called my_combined_cert.pem, which contains both your private key and certificate in the correct order.

Step 3: Upload to AWS Secrets Manager

You can now upload the concatenated file to AWS Secrets Manager. This will allow Browsolate to securely retrieve your certificate and private key during operation.

Option 1: Using the AWS Secrets Manager UI

1. Log in to the AWS Management Console.
2. Navigate to Secrets Manager.
3. Click Store a new secret.
4. In the Secret type section, choose Other type of secret.
5. In the Key/value pairs section, paste the contents of your concatenated file, which should include:
   • Private Key (beginning with -----BEGIN PRIVATE KEY-----)
   • Certificate (beginning with -----BEGIN CERTIFICATE-----)
6. Complete the remaining setup steps and click Store.

Option 2: Using the AWS CLI

If you prefer the command line, you can upload the concatenated file directly:

# Upload the concatenated certificate and private key to Secrets Manager
aws secretsmanager create-secret --name MyWebServerCert   --secret-string file://my_combined_cert.pem

The output of this command will include the ARN of the secret, which you will need later.

Step 4: Retrieve the ARN of the Secret

To retrieve the ARN of the secret you stored in AWS Secrets Manager, follow these steps:

1. Open the AWS Management Console and navigate to Secrets Manager.
2. Find the secret you created in the list.
3. The ARN will be displayed in the details of the secret. It will look something like this:

arn:aws:secretsmanager:region:account-id:secret:MyWebServerCert-xxxxxx

Copy this ARN as you will need it for the next step.

Step 5: Specify the ARN in the Setup

During the installation of Browsolate, whether through the AWS Marketplace or a CloudFormation template, you will need to provide the ARN of the secret that holds your certificate and private key.

In the CloudFormation template or the Marketplace configuration, this is specified as the HttpsConfig parameter.

Example CloudFormation Parameter

Parameters:
  HttpsConfig:
    Type: String
    Description: "ARN of the certificate and private key in Secrets Manager"
    Default: "arn:aws:secretsmanager:region:account-id:secret:MyWebServerCert-xxxxxx"

By setting the HttpsConfig parameter to the ARN of your stored secret, Browsolate will use your custom certificate and private key for HTTPS communication.