Install with IAM Identity Center

The default sign-in. People sign in to the Hub through AWS IAM Identity Center, with single sign-on from its AWS access portal. The stack finds IAM Identity Center or creates it for you. It takes two steps: create the stack, then add the Hub's SAML application in IAM Identity Center and give the stack its metadata URL. Nobody can sign in until both are done.

Watch it first (1:25, with captions), then follow the steps below.

#Before you start: is your account in an AWS Organization?

Where IAM Identity Center lives decides where you create the Hub's application in step 4:

• A standalone account: the stack creates IAM Identity Center for this account (an account instance) if there is none. Everything happens in this account.
• The management account of an organisation: AWS lets you enable IAM Identity Center there only in the console. Enable it first (open IAM Identity Center and choose Enable), then install the Hub.
• A member account of an organisation that uses IAM Identity Center: it belongs to the management account, so step 4 and step 5 are done there, by its administrator.

IAM Identity Center explains each case in full.

#Step 1: Open the quick-create page

Sign in to the AWS Management Console as an administrator of the account you install the Hub in, then choose Launch stack:

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

It opens CloudFormation's Quick create stack page with the template of 0.1.0-rc.14, the stack name cloudcertainty-hub and Identity provider IAMIdentityCenter filled in.

Check the Region in the console's top bar, and change it to the Region you chose before you go on.

#Step 2: Fill in the parameters

1. Stack name: keep cloudcertainty-hub. Whatever you choose, it must not start with cc-, the prefix of the product stacks the Hub manages.
2. Under Identity:
   • Identity provider: IAMIdentityCenter (already selected).
   • First administrator email: your email address.
   • Leave SAML metadata URL empty. You set it in step 6, once the application exists.
   • Leave the four OIDC fields empty.
3. Under IAM Identity Center:
   • Set up IAM Identity Center: keep CreateIfMissing. The stack uses this account's IAM Identity Center, or creates one when there is none.
   • Region for a new IAM Identity Center: leave it empty to create it in the stack's Region, or enter another Region. An existing IAM Identity Center is found in any Region.
4. Keep the defaults for everything else. The configuration reference explains each one. Leave Advanced (support use only) empty.

#Step 3: Create the stack and read its outputs

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

2. Wait for CREATE_COMPLETE. It takes a few minutes.

3. Open the Outputs tab. You need these values in the next steps:

   Output	What it is
   IdentityCenterStatus	What the stack did: found or created IAM Identity Center, or why it could not.
   IdentityCenterRegion	The Region of IAM Identity Center. Create the application there.
   PortalUrl	The Hub's address: the application start URL.
   SamlAcsUrl	The ACS URL of the application.
   SamlAudienceUri	The SAML audience of the application.

If IdentityCenterStatus says IAM Identity Center belongs to your organisation's management account, or must be enabled in the console, do that first; the IAM Identity Center page says what to do in each case.

When the stack found or created IAM Identity Center in this account, it also created the group CloudCertaintyHubAdmins (its members are Hub administrators) with a user for your email in it.

#Step 4: Add the Hub's application in IAM Identity Center

1. Open the IAM Identity Center console in the Region of IdentityCenterRegion.
2. Choose Applications, then Add application.
3. Choose I have an application I want to set up, then SAML 2.0, then Next.
4. Display name: Cloud Certainty Hub.
5. IAM Identity Center metadata: copy the IAM Identity Center SAML metadata file URL and keep it. You need it in step 6.
6. Application start URL: the PortalUrl output. The tile in the AWS access portal opens it.
7. Application metadata: choose Manually type your metadata values, then:
   • Application ACS URL: the SamlAcsUrl output.
   • Application SAML audience: the SamlAudienceUri output.
8. Choose Submit.

#Step 5: Map the attributes and assign people

1. On the application's page, choose Actions, then 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

   Choose Add new attribute mapping for email and groups, then Save changes. The names are case sensitive.

2. Choose Assign users and groups and assign the CloudCertaintyHubAdmins group, and any other people or groups who use the Hub. Only assigned people can sign in.

3. If the stack created your user, it has no password yet: open Users, your user, and choose Reset password. Follow the email to set one.

#Step 6: Give the stack the metadata URL

Update the Hub's stack with the metadata URL from step 4, and keep every other parameter as it is.

In the CloudFormation console:

1. Select the cloudcertainty-hub stack and choose Update (in newer consoles, Update stack, then Make a direct update).
2. Choose Use existing template, then Next.
3. Paste the URL into SAML metadata URL. Change nothing else. Choose Next, then Next again.
4. Select the IAM acknowledgement and choose Submit.
5. Wait for UPDATE_COMPLETE.

With the AWS CLI, which keeps every other parameter for you:

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.

#Step 7: Sign in

Open the AWS access portal (the IdentityCenterPortalUrl output) and choose Cloud Certainty Hub, or open the PortalUrl address directly: the Hub sends you to IAM Identity Center to sign in. The Hub opens on its Products page.

You are an administrator as the first administrator email, and so is every member of CloudCertaintyHubAdmins. The Hub's Identity Center page keeps the values from steps 4 to 6, so you never need the stack outputs again.

#If sign-in fails

• "You are not a Hub administrator": you signed in, but your email is not the first administrator email and you are not in CloudCertaintyHubAdmins. Add yourself to the group, or ask an administrator to add your email in Settings.
• IAM Identity Center says you are not assigned: assign yourself or your group (step 5).
• An error from Cognito after signing in: check the attribute names and the Subject format in step 5, and that SAML metadata URL is the URL from this application.

#Next

• Add people to CloudCertaintyHubAdmins on the Hub's Identity Center page.
• Install a product, with sign-in through the Hub for single sign-on to it.