Install with OIDC

People sign in to the Hub through an OpenID Connect identity provider. The stack needs the provider's details when you create it, so you prepare the client first; after that it is one step. Users whose email the provider has not verified are refused.

#What you need from your identity provider

• An issuer URL: the URL its /.well-known/openid-configuration document is under, over https.
• A confidential client (with a client secret) that allows the authorisation code flow and the scopes openid, email and profile.
• An email claim, and a claim that says whether that email is verified: email_verified by default; xms_edov for Microsoft Entra ID.
• Optionally, a groups claim, if you want to make a whole group Hub administrators.

#Step 1: Work out the redirect URI

The Hub's sign-in runs on an Amazon Cognito domain made from the stack's Name prefix (cc-hub by default), your account ID and the Region:

https://<NamePrefix>-<account ID>.auth.<region>.amazoncognito.com/oauth2/idpresponse

For example, with the defaults, account 111122223333 and eu-west-2:

https://cc-hub-111122223333.auth.eu-west-2.amazoncognito.com/oauth2/idpresponse

After the install, the CognitoDomain output is the first part of it, so you can check it.

#Step 2: Create the client in your identity provider

1. Register a web application (a confidential client) named Cloud Certainty Hub.
2. Set its redirect URI to the one from step 1.
3. Allow the scopes openid, email and profile, and make sure the ID token or the userinfo endpoint carries email and the email-verified claim.
4. Note the client ID and create a client secret.

Microsoft Entra ID: in App registrations, choose New registration, add the redirect URI as a Web platform, and create a secret in Certificates & secrets. In Token configuration, add the optional claims email and xms_edov to the ID token. The issuer URL is https://login.microsoftonline.com/<tenant ID>/v2.0.

#Step 3: Store the client secret in AWS Secrets Manager

The stack reads the secret from Secrets Manager, so it never appears in the stack's parameters. Store it as a plain-text secret in the account and Region you install the Hub in:

aws secretsmanager create-secret \
  --region eu-west-2 \
  --name cloudcertainty-hub/oidc-client-secret \
  --secret-string '<client secret>'

Note the secret's ARN from the output, or from the Secrets Manager console.

#Step 4: Open the quick-create page

Sign in to the AWS Management Console as an administrator of the account, 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 OIDC filled in. Check the Region in the console's top bar: it must be the Region of the redirect URI and the secret.

#Step 5: Fill in the parameters and create the stack

1. Stack name: keep cloudcertainty-hub. It must not start with cc-.
2. Under General, keep Name prefix as it was in the redirect URI (cc-hub).
3. Under Identity:
   • Identity provider: OIDC (already selected).
   • OIDC issuer URL, OIDC client ID: from step 2.
   • OIDC client secret (Secrets Manager ARN): from step 3.
   • OIDC email-verified claim: keep email_verified, or xms_edov for Microsoft Entra ID.
   • First administrator email: your email address, as your provider sends it.
   • Leave SAML metadata URL empty.
4. Under IAM Identity Center, keep CreateIfMissing, or choose Disabled to leave IAM Identity Center alone. Your Hub sign-in does not depend on it.
5. Keep the defaults for everything else, select I acknowledge that AWS CloudFormation might create IAM resources with custom names, and choose Create stack.
6. Wait for CREATE_COMPLETE, then open the Outputs tab. PortalUrl is the Hub's address, and CognitoDomain should match the start of your redirect URI.

#Step 6: Sign in

Open the PortalUrl address. The Hub sends you to your identity provider to sign in, and opens on its Products page. You are an administrator as the first administrator email.

To add others, open Settings and add their emails under Administrator emails, or their groups (as your provider sends them in groups) under Administrator groups.

#If sign-in fails

• The provider reports a redirect URI mismatch: compare its redirect URI with the CognitoDomain output followed by /oauth2/idpresponse.
• You are refused after signing in: your email is not verified in the provider, or the email-verified claim has another name; set OIDC email-verified claim to it with a stack update.
• "You are not a Hub administrator": the email your provider sends is not the first administrator email or in Settings.

#Next

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