How do I use an NGINX proxy to access OpenSearch Dashboards with Amazon Cognito authentication from outside a VPC?

Short description

Use NGINX to configure an Amazon Elastic Compute Cloud (Amazon EC2) instance as a proxy server. The proxy server then forwards browser requests to Amazon Cognito and OpenSearch Dashboards.

Note: This solution works for native Amazon Cognito users only.

You can also use an SSH tunnel or Client VPN to access OpenSearch Dashboards from outside a VPC with Amazon Cognito authentication. For more information, see How can I use Amazon Cognito authentication to access OpenSearch Dashboards from outside of a VPC?

Resolution

Important: Your OpenSearch Service domain is more secure when you restrict access to users in the VPC. Before you continue, check that this resolution doesn't violate your organization's security requirements.

Create an Amazon Cognito user pool

Create a new user pool and configure the following settings:

• For Cognito user pool sign-in options, select Email.
• For Multi-factor authentication, select No MFA.
• For Self-service sign-up, clear Enable self-registration.
• For Email, select Send email with Cognito.

Configure a hosted user pool domain

Create an app client for hosted UI sign-in and configure the following settings:

• For User Pools, select your user pool.
• For App Integration, choose Create Cognito domain.

Create a user in the Amazon Cognito user pool

Complete the following steps:

1. Open the Amazon Cognito console.
2. Choose User Pools, and then choose Users.
3. Choose Create user, and then configure the settings.
4. Under User information, for Email address, enter an email address. Then, select Mark email as verified.

Configure an identity pool

Create an identity pool in Amazon Cognito and configure the following settings:

• For Configure identity pool trust, select Authenticated access.
• For Authenticated identity sources, select Amazon Cognito user pools.
• For Configure permissions, select Create new IAM role.
• For Connect identity providers, proceed to the next step. You can configure this field after you create the identity pool.

Configure your OpenSearch Service domain to use Amazon Cognito Authentication

Configure your OpenSearch Service domain to use Amazon Cognito authentication for OpenSearch Dashboards. Configure the following settings:

• For Cognito User Pool, select your user pool.
• For Cognito Identity Pool, select your identity pool.

Configure your OpenSearch Service access policy

Complete the following steps:

1. Open the Amazon Cognito console.
2. Select your identity pool.
3. Choose User Access.
4. Copy the Authenticated Role ARN value.
5. Configure your OpenSearch Service access policy to a resource-based policy. Enter the following policy:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": {
           "AWS": "<authenticated_role_arn>"
         },
         "Action": "es:*",
         "Resource": "arn:aws:es:region:aws-account-id:domain/domain-name/*"
       }
     ]
   }

   Replace the following values:
   account-id with your AWS account ID.
   authenticated_role_arn with the authenticated role ARN.
   domain-name with the name of your domain
   Region with your domain's AWS Region.

Configure the NGINX proxy

Note: The following settings apply to an Amazon Machine Image (AMI) on Amazon Linux 2023. If you use a different AMI, then you might need to adjust the settings.

Complete the following steps:

1. Launch an Amazon EC2 instance in the public subnet of the VPC that your OpenSearch Service domain is in. The instance must use the same security group as your domain.

2. (Optional) If you don't use a test environment, then allocate an Elastic IP address to associate with your EC2 instance.

3. (Optional) If you don't use a test environment, then configure your DNS to resolve requests to the Elastic IP address. For more information about how to resolve requests with Amazon Route 53, see Configuring Amazon Route 53 to route traffic to an Amazon EC2 instance.

4. To connect to your instance and install NGINX, run the following command:

   $ sudo yum update
   $ sudo yum install nginx -y

5. To configure SSL for NGINX, get an SSL certificate from a certificate authority (CA).
   Note: If you use a test environment, then generate a self-signed certificate instead. It's a best practice to use SSL certificates signed by a third-party certificate authority only in your production environment.

