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 Cognito and OpenSearch Dashboards.

Note: The following resolution works only for native Cognito users.

You can also use an SSH tunnel or client VPN to access OpenSearch Dashboards from outside a VPC with 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 a Cognito user pool and identity pool

Complete the following steps:

1. Create a 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 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 a 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 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 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. Run the following command to connect to your instance and install NGINX:

   sudo yum updatesudo yum install nginx -y

5. Get an SSL certificate from a certificate authority (CA).
   Note: If you use a test environment, then generate a self-signed certificate instead. In your production environment, it's a best practice to use SSL certificates that a third-party CA signs.

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.
   Note: 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 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.confsudo 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. Run the following command to activate and start NGINX:

    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 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.