Getting started

This guide is for the AWS administrator or platform team who installs Cloud Certainty Hub. The Hub is one CloudFormation stack in your own AWS account. You install it once per Region, sign in, and from then on subscribe to, install and update Cloud Certainty products from it.

The Hub is free. AWS bills you for the small serverless services it runs in your account: AWS Lambda, Amazon API Gateway, Amazon DynamoDB (on demand), AWS Amplify Hosting, Amazon Cognito, and a little Amazon S3 and CloudWatch Logs.

#What you need

• An AWS account and an identity that can create the stack. The stack creates IAM roles with fixed names, so it needs the CAPABILITY_IAM and CAPABILITY_NAMED_IAM capabilities. It also creates Lambda functions, an S3 bucket, a DynamoDB table, a Cognito user pool, an API Gateway HTTP API, an Amplify Hosting app and CloudWatch log groups, and with update reminders on, an SNS topic and an EventBridge rule. An administrator of the account has every permission this needs.
• The email address of the first Hub administrator. It is the one parameter without a default.
• A sign-in method for the Hub: AWS IAM Identity Center (the default), another SAML 2.0 identity provider, an OIDC identity provider, or users managed in the Hub's own Amazon Cognito user pool. See Choose how people sign in.

You don't need a VPC: the Hub is serverless. You don't need IAM Identity Center permissions either. When the stack sets up IAM Identity Center, it does so with a role of its own.

To subscribe to products on AWS Marketplace later, you need an identity that may subscribe, for example one with the AWSMarketplaceManageSubscriptions policy.

#Choose a Region

Install the Hub in the Region where you want to run Cloud Certainty products. The Hub lists and installs the product stacks of its own Region only, and its VPC and subnet pickers show that Region's networks. To manage products in a second Region, install a second Hub there.

The template URL is the same for every Region: the release bucket is in us-east-1, and CloudFormation reads the template from there wherever you create the stack. IAM Identity Center can be in any Region; the Hub finds it wherever it is.

#Which release to install

Every release is an immutable template in Cloud Certainty's public release bucket:

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

This guide installs 0.1.0-rc.12, the latest release when it was published:

https://cloudcertainty-hub-us-east-1.s3.us-east-1.amazonaws.com/0.1.0-rc.12/main.yaml

The newest release is always announced in latest.json, next to the releases. Its latest field is the version and templateUrl the template:

curl -s https://cloudcertainty-hub-us-east-1.s3.us-east-1.amazonaws.com/latest.json

Every release and what changed in it is on the release notes page.

#Choose how people sign in

The Hub offers the same sign-in options as every Cloud Certainty product, through its IdentityProvider parameter:

CognitoOnly is the quickest way to start. You can change the method later with a stack update.

With IAMIdentityCenter, the IdentityCenterSetup parameter (default CreateIfMissing) also finds or creates IAM Identity Center for you. Read IAM Identity Center if the account belongs to an AWS Organization.

#Watch an install

Three short videos, one for each way of signing in, from Launch stack to the Hub's catalogue. Each has a voice-over and captions.

#Amazon Cognito users (CognitoOnly)

#SAML with Microsoft Entra ID (SAML)

#AWS IAM Identity Center (IAMIdentityCenter, the default)

#Install with the CloudFormation console

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

1. Sign in to the AWS Management Console with the account you install the Hub in, and choose Launch stack. It opens CloudFormation's Quick create stack page with the template of 0.1.0-rc.12 and the stack name cloudcertainty-hub filled in. Check the Region in the console's top bar. To open the page in a given Region, put it in the link:

   https://console.aws.amazon.com/cloudformation/home?region=<region>#/stacks/quickcreate?templateURL=https://cloudcertainty-hub-us-east-1.s3.us-east-1.amazonaws.com/0.1.0-rc.12/main.yaml&stackName=cloudcertainty-hub

2. Under Identity, choose the Identity provider and enter the First administrator email. Leave SAML metadata URL empty on the first deployment. With OIDC, fill in the three OIDC fields.

3. Under IAM Identity Center, keep Set up IAM Identity Center at CreateIfMissing, or see IAM Identity Center for the other choices.

4. Keep the defaults for everything else, or see the configuration reference. Leave the parameters under Advanced (support use only) empty.

5. At the bottom of the page, acknowledge that CloudFormation might create IAM resources with custom names, and choose Create stack.

6. Wait for the status to change from CREATE_IN_PROGRESS to CREATE_COMPLETE, then open the Outputs tab. PortalUrl is the address of the Hub.

Don't start the stack name with the product stack prefix (cc- by default): the Hub manages the stacks whose names start with it, and its own stack must stay out of that set.

#Install with the AWS CLI