6. (Optional) If you use a test environment with a self-signed certificate, then to generate a private key, run the OpenSSL x509 command:

   $ sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/nginx/cert.key -out /etc/nginx/cert.crt

   For more information, see x509 on the OpenSSL website.
   The preceding command generates cert.key, a private key for the self-signed SSL certificate.

7. Navigate to the /etc/nginx/conf.d directory, and then create a file titled default.conf.

8. Modify the default.conf file with the following values:
   For /etc/nginx/cert.crt, enter the path to your SSL certificate.
   For /etc/nginx/cert.key, enter the path to the private key that you generated for the SSL certificate.
   For my_domain_host, enter your OpenSearch Service endpoint.
   For my_cognito_host, enter your Amazon Cognito user pool domain.
   Important: You must use HTTPS.
   If your Amazon OpenSearch Service domain runs OpenSearch Service version 1.0+, then use the _dashboards endpoint.
   If your Amazon OpenSearch Service domain runs Elasticsearch versions 5.x-7.x, then use the _plugin/kibana endpoint.

   Note: The resolver value changes based on your VPC settings. Use the DNS resolver at your primary CIDR block's base IP address plus two. For example, if you create a VPC with CIDR block 10.0.0.0/24, then your DNS resolver is located at 10.0.0.2.

   Example default.conf file:

   server {  listen 443;
     server_name $host;
     rewrite ^/$ https://$host/_dashboards redirect;
     resolver 10.0.0.2 ipv6=off valid=5s;
     set $domain_endpoint my_domain_host;
     set $cognito_host my_cognito_host;
   
     ssl_certificate           /etc/nginx/cert.crt;
     ssl_certificate_key       /etc/nginx/cert.key;
   
     ssl on;
     ssl_session_cache  builtin:1000  shared:SSL:10m;
     ssl_protocols  TLSv1 TLSv1.1 TLSv1.2;
     ssl_ciphers HIGH:!aNULL:!eNULL:!EXPORT:!CAMELLIA:!DES:!MD5:!PSK:!RC4;
     ssl_prefer_server_ciphers on;
   
     location ^~ /_dashboards {
   
       # Forward requests to Dashboards
       proxy_pass https://$domain_endpoint;
   
       # Handle redirects to Cognito
       proxy_redirect https://$cognito_host https://$host;
   
       # Handle redirects to Dashboards
       proxy_redirect https://$domain_endpoint https://$host;
   
       # Update cookie domain and path
       proxy_cookie_domain $domain_endpoint $host;
       proxy_cookie_path ~*^/$ /_dashboards/;
   
       # Response buffer settings
       proxy_buffer_size 128k;
       proxy_buffers 4 256k;
       proxy_busy_buffers_size 256k;
     } 
   
     location ~ \/(log|sign|fav|forgot|change|saml|oauth2|confirm) {
   
       # Forward requests to Cognito
       proxy_pass https://$cognito_host;
   
       # Handle redirects to Dashboards
       proxy_redirect https://$domain_endpoint https://$host;
   
       # Handle redirects to Cognito
       proxy_redirect https://$cognito_host https://$host;
   
       proxy_cookie_domain $cognito_host $host;
     }
   }

9. (Optional) To assign my_domain_host and my_cognito_host as variables, run the sed command:

   sudo sed -i 's/my_domain_host/vpc-cognito-private-xxxxxxxxxx.us-east-1.es.amazonaws.com/' /etc/nginx/conf.d/default.conf
   sudo sed -i 's/my_cognito_host/domain-xxxxxxx.auth.us-east-1.amazoncognito.com/' /etc/nginx/conf.d/default.conf

   Note: If you run the preceding command, then you don't have to replace my_domain_host and my_cognito_host in the /etc/nginx/conf.d/default.conf file.

10. To activate and start NGINX, run the following command:

    $ sudo systemctl enable nginx && sudo systemctl start nginx

Access OpenSearch Dashboard

Complete the following steps:

1. Use your browser to open the NGINX IP address or the DNS name. Now, this redirects you to the Amazon Cognito login page.
2. To log in to OpenSearch Dashboards, enter your username and temporary password. Then, change your password when prompted, and log in again.