Launch with OpenID Connect (OIDC)

Time to deploy: Approximately 30 minutes

Prerequisites

Important

The Centralized Logging with OpenSearch console is served via CloudFront distribution which is considered as an Internet information service. If you are deploying the solution in AWS China Regions, the domain must have a valid ICP Recordal.

A domain. You will use this domain to access the Centralized Logging with OpenSearch console (Required for AWS China Regions, 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. Note that this is required for AWS China Regions, but is not recommended for AWS Regions.
Make sure to request or import the ACM certificate in the US East (N. Virginia) Region (us-east-1). Note that this is not required for AWS China Regions, and is optional for AWS Regions.

Deployment Overview

Use the following steps to deploy this solution on AWS.

Step 1. Create OIDC client

Step 2. Launch the stack

Step 3. Setup DNS Resolver

Step 4. Launch the web console

Step 1. Create OIDC client

You can use different kinds of OpenID Connector (OIDC) 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 Standard Region as the OIDC provider.

Go to the Amazon Cognito console in an AWS Standard Region.
Set up the hosted UI with the Amazon Cognito console based on this guide.
Choose Public client when selecting the App type.
Enter the Callback URL and Sign out URL using your domain name for Centralized Logging with OpenSearch console. If your hosted UI is set up, you should be able to see something like below.
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, the OidcClientID is the App client ID, and OidcProvider is https://cognito-idp.${REGION}.amazonaws.com/${USER_POOL_ID}.

(Option 2) Authing.cn OIDC client

Go to the Authing console.
Create a user pool if you don't have one.
Select the user pool.
On the left navigation bar, select Self-built App under Applications.
Click the Create button.
Enter the Application Name, and Subdomain.
Save the App ID (that is, client_id) and Issuer to a text file from Endpoint Information, which will be used later.
Update the Login Callback URL and Logout Callback URL to your IPC recorded domain name.
Set the Authorization Configuration.

You have successfully created an authing self-built application.

(Option 3) Keycloak OIDC client

Deploy the Keycloak solution in AWS China Regions following this guide.
Sign in to the Keycloak console.
On the left navigation bar, select Add realm. Skip this step if you already have a realm.
Go to the realm setting page. Choose Endpoints, and then OpenID Endpoint Configuration from the list.
In the JSON file that opens up in your browser, record the issuer value which will be used later.
Go back to Keycloak console and select Clients on the left navigation bar, and choose Create.
Enter a Client ID, which must contain 24 letters (case-insensitive) or numbers. Record the Client ID which will be used later.
Change client settings. Enter https://<Centralized Logging with OpenSearch Console domain> in Valid Redirect URIs，and enter * and + in Web Origins.
In the Advanced Settings, set the Access Token Lifespan to at least 5 minutes.
Select Users on the left navigation bar.
Click Add user and enter Username.
After the user is created, select Credentials, and enter Password.

The issuer value is https://<KEYCLOAK_DOMAIN_NAME>/auth/realms/<REALM_NAME>.

(Option 4) ADFS OpenID Connect Client

Make sure your ADFS is installed. For information about how to install ADFS, refer to this guide.
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.
Log on your Domain Controller, and open Active Directory Users and Computers.
Create a Security Group for Centralized Logging with OpenSearch Users, and add your planned Centralized Logging with OpenSearch users to this Security Group.
Log on to ADFS server, and open ADFS Management.
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.
Record the Client Identifier (client_id) under Redirect URI, enter your Centralized Logging with OpenSearch domain (for example, xx.domain.com), and choose Add, and then choose Next.
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.
Under Summary window, choose Next, and choose Close.

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-centralized-logging-with-opensearch-domain>

Under Windows PowerShell on ADFS server, run the following command to get the Issuer (issuer) of ADFS, which is similar to https://adfs.domain.com/adfs.
```
Get-ADFSProperties | Select IdTokenIssuer
```

Step 2. Launch the stack

Important

You can only have one active Centralized Logging with OpenSearch solution stack in one region of an AWS account. If your deployment failed (for example, not meeting the requirements in prerequisites), make sure you have deleted the failed stack before retrying the deployment.

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

	Launch in AWS Console
Launch with a new VPC in AWS Regions
Launch with an existing VPC in AWS Regions
Launch with a new VPC in AWS China Regions
Launch with an existing VPC in AWS China Regions

The template is launched in the default region after you log in to the console. To launch the Centralized Logging with OpenSearch solution in a different AWS Region, use the Region selector in the console navigation bar.
On the Create stack page, verify that the correct template URL shows in the Amazon S3 URL text box and choose Next.
On the Specify stack details page, assign a name to your solution stack. For information about naming character limitations, refer to IAM and STS Limits in the AWS Identity and Access Management User Guide.

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

If you are launching the solution in a new VPC, this solution uses the following parameters:

Parameter	Default	Description
OidcClientId	`<Requires input>`	OpenID Connector client Id.
OidcProvider	`<Requires input>`	OpenID Connector provider issuer. The issuer must begin with `https://`
Domain	`<Optional>`	Custom domain for Centralized Logging with OpenSearch console. Do NOT add `http(s)` prefix.
IamCertificateID	`<Optional>`	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.
AcmCertificateArn	`<Optional>`	Arn for ACM certificates requested (or imported) the certificate in the US East (N. Virginia) Region (us-east-1).

If you are launching the solution in an existing VPC, this solution uses the following parameters:

Parameter	Default	Description
OidcClientId	`<Requires input>`	OpenID Connector client Id.
OidcProvider	`<Requires input>`	OpenID Connector provider issuer. The issuer must begin with `https://`
Domain	`<Optional>`	Custom domain for Centralized Logging with OpenSearch console. Do NOT add `http(s)` prefix.
IamCertificateID	`<Optional>`	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.
AcmCertificateArn	`<Optional>`	Arn for ACM certificates requested (or imported) the certificate in the US East (N. Virginia) Region (us-east-1).
VPC ID	`<Requires input>`	Specify the existing VPC ID in which you are launching the solution.
Public Subnet IDs	`<Requires input>`	Specify the two public subnets in the selected VPC. The subnets must have routes pointing to an Internet Gateway.
Private Subnet IDs	`<Requires input>`	Specify the two private subnets in the selected VPC. The subnets must have routes pointing to an NAT Gateway.

Important

If you are deploying the solution in AWS China Regions, you must enter Domain, and IamCertificateID.
If you are deploying the solution in AWS Regions,
- when a custom domain name is required, you must enter Domain, and AcmCertificateArn.
- when no custom domain name is required, leave it blank for Domain, IamCertificateID, and AcmCertificateArn.

Choose Next.
On the Configure stack options page, choose Next.
On the Review page, review and confirm the settings. Check the box acknowledging that the template creates AWS Identity and Access Management (IAM) resources.
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 15 minutes.

Step 3. Setup DNS Resolver

This solution provisions a CloudFront distribution that gives you access to the Centralized Logging with OpenSearch console.

Sign in to the AWS CloudFormation console.
Select the solution's stack.
Choose the Outputs tab.
Obtain the WebConsoleUrl as the endpoint.
Create a CNAME record in DNS resolver, which points to the endpoint address.

Step 4. Launch the web console

Important

You login credentials is managed by the OIDC provider. Before signing in to the Centralized Logging with OpenSearch console, make sure you have created at least one user in the OIDC provider's user pool.

Use the previous assigned CNAME to open the OIDC Customer Domain URL using a web browser.
Choose Sign in to Centralized Logging with OpenSearch, and navigate to OIDC provider.
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.
After the verification is complete, the system opens the Centralized Logging with OpenSearch web console.

Once you have logged into the Centralized Logging with OpenSearch console, you can import an Amazon OpenSearch Service domain and build log analytics pipelines.