Installation

• 1: Marketplace installation
• 2: CloudFormation installation
• 3: Installation parameters
• 4: Network security
• 5: Custom themes
• 6: Bring your own certificate
• 7: Configuring a proxy
• 8: STUN & TURN services

1 - Marketplace installation

When setting up Browsolate from AWS Marketplace, several parameters can be configured to customize the solution to fit your organization’s requirements.

These parameters affect security, performance, session handling, and the overall behavior of the service.

See Installation parameters to learn more.

2 - CloudFormation installation

This guide is targeted at developers and system administrators who need to install Browsolate using AWS CloudFormation. This installation method is required for certain configurations and license agreements.

Prerequisites

1. License Key: You will need a valid license key, which you will enter during the deployment process.
2. CloudFormation Template Location: An S3 location containing the CloudFormation templates will be provided to you, along with any specific configuration instructions related to your contract.
3. AWS Permissions: Ensure that the deploying user has the necessary AWS IAM permissions, as outlined below.

Security and Template Inspection

For security assurance, you are encouraged to inspect the provided CloudFormation templates to review settings, including role and IAM policies.

Required AWS Permissions

The following AWS IAM permissions are required for deploying Browsolate via CloudFormation:

• AmazonEC2ContainerRegistryFullAccess
• AmazonEC2FullAccess
• AmazonECS_FullAccess
• AmazonSSMReadOnlyAccess
• AWSCloudFormationFullAccess
• AWSLambda_FullAccess
• CloudWatchLogsFullAccess
• IAMFullAccess

Installation Steps

1. Deploying the Template: Using the AWS Management Console, AWS CLI, or SDK, initiate the CloudFormation template deployment using the provided S3 URL.

2. Parameters: Follow the parameters listed in the Installation Options Documentation to configure the template. Additionally, you will need to pass your secret key, provided in your installation email. Ensure you check this email for any additional installation notes or customer-specific instructions.

3. Deployment Verification: Once the deployment is complete, check the Outputs section in the CloudFormation template. Here you will find URLs, deployment details, and other relevant configuration information.

4. DNS Propagation: If using a browsolate.com domain, DNS propagation may take some time. To monitor the progress, consult the CloudWatch logs.

Testing the installation

If you enabled the Launcher UI you can use the built-in example page to create and launch arbitrary URLs. The URL of the Launcher will be published in the Outputs section of the CloudFormation deployment.

NOTES

• By default, the Launcher UI is hosted on port 5443. Access to this port in controlled by the Public API Enabled installation parameter, and the security group tagged Browsolate-PublicSecurityGroup, which you can customise to control access to the Launcher UI.
• The username for the Launcher UI is b8admin .
• The password in configured at installation by the Management Password parameter.

3 - Installation parameters

When setting up Browsolate using AWS Marketplace or AWS CloudFormation, several parameters can be configured to customize the solution to fit your organization’s requirements. These parameters affect security, performance, session handling, and the overall behavior of the service. Below are detailed explanations of each parameter group and the associated options.

Parameter Groups

Administration

Management Password

This parameter sets the password used to access management APIs. If left blank, management pages such as KeyManager and Launcher will not be enabled.

• MGMTPasswd
  • Type: String
  • Default: '' (blank)

Enable Launcher UI

Determines whether the launcher page, which is the interface users interact with to initiate isolated sessions, is enabled. Disabling the launcher UI may be useful if you’re directly controlling session creation through APIs.

• LauncherUI
  • Type: Boolean
  • Default: true
  • Allowed Values: true, false

Enable Encryption Keys Management UI

This parameter determines whether the encryption key management page is enabled.

• UrlEncryptionKeysManagerUI
  • Type: Boolean
  • Default: true
  • Allowed Values: true, false

Custom Theme CSS ARN

Specifies the Amazon Resource Name (ARN) of a custom CSS file that contains themes to modify the look and feel of the Browsolate user interface. This allows you to brand the user interface with your company’s identity or create a custom experience for your users.

• ThemeCSS
  • Type: String
  • Default: ''

Public API Access

Controls whether the API ports (default 5443) are publicly accessible. Setting this to true allows external users to access the APIs, which might be useful for testing or other use cases. For production environments, you may want to restrict access by setting it to false.

• PublicAPIAccess
  • Type: Boolean
  • Default: false
  • Allowed Values: true, false

Session Configuration

Session Maximum Duration

This parameter defines the maximum allowed duration for a single user session, in seconds. After the specified duration, the session will automatically end, helping to prevent long, inactive sessions and optimize resource usage.

• Duration
  • Type: Number
  • Default: 600 (10 minutes)

Session Dead Time

Sets the maximum period (in seconds) during which a session can remain inactive before being terminated. This is useful in cases where a user leaves a session open but inactive, allowing resources to be reclaimed after the dead time has passed.

