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: The following resolution works only for native Amazon Cognito users.

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: When you restrict access to users in your VPC, your OpenSearch Service domain is more secure. Before you continue, make sure that this resolution aligns with your organization's security requirements.

Create an Amazon Cognito user pool and identity pool

Complete the following steps:

1. Create an Amazon Cognito user pool. Configure the following settings:
   For Application type, choose Traditional web application.
   For Name your application, enter a custom application name or keep the default name.
   For Options for sign-in identifiers, choose Username.
   For Required attributes for sign-up, choose Email.

2. Open the Amazon Cognito console.

3. In the navigation pane, choose User pools.

4. Select your User pool, and then configure the following settings: 
   In the navigation pane, under Branding, choose Managed Login.
   For Domains with managed login branding, choose Update version.
   For Branding version, choose Hosted UI (classic).

5. Configure your users and groups.

6. Create an Amazon Cognito identity pool. Configure the following settings:
   For User Access, choose Authenticated access.
   For Authenticated identity sources, enter Amazon Cognito user pool.
   For IAM role, choose Create a new IAM role, and then enter a role name.
   For User pool details, select your user pool ID, and then choose App client ID.
   For Role settings, choose Use default authenticated role.
   For Claim mapping, choose Inactive.

7. Configure your OpenSearch Service domain to use Amazon Cognito authentication. Configure the following settings:
   For Cognito User Pool, select your user pool.
   For Cognito Identity Pool, select your identity pool.

8. For Domain access policy , enter the following access policy:

     
   {  "Version": "2012-10-17",  
     "Statement": \[  
       {  
         "Effect": "Allow",  
         "Principal": {  
           "AWS": "arn:aws:iam::account-id:role/service-role/identitypool-role"  
         },  
         "Action": "es:\*",  
         "Resource": "arn:aws:es:region:account-id:domain/domain-name/\*"  
       }  
     \]  
   }

   Note: Replace account-id with your AWS account ID and identitypool-role with the name of your identity pool role. Replace domain-name with your OpenSearch Service domain, and 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 that are 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 run the OpenSSL x509 command to generate a private key:

   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 that's a private key for the self-signed SSL certificate.

7. Navigate to the /etc/nginx/conf.d directory, and then create a file that's named 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 or later, 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 ssl;
     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 Dashboards

Complete the following steps:

1. Use your browser to open the NGINX IP address or the DNS name that redirects you to the Amazon Cognito login page.
2. Enter your username and temporary password to log in to OpenSearch Dashboards.
3. When prompted, change your password and log in again.