Launch with OpenID Connect (OIDC)

Time to deploy: Approximately 30 minutes

Prerequisites

Important

The Clickstream Analytics on AWS console is served via CloudFront distribution which is considered as an Internet information service.

If deploying the solution in AWS China Regions, a valid ICP Recordal is required. Check this documentation for additional prerequisites.

• A domain. You will use this domain to access the Clickstream Analytics on AWS console. This is required for AWS China Regions, and is optional for AWS Regions.
• An SSL certificate in AWS IAM. The SSL must be associated with the given domain. Follow this guide to upload SSL certificate to IAM. This is required for AWS China Regions only.

Deployment Overview

Use the following steps to deploy this solution on AWS.

Step 1. Create OIDC client

Step 2. Launch the stack

Step 3. Update the callback URL of OIDC client

Step 4. Set up DNS Resolver

Step 5. Launch the web console

Step 1. Create OIDC client

You can use different kinds of OpenID Connect providers. This section introduces Option 1 to Option 4.

• (Option 1) Using Amazon Cognito from another region as OIDC provider.
• (Option 2) Authing, which is an example of a third-party authentication provider.
• (Option 3) Keycloak, which is a solution maintained by AWS and can serve as an authentication identity provider.
• (Option 4) ADFS, which is a service offered by Microsoft.
• (Option 5) Other third-party authentication platforms such as Auth0.

Follow the steps below to create an OIDC client, and obtain the client_id and issuer.

(Option 1) Using Cognito User Pool from another region

You can leverage the Cognito User Pool in a supported AWS Region as the OIDC provider.

1. Go to the Amazon Cognito console in an AWS Region.
2. Set up the hosted UI with the Amazon Cognito console based on this guide. Please pay attentions to below two configurations
   • Choose Public client when selecting the App type. Make sure don't change the selection Don't generate a client secret for Client secret.
   • Add Profile in OpenID Connect scopes.

3. Enter the Callback URL and Sign out URL using your domain name for Clickstream Analytics on AWS console as the following:

   • Callback URL: http[s]://<domain-name>/signin
   • Sign out URL: http[s]://<domain-name>

   Note

   If you're not using custom domain for the console, you don't know the domain name of console. You can input a fake one, for example, clickstream.example.com. Then update it following guidelines in Step 3.

4. If your hosted UI is set up, you should be able to see something like below.

   

5. Save the App client ID, User pool ID and the AWS Region to a file, which will be used later.

   

In Step 2. Launch the stack, enter the parameters below from your Cognito User Pool.

• OIDCClientId: App client ID
• OIDCProvider: https://cognito-idp.${REGION}.amazonaws.com/${USER_POOL_ID}

(Option 2) Authing.cn OIDC client

1. Go to the Authing console.
2. Create a user pool if you don't have one.
3. Select the user pool.
4. On the left navigation bar, select Self-built App under Applications.
5. Click the Create button.
6. Enter the Application Name, and Subdomain.

7. Save the App ID (that is, client_id) and Issuer to a text file from Endpoint Information, which will be used later.

   

8. Update the Login Callback URL and Logout Callback URL, note that you need to add /signin to your domain name for Login Callback URL as follow:

   • Callback URL: http[s]://<domain-name>/signin
   • Sign out URL: http[s]://<domain-name>

9. Set the Authorization Configuration.

   

You have successfully created an authing self-built application.

In Step 2. Launch the stack, enter the parameters below from your Authing user pool.

• OIDCClientId: client id
• OIDCProvider: Issuer

(Option 3) Keycloak OIDC client

1. Deploy the Keycloak solution in AWS China Regions following this guide.

2. Sign in to the Keycloak console.

3. On the left navigation bar, select Add realm. Skip this step if you already have a realm.

4. Go to the realm setting page. Choose Endpoints, and then OpenID Endpoint Configuration from the list.

   

5. In the JSON file that opens up in your browser, record the issuer value which will be used later.

   

6. Go back to Keycloak console and select Clients on the left navigation bar, and choose Create.

7. Enter a Client ID, which must contain letters (case-insensitive) or numbers. Record the Client ID which will be used later.