• Deadtime
  • Type: Number
  • Default: 90 (seconds)

System Configuration

Proxy Server URL

URL for the proxy server that will be used to route user traffic. This can include authentication credentials within the URL if required (e.g., https://user:password@proxy.example.com). Setting a proxy server allows you to route traffic through a secure or anonymized network.

• Proxy
  • Type: String
  • Default: ''

EC2 Instance Type

Determines the type of EC2 instance used to host Browsolate. The instance type you choose affects the computational power and memory available, which can impact the performance of the service. You need to ensure that the instance type you specify is available in your AWS region. Choose a larger instance for higher performance and scalability.

• InstanceType
  • Type: String
  • Default: m5.large

Maximum number of EC2 instances

Determines the maximum number of EC2 instances which can be deployed into the ECS cluster. Choose more instances for higher scalability.

• EC2MaxInstances
  • Type: Number
  • Default: 1

HTTPS Certificates Configuration

Specifies the value stored in AWS Secrets Manager that contains your HTTPS certificates. This allows Browsolate to serve HTTPS traffic securely using your own certificates.

• HttpsConfig
  • Type: String
  • Default: ''

Domain Name

Allows you to specify a custom domain name for your organization. If left blank, Browsolate will register your service with the default domain browsolate.com. Using your own domain requires additional setup to configure DNS and certificates.

• Domain
  • Type: String
  • Default: ''

Availability Zone Index

Specifies the index of the AWS Availability Zone (AZ) where the service will be deployed. Choose 0 for the first AZ, 1 for the second, and so on. Ensure that the selected instance type is available in the chosen Availability Zone.

• AvailabilityZoneIndex
  • Type: Number
  • Default: 0
  • Min Value: 0
  • Max Value: 2

UI Configuration

Region for Custom Theme CSS

Defines the AWS region where your custom theme CSS file is stored. This is useful when hosting theme files in regions other than the default region of your deployment. Providing this value ensures that the correct region is used to retrieve the CSS file.

• ThemeCSSRegion
  • Type: String
  • Default: ''

STUN/TURN Server

STUN/TURN Server EC2 Instance Type

This parameter defines the EC2 instance type for the STUN/TURN servers. STUN/TURN servers are responsible for relaying WebRTC traffic when direct peer-to-peer connections are not possible (such as when users are behind firewalls). A more powerful instance type can handle a higher volume of traffic.

• WebRTCInstanceType
  • Type: String
  • Default: t3.large

STUN/TURN Server Shared Secret

The shared secret used by the STUN/TURN server for authenticating clients. This secret is used to secure WebRTC connections between clients.

• WebRTCSecret
  • Type: String
  • Default: ''

Existing STUN Server URLs

If using existing STUN/TURN servers, specify a comma-separated list of stun: URLs here. This parameter allows you to connect to external STUN servers instead of creating new instances.

• STUNUrls

  • Type: String
  • Default: ''
  
  

Existing TURN Server URLs

If using existing STUN/TURN servers, specify a comma-separated list of turn: URLs here. This parameter allows you to connect to external TURN servers instead of creating new instances.

• TURNUrls

  • Type: String
  • Default: ''
  
  

Number of STUN/TURN Server Instances

Specifies the number of STUN/TURN server instances to deploy.

More instances can improve redundancy and performance, particularly for users behind firewalls or on mobile networks.

You can scale the number of instances depending on the expected traffic.

This field is ignored if STUNUrls or TURNUrls are provided.

• WebRTCInstances

  • Type: Number
  • Default: 1
  • Min Value: 1
  • Max Value: 20

These parameters allow you to customize various aspects of Browsolate during installation, from session management and EC2 instance types to the configuration of STUN/TURN servers and UI themes. Adjust these settings based on your organization’s requirements for performance, security, and scalability.

4 - Network security

Network Ports

The following network ports are used by Browsolate:

• Port 443 (TCP): The primary port used for session isolation. All isolated session traffic is secured by the URL encryption mechanism as discussed in Creating an Isolated Link.
• Port 5443 (TCP): This port hosts the optional URL creation API and test/example UI pages for session management and key management. Traffic on this port is protected by HTTPS and Basic Authorization, using the password set during installation in MGMTPasswd (details here). It is recommended to restrict access to this port if exposing it externally is not required.
• Port 80 (TCP): Used periodically when auto-generating HTTPS certificates through Browsolate.
• Port 3478 (TCP/UDP): Used for STUN/TURN services, facilitating WebRTC connections.
• Ports 49160–49200 (TCP/UDP): Additional ports for WebRTC traffic.

The security configuration, as shown in the CloudFormation template, controls which of these ports are exposed to external access.

Restricting Access to Port 5443

For enhanced security, you can restrict access to Port 5443 using AWS Security Groups. By default, this port is used for API and UI access and can be limited to internal networks only if public API access is not required.

API and UI Security

Browsolate offers an API endpoints for URL encryption, and several user interface pages for creatings sessions and managing keys. These are available on Port 5443.

Disabling API and UI Access

To disable the API or UI pages:

• Set the PublicAPIAccess parameter to false to limit API access.
• Disable optional UI pages in the configuration if they are not needed.
  • LauncherUI
  • UrlEncryptionKeysManagerUI

For the highest level of security, you can protect session links with a shared secret stored in AWS Secrets Manager, and completely disable external access to the API, setting PublicAPIAccess to false

See Creating an Isolated Link to learn more about using Browsolate with AWS Secrets Manager.

5 - Custom themes

Introduction

In Browsolate, you can fully customize the look and feel of the interface by providing a custom CSS file. This CSS file should be stored in an S3 bucket, and the ARN of the CSS file must be provided during the setup process.

This guide will walk you through the steps for creating and using a custom theme.

Steps Overview

1. Create your custom CSS file.
2. Upload the CSS file to S3.
3. Get the ARN of the S3 object.
4. Specify the ARN in the CloudFormation template or Marketplace configuration.

Example Custom CSS File

Here is an example of a CSS file that customizes various elements of the Browsolate interface:

:root.b8-theme-cp-default {
    --theme-display-name: Cherrypops Inc;
    --company-logo: 'https://cherrypops.inc/assets/logo.png';
    --toolbar-background: linear-gradient(145deg, #ff7bff, #ff56b3);
    --toolbar-button-hover-background: linear-gradient(145deg, #ff56b3, #ff7bff);
    --toolbar-button-active-background: linear-gradient(145deg, #ff3366, #ff4085);
    --toolbar-button-text-colour: white;
    --toolbar-button-box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1), 0 2px 4px rgba(0, 0, 0, 0.1);
    --toolbar-button-active-box-shadow: 0 2px 4px rgba(0, 0, 0, 0.2), 0 1px 3px rgba(0, 0, 0, 0.2);
    --toolbar-button-focus-box-shadow: 0 0 0 4px rgba(0, 23, 55, 0.5);
    --toolbar-button-font-size: 24px;
    --toolbar-button-width: 40px;
    --toolbar-button-height: 40px;
    --toolbar-button-padding: 8px 8px;
    --toolbar-height: 55px;
    --toolbar-menu-font-size: 16px;
    --toolbar-url-background-colour: #090909;
    --toolbar-url-text-colour: #ece;
    --session-end-content: 'https://media.istockphoto.com/id/944014530/video/animation-of-digital-human-head-on-colorful-noisy-moving-lines.mp4?s=mp4-640x640-is&k=20&c=vhYdSXvu3CDPXjtwtv6ExxOBg44nPU0_14aYbeHAOyM=';
}

Explanation of the Fields:

• --theme-display-name: The name of your theme, displayed in the Browsolate interface.
• --company-logo: The URL of your company’s logo, which is shown in the interface.
• --toolbar-background: The background style for the toolbar, in this case, a gradient.
• --toolbar-button-hover-background: The background style when hovering over toolbar buttons.
• --toolbar-button-active-background: The background style for active toolbar buttons.
• --toolbar-button-text-colour: The text color of the toolbar buttons.
• --toolbar-button-box-shadow: The box-shadow applied to the toolbar buttons by default.
• --toolbar-button-active-box-shadow: The box-shadow for active toolbar buttons.
• --toolbar-button-focus-box-shadow: The box-shadow applied when a toolbar button is focused.
• --toolbar-button-font-size: The font size of toolbar button text.
• --toolbar-button-width: The width of toolbar buttons.
• --toolbar-button-height: The height of toolbar buttons.
• --toolbar-button-padding: Padding around toolbar buttons.
• --toolbar-height: The height of the entire toolbar.
• --toolbar-menu-font-size: The font size used in the toolbar menu.
• --toolbar-url-background-colour: The background color of the URL input box.
• --toolbar-url-text-colour: The color of the text in the URL input box.
• --session-end-content: URL of a video or image displayed when the session ends.

Step 1: Create Your Custom CSS File

Create a CSS file with your custom styles, following the example above. Save the file locally, ensuring that the .css extension is used.

Step 2: Upload the CSS File to S3

1. Log in to the AWS Management Console.
2. Navigate to S3 and create a new bucket (or use an existing bucket).
3. Upload your custom CSS file to the S3 bucket.
4. Set the appropriate permissions for the file to ensure it can be accessed by Browsolate.

Step 3: Retrieve the ARN of the CSS File

To retrieve the ARN of your CSS file in S3:

1. In the S3 console, locate the uploaded CSS file.
2. Click on the file to view its details.
3. The ARN of the object will be displayed in the details section. It will look something like this:

arn:aws:s3:::bucket-name/path-to-your-file.css

Step 4: Specify the ARN in the Setup

During the installation of Browsolate, you will need to specify the ARN of your custom CSS file in the ThemeCSS . This can be done either in the CloudFormation template or the AWS Marketplace configuration.

Example CloudFormation Parameter

Parameters:
  ThemeCSS:
    Type: String
    Description: "ARN of the custom theme CSS file in S3"
    Default: "arn:aws:s3:::bucket-name/path-to-your-file.css"

By setting the ThemeCSS parameter to the ARN of your stored CSS file, Browsolate will apply your custom theme during operation.

6 - 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.

7 - Configuring a proxy

Introduction

When deploying Browsolate, you can configure a proxy server to route all traffic through an external network. This is particularly useful for enhancing security, anonymity, or enforcing network policies.

The proxy configuration is passed through the Proxy parameter from the AWS Marketplace installer or the the CloudFormation template.

Proxy Parameter Format

The format of the Proxy parameter follows standard URL syntax. It supports various types of proxy servers, including HTTP, HTTPS, and SOCKS (SOCKS4 and SOCKS5). Authentication can also be included in the URL if required.

Example Formats:

• HTTP / HTTPS Proxy:

  http://proxy.example.com:8080
  https://proxy.example.com:443
  https://username:password@proxy.example.com:443
  

• SOCKS4 / SOCKS5 Proxy:

  socks4://proxy.example.com:1080
  socks5://proxy.example.com:1080
  socks5://username:password@proxy.example.com:1080
  

In this format:

• username and password are your proxy authentication credentials (if required).
• proxy.example.com is the hostname or IP address of your proxy server.
• 8080, 443, and 1080 are the ports that the proxy server is listening on.

Custom Request Headers

In addition to proxy configuration, Browsolate allows the addition of custom headers at runtime through the customRequestHeaders field in the URL JSON configuration. This feature provides flexibility in injecting headers into requests, giving fine-grained control over how requests are handled by an upstream proxy.

Example

To include a custom header, modify the customRequestHeaders field in the URL configuration:

{
  "url": "https://example.com",
  "customRequestHeaders": {
    "X-Custom-Header1": "custom-value1",
    "X-Proxy-Username": "protected@mycompany.com"
  }
}

8 - STUN & TURN services

Purpose of STUN & TURN Services

STUN (Session Traversal Utilities for NAT) and TURN (Traversal Using Relays around NAT) servers play essential roles in WebRTC communication by helping manage NAT (Network Address Translation) traversal and facilitating peer-to-peer connectivity. These services ensure smooth media flow even when direct peer-to-peer connections are not possible.

• STUN: STUN servers provide the necessary information about a client’s public IP and port, which helps establish direct peer-to-peer connections. STUN is lightweight, but it only works if both peers can establish connections directly.
• TURN: TURN servers, on the other hand, relay media data between peers when direct connectivity is not possible, such as when one or both peers are behind symmetric NATs or firewalls. TURN is more resource-intensive, as it relays data through the server, making it essential for handling media traffic where direct connections fail.

Note: While there are several free STUN servers available, TURN functionality is generally not provided for free due to the high resource demand of relaying media traffic.

STUN & TURN Server in Browsolate

Browsolate includes the open-source Eturnal STUN/TURN server. If no alternative STUN/TURN servers are specified during setup, Browsolate will deploy an Eturnal server instance for you.

To use alternative servers, specify them as comma-separated URLs in the STUNUrls and TURNUrls parameters in the CloudFormation template or AWS Marketplace installation. This option can be particularly helpful for enterprises already using third-party WebRTC providers.

Configuring Authentication

Browsolate supports username/password authentication for TURN services as defined in RFC 8489. You can set the shared secret required for this authentication in the CloudFormation template during installation, as detailed in the WebRTCSecret parameter.

Sizing STUN/TURN Server Instances

The size and number of STUN/TURN server instances you deploy depend on your traffic volume and user network conditions:

• Instance Type: You can specify the instance type used for STUN/TURN servers in the CloudFormation configuration (e.g., t3.large for moderate usage).
• Instance Count: Adjust the WebRTCInstances parameter to define the number of server instances deployed. This is useful for balancing load and maintaining performance across high volumes of media traffic.

Currently, autoscaling is not supported, so it’s important to select the appropriate instance size and count to meet your expected usage.

Integrating with Third-Party Providers

If your use case requires specific password requirements or you need to integrate Browsolate with third-party WebRTC providers, we offer customization options. For more details or to discuss custom integration needs, please contact us through the Contact Page.