Create the stack with the template URL of the release, the two IAM capabilities and your parameters. This installs the Hub in eu-west-2 with Cognito users; change the Region and the values to yours:

aws cloudformation create-stack \
  --region eu-west-2 \
  --stack-name cloudcertainty-hub \
  --template-url https://cloudcertainty-hub-us-east-1.s3.us-east-1.amazonaws.com/0.1.0-rc.12/main.yaml \
  --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM \
  --parameters \
    ParameterKey=BootstrapAdminEmail,ParameterValue=admin@example.com \
    ParameterKey=IdentityProvider,ParameterValue=CognitoOnly

For more parameters, a file is easier to keep. Every parameter you leave out takes its default:

[
  { "ParameterKey": "BootstrapAdminEmail", "ParameterValue": "admin@example.com" },
  { "ParameterKey": "IdentityProvider", "ParameterValue": "IAMIdentityCenter" },
  { "ParameterKey": "IdentityCenterSetup", "ParameterValue": "CreateIfMissing" },
  { "ParameterKey": "DeployMode", "ParameterValue": "Full" },
  { "ParameterKey": "TagOwner", "ParameterValue": "platform-team" }
]

aws cloudformation create-stack \
  --region eu-west-2 \
  --stack-name cloudcertainty-hub \
  --template-url https://cloudcertainty-hub-us-east-1.s3.us-east-1.amazonaws.com/0.1.0-rc.12/main.yaml \
  --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM \
  --parameters file://hub-parameters.json

Wait until the stack is ready, then read its outputs:

aws cloudformation wait stack-create-complete \
  --region eu-west-2 --stack-name cloudcertainty-hub

aws cloudformation describe-stacks \
  --region eu-west-2 --stack-name cloudcertainty-hub \
  --query "Stacks[0].Outputs[].[OutputKey,OutputValue]" --output table

If the wait ends with an error, the stack's events say why:

aws cloudformation describe-stack-events \
  --region eu-west-2 --stack-name cloudcertainty-hub \
  --query "StackEvents[?ResourceStatus=='CREATE_FAILED'].[LogicalResourceId,ResourceStatusReason]" \
  --output table

#Install with Terraform

The Hub's Terraform module deploys the same template as an aws_cloudformation_stack resource and checks your inputs at plan time. It needs Terraform 1.5 or later and the AWS provider 6.x, and it installs the Hub in the provider's Region:

provider "aws" {
  region = "eu-west-2"
}

module "hub" {
  source  = "cloudcertainty/cloudcertainty-hub/aws"
  version = "0.1.0-rc.12"

  hub_version           = "0.1.0-rc.12"
  identity_provider     = "CognitoOnly"
  bootstrap_admin_email = "admin@example.com"

  tags = {
    Owner       = "platform-team"
    Environment = "prod"
  }
}

output "hub_url" {
  value = module.hub.portal_url
}

The module is on the Terraform Registry (opens in a new tab), and its version tracks the Hub release it deploys. Terraform only selects a pre-release such as 0.1.0-rc.12 when version names it exactly. Keep version and hub_version on the same release. Each input is a template parameter in snake case (identity_provider is IdentityProvider); the configuration reference lists them all. The Owner, CostCenter and Environment keys of tags also fill the template's tag parameters.

The module tags the stack cloudcertainty:managed-by = terraform. The Hub reads that tag and never updates itself, so your Terraform state does not drift: you update the Hub by changing hub_version and applying. The stack is named cloudcertainty-hub unless you set stack_name, which must not start with stack_name_prefix (cc- by default).

With IAMIdentityCenter or SAML, apply twice: first without saml_metadata_url, then, once the SAML application exists, with its metadata URL. The module's saml_acs_url and saml_audience_uri outputs are the values the application needs.

Without the module, the same stack is one resource. Keep the tag, so the Hub leaves its updates to Terraform:

resource "aws_cloudformation_stack" "hub" {
  name         = "cloudcertainty-hub"
  template_url = "https://cloudcertainty-hub-us-east-1.s3.us-east-1.amazonaws.com/0.1.0-rc.12/main.yaml"
  capabilities = ["CAPABILITY_IAM", "CAPABILITY_NAMED_IAM"]

  parameters = {
    BootstrapAdminEmail = "admin@example.com"
    IdentityProvider    = "CognitoOnly"
  }

  tags = {
    "cloudcertainty:managed-by" = "terraform"
  }
}

#Where to find the Hub

The stack output PortalUrl is the address of the Hub, on amplifyapp.com. It is in the Outputs tab of the stack in the CloudFormation console, and with Terraform in the module's portal_url output. From the AWS CLI:

aws cloudformation describe-stacks \
  --region eu-west-2 --stack-name cloudcertainty-hub \
  --query "Stacks[0].Outputs[?OutputKey=='PortalUrl'].OutputValue" --output text

The other outputs are described in the configuration reference.

#First sign-in

#Amazon Cognito users

With CognitoOnly the stack creates your user. You receive an email with the subject Your Cloud Certainty Hub account, with your user name (your email address) and a temporary password. The temporary password is valid for 3 days.

1. Open the Hub's address and sign in with your email address and the temporary password.
2. Set a new password: at least 14 characters, with upper and lower case letters, a number and a symbol.
3. Register an authenticator app. Multi-factor authentication is required for every Cognito user of the Hub.

You are the first Hub administrator.

#IAM Identity Center

With IAMIdentityCenter, finish the second step before anyone signs in. AWS offers no API for it, so it is done once in the console.

1. Read the stack outputs. IdentityCenterStatus says what the stack did: found or created IAM Identity Center, or why it could not. IdentityCenterRegion is where IAM Identity Center is. If the status says IAM Identity Center belongs to your organisation's management account, or that it must be enabled in the console, read IAM Identity Center first.

2. In the IAM Identity Center console, in that Region, open Applications, choose Add application, then I have an application I want to set up and SAML 2.0.

3. Enter the display name Cloud Certainty Hub, the PortalUrl output as the application start URL, and under Manually type your metadata values the SamlAcsUrl output as the ACS URL and the SamlAudienceUri output as the SAML audience.

4. Before you submit, copy the IAM Identity Center SAML metadata file URL shown on the same page.

5. Submit, then choose Actions, Edit attribute mappings and set:

   User attribute in the application	Maps to this value	Format
   Subject	${user:email}	emailAddress
   email	${user:email}	unspecified
   groups	${user:groups}	unspecified

6. Choose Assign users and groups and assign the CloudCertaintyHubAdmins group (its members are Hub administrators) or the people who use the Hub.

7. If the stack created your user in IAM Identity Center, it has no password yet. In the IAM Identity Center console, open Users, your user, and choose Reset password.

8. Update the Hub's stack with the metadata URL and keep every other parameter. In the console, choose Update, keep the current template and set SAML metadata URL. With the AWS CLI:

   bash

   KEEP=$(aws cloudformation describe-stacks \
     --region eu-west-2 --stack-name cloudcertainty-hub \
     --query "Stacks[0].Parameters[?ParameterKey!='SamlMetadataUrl'].ParameterKey" --output text \
     | tr '\t' '\n' | sed 's/.*/ParameterKey=&,UsePreviousValue=true/')
   
   aws cloudformation update-stack \
     --region eu-west-2 --stack-name cloudcertainty-hub \
     --use-previous-template \
     --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM \
     --parameters ParameterKey=SamlMetadataUrl,ParameterValue=<metadata URL> $KEEP

   With Terraform, set saml_metadata_url and apply again.

9. When the update is complete, open the Hub's address. It sends you to IAM Identity Center to sign in.

Once you are in, the Hub's Identity Center page shows the same values, so the next person never needs the stack outputs.

#Another SAML identity provider

The same two steps with your identity provider: create a SAML application with the SamlAcsUrl output as the ACS (reply) URL and the SamlAudienceUri output as the audience (entity ID). Send the user's email in an attribute named email, and group names, if you want to use groups, in an attribute named groups. Then update the stack with the application's metadata URL as above.

#OIDC

Before you install, create a confidential client in your identity provider:

• Redirect URI: https://<NamePrefix>-<account ID>.auth.<region>.amazoncognito.com/oauth2/idpresponse, for example https://cc-hub-111122223333.auth.eu-west-2.amazoncognito.com/oauth2/idpresponse. After the install, the CognitoDomain output is the first part of it.
• Scopes: openid, email and profile. The Hub reads the email claim, the claim named in OidcEmailVerifiedClaim (email_verified by default; xms_edov for Microsoft Entra ID), and groups if your provider sends it.
• Client secret: store it in AWS Secrets Manager as a plain-text secret in the Hub's account and Region, and give its ARN as OidcClientSecretArn.

Then install with IdentityProvider set to OIDC and the issuer URL, client ID and secret ARN.

#Next steps

• Add administrators. The first administrator always stays one. Add others in the Hub's Settings by email or by group, or add them to the CloudCertaintyHubAdmins group in IAM Identity Center. Only administrators can use the Hub.
• Set shared defaults in Settings: values such as your VPC, subnets and tags, which fill every product's install form.
• Install a product. See installing and updating products.
• Confirm update reminders. With update reminders on, AWS sends a confirmation email to the reminder address; accept it to hear about new Hub releases. See update reminders.