8. Change client settings. Enter http[s]://<Clickstream Analytics on AWS Console domain>/signin in Valid Redirect URIs, and enter <console domain> and + in Web Origins.

   Tip

   If you're not using custom domain for the console, the domain name of console is not available yet. You can enter a fake one, for example, clickstream.example.com, and then update it following guidelines in Step 3.

9. In the Advanced Settings, set the Access Token Lifespan to at least 5 minutes.

10. Select Users on the left navigation bar.
11. Click Add user and enter Username.
12. After the user is created, select Credentials, and enter Password.

In Step 2. Launch the stack, enter the parameters below from your Keycloak realm.

• OIDCClientId: client id
• OIDCProvider: https://<KEYCLOAK_DOMAIN_NAME>/auth/realms/<REALM_NAME>

(Option 4) ADFS OpenID Connect Client

1. Make sure your ADFS is installed. For information about how to install ADFS, refer to this guide.
2. Make sure you can log in to the ADFS Sign On page. The URL should be https://adfs.domain.com/adfs/ls/idpinitiatedSignOn.aspx, and you need to replace adfs.domain.com with your real ADFS domain.
3. Log on your Domain Controller, and open Active Directory Users and Computers.

4. Create a Security Group for Clickstream Analytics on AWS Users, and add your planned Clickstream Analytics on AWS users to this Security Group.

5. Log on to ADFS server, and open ADFS Management.

6. Right click Application Groups, choose Application Group, and enter the name for the Application Group. Select Web browser accessing a web application option under Client-Server Applications, and choose Next.

7. Record the Client Identifier (client_id) under Redirect URI, enter your Clickstream Analytics on AWS domain (for example, xx.example.com), and choose Add, and then choose Next.

8. In the Choose Access Control Policy window, select Permit specific group, choose parameters under Policy part, add the created Security Group in Step 4, then click Next. You can configure other access control policy based on your requirements.

9. Under Summary window, choose Next, and choose Close.

10. Open the Windows PowerShell on ADFS Server, and run the following commands to configure ADFS to allow CORS for your planned URL.

    Set-AdfsResponseHeaders -EnableCORS $true
    Set-AdfsResponseHeaders -CORSTrustedOrigins https://<your-clickstream-analytics-on-aws-domain>
    

11. Under Windows PowerShell on ADFS server, run the following command to get the Issuer (issuer) of ADFS, which is similar to https://adfs.example.com/adfs.

    Get-ADFSProperties | Select IdTokenIssuer
    

    

In Step 2. Launch the stack, enter the parameters below from your ADFS server.

• OIDCClientId: client id
• OIDCProvider: Get the server of the issuer from above step 11

Step 2. Launch the stack

1. Sign in to the AWS Management Console and use the button below to launch the AWS CloudFormation template.

   	Launch in AWS Console
   Launch in AWS Regions
   Launch with custom domain in AWS Regions
   Launch in AWS China Regions

2. The template is launched in the default region after you log in to the console. To launch the Clickstream Analytics on AWS solution in a different AWS Region, use the Region selector in the console navigation bar.

3. On the Create stack page, verify that the correct template URL shows in the Amazon S3 URL text box and choose Next.
4. On the Specify stack details page, assign a name to your solution stack. For information about naming character limitations, refer to IAM and AWS STS quotas in the AWS Identity and Access Management User Guide.

