Getting started

This guide is for the administrator or platform team who installs Cloud Certainty Secure Browser. You subscribe on AWS Marketplace, deploy one CloudFormation stack in your own AWS account, connect your identity provider and sign in. Plan on about 30 minutes.

#What you need

• An AWS account where you can create CloudFormation stacks, including IAM roles with custom names.
• A supported Region: most commercial AWS Regions are supported. The stack checks the Region when you deploy and tells you if it isn't.
• A VPC with at least two subnets in different Availability Zones. The subnets need outbound internet access, either through a NAT gateway (recommended) or because they are public subnets. Nothing needs inbound access.
• A sign-in method for your users: AWS IAM Identity Center, another SAML 2.0 identity provider (for example Microsoft Entra ID or Okta), an OIDC identity provider, or users managed directly in Amazon Cognito.
• The email address of your first administrator.

#1. Subscribe on AWS Marketplace

1. Sign in to the AWS Management Console with the AWS account you will deploy the stack to. Use an identity that may subscribe to AWS Marketplace products, for example one with the AWSMarketplaceManageSubscriptions policy. With IAM Identity Center, sign in through your AWS access portal and open the console of that account. Screenshot
2. In the same browser, open Cloud Certainty Secure Browser on AWS Marketplace (opens in a new tab) and choose View purchase options. Screenshot
3. Review the offer. There is one price, per container-hour, and no upfront or monthly fee. Screenshot
4. At the bottom of the page, choose Subscribe. This accepts the terms and the end user license agreement. Screenshot
5. Wait for the purchase confirmation, usually under a minute, then choose Launch your software. The agreement status is Active. Screenshot
6. The Launch page shows the current version and the setup instructions. The AWS CloudFormation template link is the template URL you need in the next step. Screenshot

There is no upfront fee. You pay per browser session-hour while sessions run, plus the AWS resources the stack uses in your account. See the FAQ.

#2. Deploy the stack

#CloudFormation console

Launch stack (opens the AWS CloudFormation console in a new tab)

1. Choose Launch stack. It opens CloudFormation's Quick create stack page with the template of the latest release and the stack name secure-browser filled in. The Marketplace Launch page has the same link as Launch stack in AWS CloudFormation. Check the Region in the console's top bar. Screenshot
2. Under Network, choose your VPC and at least two subnets in different Availability Zones, and say whether they are public. Under Identity, choose your identity provider (see Connect your identity provider). Screenshot
3. Enter the First administrator email. Keep the defaults for everything else, or see below. With IAM Identity Center, SAML or OIDC the stack does not create this user. The first person who signs in with this email becomes the administrator, so it must be the email of an existing user in your identity provider, the user must be assigned to the application (step 3), and with OIDC the email must be verified. Upper and lower case don't matter. With Cognito users only, the stack creates the user and emails a temporary password. Screenshot
4. At the bottom of the page, acknowledge that CloudFormation might create IAM resources with custom names, and choose Create stack. It takes about 5 to 10 minutes. Screenshot
5. Wait for the status to change from CREATE_IN_PROGRESS to CREATE_COMPLETE. Screenshot
6. Open the Outputs tab. PortalUrl, SamlAcsUrl and SamlAudienceUri are the values you need in the next step. Screenshot

To pick a release yourself, open the CloudFormation console, choose Create stack → With new resources, and enter the release's template URL as the Amazon S3 URL. The URL is the same for every Region:

https://cloudcertainty-secure-browser-us-east-1.s3.us-east-1.amazonaws.com/<version>/main.yaml

Replace <version> with a release number from the release notes page.

#AWS CLI

aws cloudformation create-stack --region <your-region> --stack-name secure-browser \
  --template-url https://cloudcertainty-secure-browser-us-east-1.s3.us-east-1.amazonaws.com/<version>/main.yaml \
  --parameters file://params.json \
  --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM

#Terraform or OpenTofu

The cloudcertainty/secure-browser/aws module deploys the same template and checks your inputs at plan time:

module "secure_browser" {
  source  = "cloudcertainty/secure-browser/aws"
  version = "~> 0.1"

  vpc_id                = "vpc-0123456789abcdef0"
  task_subnet_ids       = ["subnet-0123456789abcdef0", "subnet-0fedcba9876543210"]
  identity_provider     = "IAMIdentityCenter"
  bootstrap_admin_email = "[email protected]"
}

#Parameters that matter

Most parameters have sensible defaults. These are the ones to look at:

Leave the parameters marked Advanced (support use only) empty.

When the stack is complete, note these outputs:

• PortalUrl: the address your users and admins open.
• SamlAcsUrl and SamlAudienceUri: needed for a SAML identity provider.
• CognitoDomain: needed for an OIDC identity provider.

#3. Connect your identity provider

Roles and policies are assigned by email address, so the email your identity provider sends must be one users can't change themselves.

#Which one to choose

Not sure? Use what your staff already sign in with every day. If that is IAM Identity Center, choose it. If it is Microsoft Entra ID or Okta and that isn't connected to IAM Identity Center, choose SAML.

#IAM Identity Center

You need the organization instance of IAM Identity Center, the one that gives access to your AWS accounts. An account instance can't hold SAML applications. The stack can run in any account of your organization. You create the application in the account where IAM Identity Center is managed.

1. Deploy the stack with IdentityProvider = IAMIdentityCenter and leave SamlMetadataUrl empty.
2. In the IAM Identity Center console of your management account, open Applications and choose Add application. Screenshot
3. Choose I have an application I want to set up and SAML 2.0, then Next. Screenshot
4. Set Display name to Cloud Certainty Secure Browser. Under IAM Identity Center metadata, copy the IAM Identity Center SAML metadata file URL; you need it in step 8. Screenshot
5. Set Application start URL to the PortalUrl output. Under Application metadata, choose Manually type your metadata values: Application ACS URL is the SamlAcsUrl output and Application SAML audience is the SamlAudienceUri output. Choose Submit. Screenshot
6. In Actions → Edit attribute mappings, map Subject to ${user:email} (format emailAddress), add email mapped to ${user:email} (format unspecified), and save. Screenshot
7. Choose Assign users and groups and add the people or groups who may use the browser, including the first administrator. Screenshot
8. Update the stack (Update stack → Make a direct update, keep the current template and every other parameter) and set SamlMetadataUrl to the metadata URL from step 4.

In the AWS access portal. After step 7, every assigned user sees a Cloud Certainty Secure Browser tile under Applications; refresh the list if it isn't there yet. Users who aren't assigned don't see the tile and can't sign in. After step 8, the tile opens the portal and signs the user in with their current IAM Identity Center session, with no second sign-in. Screenshot The first administrator lands in the portal with the Administration menu. Screenshot The tile only works if Application start URL is set to the PortalUrl output. Sign-in that starts in the access portal without it isn't supported.

IAM Identity Center sends group IDs rather than group names, and only if you also map groups to ${user:groups}. The simplest setup is to assign roles and policies per user (by email). If you do map groups, use the group ID from the IAM Identity Center console wherever the admin console asks for a group name.

#Microsoft Entra ID, Okta and other SAML 2.0 providers

Deploy with IdentityProvider = SAML, then create a SAML application in your provider:

Assign users and groups to the application, copy its metadata URL, and update the stack with SamlMetadataUrl set to it.

App tiles must open the PortalUrl. Sign-in that starts at your provider instead isn't supported. In Microsoft Entra ID, setting the Sign-on URL is enough for the tile in My Apps. In Okta, the tile of a SAML app always starts sign-in at Okta. Hide it (Do not display application icon to users) and add a Bookmark App that points to the PortalUrl.

#OIDC providers

1. Create a confidential web client in your provider with the redirect URI <CognitoDomain>/oauth2/idpresponse and the scopes openid email profile.
2. Store the client secret in AWS Secrets Manager as a plain-text secret.
3. Deploy (or update) the stack with IdentityProvider = OIDC, OidcIssuer, OidcClientId and OidcClientSecretArn.

Your provider must tell the stack that each user's email is verified (usually the email_verified claim). Users with an unverified email are refused. For Microsoft Entra ID, SAML is the simpler choice.

#Users managed in Amazon Cognito

With IdentityProvider = CognitoOnly there is nothing to connect. Your first administrator gets a temporary password by email. Create further users in the Amazon Cognito console and tick Mark email address as verified. Every user sets up an authenticator app at first sign-in.

#4. Sign in

Open the PortalUrl output and sign in as the BootstrapAdminEmail user. You land in the portal with an Admin menu. Do this straight after deployment: the first sign-in with that email becomes the permanent first administrator.

Then:

• grant Admin to at least one more person or group, so you can't be locked out;
• review the restrictive default policy profile and create profiles for your teams;
• share the PortalUrl and the user guide with your users.

The admin guide explains each setting.

#Removing the product

Delete the CloudFormation stack (or run terraform destroy). The table holding your settings and audit history is kept on purpose; delete it yourself once you no longer need the history. Then cancel the subscription in AWS Marketplace if you don't plan to deploy again.

#Troubleshooting

Still stuck? Email [email protected] with the stack's Region and the error message, or see the support plans.