Install with SAML

People sign in to the Hub through your company's SAML 2.0 identity provider: Microsoft Entra ID, Okta, or any other. It takes two steps: create the stack, then add the Hub as an application in your identity provider and give the stack its metadata URL. Nobody can sign in until both are done.

This guide shows Microsoft Entra ID in full, then the same settings for Okta and other providers.

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

#What the Hub needs from your identity provider

Whatever the provider, the Hub's application must:

• send the user's email address in an attribute named exactly email;
• optionally, send group memberships in an attribute named exactly groups, if you want to make a whole group Hub administrators;
• use the SamlAcsUrl output as its ACS (reply) URL and the SamlAudienceUri output as its audience (entity ID);
• publish a metadata URL that the Hub's Cognito user pool can read.

The first administrator email you enter in step 2 must be the email your provider sends for you.

#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 SAML 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: SAML (already selected).
   • First administrator email: your email address, as your identity provider sends it.
   • Leave SAML metadata URL empty. You set it in step 5, once the application exists.
   • Leave the four OIDC fields empty.
3. Under IAM Identity Center, keep Set up IAM Identity Center at CreateIfMissing if you want the Hub to manage IAM Identity Center users and groups for the products later, or choose Disabled to leave IAM Identity Center alone. Your Hub sign-in does not depend on it.
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 and keep these three values:

   Output	Example	In Microsoft Entra ID
   SamlAudienceUri	urn:amazon:cognito:sp:eu-west-2_AbCdEf123	Identifier (Entity ID)
   SamlAcsUrl	https://cc-hub-111122223333.auth.eu-west-2.amazoncognito.com/saml2/idpresponse	Reply URL
   PortalUrl	https://main.d1a2b3c4d5e6f7.amplifyapp.com	Sign on URL

#Step 4: Add the Hub in Microsoft Entra ID

You need an Entra role that can create enterprise applications, such as Cloud Application Administrator.

Create the application

1. Sign in to the Microsoft Entra admin center and open Enterprise applications.
2. Choose New application, then Create your own application.
3. Name it Cloud Certainty Hub, choose Integrate any other application you don't find in the gallery (Non-gallery), and choose Create.

Set up SAML

4. In the application, open Single sign-on and choose SAML.

5. In Basic SAML Configuration, choose Edit and set:

   • Identifier (Entity ID): the SamlAudienceUri output.
   • Reply URL (Assertion Consumer Service URL): the SamlAcsUrl output.
   • Sign on URL: the PortalUrl output, so the tile in My Apps opens the Hub.

   Choose Save.

Send the email and the groups

6. In Attributes & Claims, choose Edit, then Add new claim:

   • Name: email, with Namespace left empty.
   • Source attribute: user.mail.

   Choose Save. Entra's own email claim has a long name the Hub does not read, so this one is needed even though it looks like a duplicate.

7. Optional, to make a group Hub administrators: choose Add a group claim, then Groups assigned to the application, with Source attribute Group ID. Under Advanced options, select Customize the name of the group claim and enter groups, with no namespace. Choose Save.

Copy the metadata URL and assign people

8. Back on Single sign-on, in SAML Certificates, copy the App Federation Metadata Url. You need it in step 5.
9. Open Users and groups, choose Add user/group, select the people (or, with Entra ID P1 or P2, the groups) who use the Hub, and choose Assign. Only assigned people can sign in.

#Okta

In the Okta Admin Console, open Applications, choose Create App Integration, then SAML 2.0. Name it Cloud Certainty Hub, then:

• Single sign-on URL: the SamlAcsUrl output.
• Audience URI (SP Entity ID): the SamlAudienceUri output.
• Name ID format: EmailAddress; Application username: Email.
• Attribute Statements: email with the value user.email.
• Group Attribute Statements (optional): groups, with a filter for the groups to send.

Finish, assign people on Assignments, and copy the Metadata URL from the Sign On tab.

#Another SAML provider

Create a SAML 2.0 application with the SamlAcsUrl output as the ACS (reply) URL and the SamlAudienceUri output as the audience (entity ID). Send the email in an attribute named email and, if you want them, group names or IDs in an attribute named groups. Assign the people who use the Hub, and copy the application's metadata URL.

#Step 5: 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 6: Sign in and add administrators

1. Open the PortalUrl address, or the Cloud Certainty Hub tile in My Apps. The Hub sends you to your identity provider to sign in, and opens on its Products page.
2. You are an administrator as the first administrator email. To add others, open Settings:
   • Administrator emails: one email per line.
   • Administrator groups: the values your provider sends in groups. With Entra's Group ID source these are the groups' Object IDs, not their names.

#If sign-in fails

• "You are not a Hub administrator": your email is not the first administrator email or in Settings. Check which email your provider sends: in Entra, user.mail must be set on the user.
• Your provider says you are not assigned: assign yourself or your group (step 4).
• An error from Cognito after signing in: the attribute must be named exactly email, with no namespace, and SAML metadata URL must be this application's metadata URL.

#Next

• Install a product, with sign-in through the Hub for single sign-on to it.