5. Under Parameters, review the parameters for the template and modify them as necessary.

   • This solution uses the following parameters:

     Parameter	Default	Description
     OpenID Connector Client Id (OIDCClientId)	<Requires input>	OpenID Connect client Id.
     OpenID Connector Issuer (OIDCProvider)	<Requires input>	OpenID Connect provider issuer. The issuer must begin with https://
     Admin User Email (Email)	<Requires input>	Specify the email of the Administrator. This email address will receive a temporary password to access the Clickstream Analytics on AWS web console. You can create more users directly in the provisioned Cognito User Pool after launching the solution.
     IAM Role Prefix (IamRolePrefix)	<Optional input>	Specify the prefix for the name of IAM roles created in the solution.
     IAM Role Boundary ARN (IamRoleBoundaryArn)	<Optional input>	Specify the permissions boundary for the IAM roles created in the solution.

     Important

     By default, this deployment uses TLSv1.0 and TLSv1.1 in CloudFront. However, we recommend that you manually configure CloudFront to use the more secure TLSv1.2/TLSv1.3 and apply for a certificate and custom domain to enable this. We highly recommend that you update your TLS configuration and cipher suite selection according to the following recommendations:

     • Transport Layer Security Protocol: Upgrade to TLSv1.2 or higher
     • Key Exchange: ECDHE
     • Block Cipher Mode of Operation: GCM
     • Authentication: ECDSA
     • Encryption Cipher: AES256
     • Message Authentication: SHA(256/384/any hash function except for SHA1)

     Such as TLSv1.2_2021 can meet the above recommendations.

   • If you are launching the solution with custom domain in AWS Regions, this solution has the following additional parameters:

     Parameter	Default	Description
     Host Zone ID (HostedZoneId)	<Requires input>	Choose the public hosted zone ID of Amazon Route 53.
     Host Zone Name (HostedZoneName)	<Requires input>	The domain name of the public hosted zone, for example, example.com.
     Record Name (RecordName)	<Requires input>	The sub name (as known as record name in R53) of the domain name of console. For example, enter clickstream, if you want to use custom domain clickstream.example.com for the console.

   • If you are launching the solution in AWS China Regions, this solution has the following additional parameters:

     Parameter	Default	Description
     Domain Name (Domain)	<Requires input>	Custom domain for Clickstream Analytics on AWS console. Do NOT add http(s) prefix.
     Certificate Id (IamCertificateID)	<Requires input>	The ID of the SSL certificate in IAM. The ID is composed of 21 characters of capital letters and digits. Use the list-server-certificates command to retrieve the ID.

6. Choose Next.

7. On the Configure stack options page, choose Next.
8. On the Review page, review and confirm the settings. Check the box acknowledging that the template creates AWS Identity and Access Management (IAM) resources.
9. Choose Create stack to deploy the stack.

You can view the status of the stack in the AWS CloudFormation console in the Status column. You should receive a CREATE_COMPLETE status in approximately 10 minutes.

Step 3. Update the callback URL of OIDC client

Important

If you don't deploy stack with custom domain, you must complete below steps.

1. Sign in to the AWS CloudFormation console.
2. Select the solution's stack.
3. Choose the Outputs tab.
4. Obtain the ControlPlaneURL as the endpoint.
5. Update or add the callback URL to your OIDC.
   1. For Cognito, add or update the url in Allowed callback URL of your client with value ${ControlPlaneURL}/signin. NOTE: The url must start with https://.
   2. For Keycloak, add or update the url in Valid Redirect URIs of your client with value ${ControlPlaneURL}/signin.
   3. For Authing.cn, add or update the url in Login Callback URL of Authentication Configuration.

Step 4. Setup DNS Resolver

Important

If you deploy stack in AWS Regions, you can skip this step.

This solution provisions a CloudFront distribution that gives you access to the Clickstream Analytics on AWS console.

1. Sign in to the AWS CloudFormation console.
2. Select the solution's stack.
3. Choose the Outputs tab.
4. Obtain the ControlPlaneURL and CloudFrontDomainName.
5. Create a CNAME record for ControlPlaneURL in DNS resolver, which points to the domain CloudFrontDomainName obtained in previous step.

Step 5. Launch the web console

Important

Your login credentials is managed by the OIDC provider. Before signing in to the Clickstream Analytics on AWS console, make sure you have created at least one user in the OIDC provider's user pool.

1. Use the previously assigned domain name or the generated ControlPlaneURL in a web browser.
2. Choose Sign In, and navigate to OIDC provider.
3. Enter sign-in credentials. You may be asked to change your default password for first-time login, which depends on your OIDC provider's policy.
4. After the verification is complete, the system opens the Clickstream Analytics on AWS web console.

Once you have logged into the Clickstream Analytics on AWS console, you can start to create a project for your applications.