--- title: Configuring NGINX description: Configure NGINX for your operating system and then for PingIntelligence. component: pingintelligence version: 5.2 page_id: pingintelligence:pingintelligence_integrations:pingintelligence_nginx_configure canonical_url: https://docs.pingidentity.com/pingintelligence/5.2/pingintelligence_integrations/pingintelligence_nginx_configure.html revdate: April 3, 2024 section_ids: about-this-task: About this task configuring-nginx-for-rhel-7-6: Configuring NGINX for RHEL 7.6 about-this-task-2: About this task steps: Steps result: Result: configuring-nginx-for-ubuntu-16-04: Configuring NGINX for Ubuntu 16.04 about-this-task-3: About this task steps-2: Steps result-2: Result: configuring-nginx-for-pingintelligence: Configuring NGINX for PingIntelligence about-this-task-4: About this task steps-3: Steps example: Example: example-2: Example: example-3: Example: example-4: Example: example-5: Example: --- # Configuring NGINX Configure NGINX for your operating system and then for PingIntelligence. ## About this task To configure NGINX, complete the following configuration steps: 1. Configure NGINX for either RHEL 7.6 or Ubuntu 16.04. 2. Configure NGINX for PingIntelligence. * RHEL 7.6 * Ubuntu 16.04 ## Configuring NGINX for RHEL 7.6 Configure NGINX for RHEL 7.6. ### About this task To compile NGINX Community Edition 1.14.2 for PingIntelligence for APIs: ### Steps 1. Download the NGINX community version: ``` # wget https://nginx.org/download/nginx-1.14.2.tar.gz ``` 2. Untar the NGINX file: ``` # tar -xvzf nginx-1.14.2.tar.gz ``` 3. Change the directory to `nginx-1.14.2`: ``` # cd nginx-1.14.2 ``` 4. Compile and install NGINX by running the following command. | | | | - | --------------------------------------------------------------------------------------- | | | These options for compiling NGINX are in addition to your environment specific options. | ``` # ./configure --with-compat --with-http_ssl_module ``` * `--with-compat`: This option enables NGINX to load dynamic modules. * `--with_http_ssl_module`: This flag is used configure SSL support in NGINX. 5. Run the `make` command to compile NGINX: ``` # make ``` 6. Run the `make install` command to install NGINX: ``` # sudo make install ``` 7. Verify the compilation by entering the following command: ``` # sudo /usr/local/nginx/sbin/nginx -V ``` #### Result: The output of the above command should display `--with-compat` and `--with_http_ssl_module` flags. ## Configuring NGINX for Ubuntu 16.04 Configure NGINX for Ubuntu 16.04. ### About this task To compile NGINX Community Edition 1.14.2 for PingIntelligence for APIs: ### Steps 1. Download the NGINX community version: ``` # wget https://nginx.org/download/nginx-1.14.2.tar.gz ``` 2. Untar the NGINX file: ``` # tar -xvzf nginx-1.14.2.tar.gz ``` 3. Change the directory to `nginx-1.14.2`: ``` # cd nginx-1.14.2 ``` 4. Compile and install NGINX by running the following command. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | These options for compiling NGINX are in addition to your environment-specific options:- `--with-compat`: This option enables NGINX to load dynamic modules. - `--with_http_ssl_module`: This flag is used configure Secure Sockets Layer (SSL) *(tooltip: \
\

A protocol for authenticated and encrypted links between networked machines, typically over HTTPS. SSL was deprecated in 1999 in favor of Transport Layer Security (TLS).\

\
)* support in NGINX. | ``` # ./configure --with-compat --with-http_ssl_module ``` 5. Run the `make` command to compile NGINX: ``` # make ``` 6. Run the `make install` command to install NGINX: ``` # sudo make install ``` 7. Verify the compilation by entering the following command: ``` # sudo /usr/local/nginx/sbin/nginx -V ``` #### Result: The output of the above command should display `--with-compat` and `--with_http_ssl_module` flags. ## Configuring NGINX for PingIntelligence Configure the `nginx.conf` setup NGINX and PingIntelligence sideband integration. ### About this task To configure NGINX for PingIntelligence: ### Steps 1. Create a `modules` directory in NGINX: ``` # mkdir /usr/local/nginx/modules ``` 2. Download the NGINX - PingIntelligence policy modules from the [PingIntelligence Downloads site](https://www.pingidentity.com/en/resources/downloads/pingintelligence.html). 3. Untar the downloaded file. ``` tar -xvzf ubuntu_modules_1.14.2.tgz modules/ modules/nginx-oss-list.txt modules/ngx_ase_integration_module.so modules/ngx_http_ase_integration_response_module.so modules/ngx_http_ase_integration_request_module.so ``` 4. Copy the three PingIntelligence modules for Ubuntu to the `modules` directory of NGINX. The three PingIntelligence modules are: * `ngx_ase_integration_module.so` * `ngx_http_ase_integration_request_module.so` * `ngx_http_ase_integration_response_module.so` ``` # cp ngx_ase_integration_module.so /usr/local/nginx/modules # cp ngx_http_ase_integration_request_module.so /usr/local/nginx/modules # cp ngx_http_ase_integration_response_module.so /usr/local/nginx/modules ``` 5. Edit the `nginx.conf` file to load the PingIntelligence modules. #### Example: The following is a snippet of the `nginx.conf` file showing the loaded PingIntelligence modules. `IP:PORT` is the IP address of primary and secondary ASE. ``` worker_processes 1; error_log /usr/local/nginx/logs/error.log debug; worker_rlimit_core 500M; working_directory /usr/local/nginx; pid /usr/local/nginx/pid/nginx.pid; load_module modules/ngx_ase_integration_module.so; load_module modules/ngx_http_ase_integration_request_module.so; load_module modules/ngx_http_ase_integration_response_module.so; events { worker_connections 1024; } http \{ keepalive_timeout 65; upstream pi.ase \{ server IP:PORT max_fails=1 max_conns=1024 fail_timeout=10; server IP:PORT max_fails=1 max_conns=1024 fail_timeout=10 backup; keepalive 32; } truncated nginx.conf ``` 6. Add primary and secondary ASE hosts in `nginx.conf` in the upstream section. #### Example: The following is a snippet of the `nginx.conf` file with an ASE primary and secondary host configuration: ``` http { keepalive_timeout 65; upstream pi.ase { server 192.168.11.12:443 max_fails=3 max_conns=1024 fail_timeout=10; server 192.168.11.13:443 max_fails=3 max_conns=1024 fail_timeout=10 backup; keepalive 32; } ``` 7. Configure an SSL certificate location and ASE sideband authentication token in `nginx.conf`. Copy the certificate to `/usr/local/nginx/ssl/test.ase.pi` on the NGINX machine and configure the certificate path in `nginx.conf` file. The ASE certificate was extracted from ASE in [Preparing to deploy the PingIntelligence policy](pingintelligence_nginx_prepare.html). The sideband authentication token was created in step 1c of [Preparing to deploy the PingIntelligence policy](pingintelligence_nginx_prepare.html). | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You can also use your own SSL *(tooltip: \
\

A protocol for authenticated and encrypted links between networked machines, typically over HTTPS. SSL was deprecated in 1999 in favor of Transport Layer Security (TLS).\

\
)* certificate by providing the path to the certificate in `set $certificate`. Make sure that ASE has the updated certificate. | #### Example: The following is a snippet the showing certificate location and sideband authentication token: ``` #Certificiate location of ASE set $certificate /usr/local/nginx/ssl/test.ase.pi; #ASE Token for sideband authentication set $ase_token ; ``` 8. Configure ASE request and response API endpoints in `nginx.conf`. | | | | - | -------------------------------------------------------------------- | | | `ase_integration_ssl_verify` is optional for non-SSL ASE connection. | #### Example: The following snippet of `nginx.conf` shows ASE request and response: ``` #ASE Request Proxy Configuration location = /ase/request { internal; ase_integration https://pi.ase; ase_integration_method "POST"; ase_integration_http_version 1.1; ase_integration_ase_token $ase_token; ase_integration_correlation_id $correlationid; ase_integration_host pi.ase; ase_integration_ssl_trusted_certificate /usr/local/nginx/ssl/test.ase.pi; ase_integration_ssl_verify off; ase_integration_ssl_verify_depth 1; ase_integration_ssl_server_name on; ase_integration_ssl_name test.ase.pi; ase_integration_next_upstream error timeout non_idempotent; #ASE Response Proxy Configuration location = /ase/response { internal; ase_integration https://pi.ase; ase_integration_method "POST"; ase_integration_http_version 1.1; ase_integration_ase_token $ase_token; ase_integration_correlation_id $correlationid; ase_integration_host pi.ase; ase_integration_ssl_trusted_certificate /usr/local/nginx/ssl/test.ase.pi; ase_integration_ssl_verify off; ase_integration_ssl_verify_depth 1; ase_integration_ssl_server_name on; ase_integration_ssl_name test.ase.pi; ase_integration_next_upstream error timeout non_idempotent; ``` 9. Apply PingIntelligence modules for APIs by configuring `location` in `nginx.conf`. `ase_integration_request` should be the first, and an `ase_integration_response` should be the last. ``` location /shop { ase_integration_request; proxy_pass http://localhost:8000/; ase_integration_response; } ``` If you have more than more than one API, configure a `location` for each API as shown above. 10. Verify that `nginx.conf` is syntactically correct by running the following command: ``` # sudo /usr/local/nginx/sbin/nginx -t nginx: the configuration file /usr/local/nginx/conf/nginx.conf syntax is ok nginx: configuration file /usr/local/nginx/conf/nginx.conf test is successful ``` 11. Restart NGINX by entering the following command: ``` # sudo /usr/local/nginx/sbin/nginx -s stop # sudo /usr/local/nginx/sbin/nginx ``` 12. Run the following command to verify if `--with-compat` and `--with-http_ssl_module` is in the list of flags under configured arguments: ``` # sudo /usr/local/nginx/sbin/nginx -V nginx version: nginx/1.14.2 built by gcc 5.4.0 20160609 (Ubuntu 5.4.0-6ubuntu1~16.04.11) built with OpenSSL 1.0.2g 1 Mar 2016 TLS SNI support enabled configure arguments: --with-compat --with-http_ssl_module ``` 13. Verify that NGINX has restarted by entering the following command: ``` # netstat -tulpn | grep 4443 ``` #### Example: The following is a sample `nginx.conf` for reference: ``` worker_processes 1; error_log /usr/local/nginx/logs/error.log debug; worker_rlimit_core 500M; working_directory /usr/local/nginx; pid /usr/local/nginx/pid/nginx.pid; load_module modules/ngx_ase_integration_module.so; load_module modules/ngx_http_ase_integration_request_module.so; load_module modules/ngx_http_ase_integration_response_module.so; events { worker_connections 1024; } http \{ keepalive_timeout 65; upstream pi.ase \{ server IP:PORT max_fails=1 max_conns=100 fail_timeout=10; server IP:PORT max_fails=1 max_conns=100 fail_timeout=10 backup; keepalive 32; } server { # remove "ssl" from the below line for a non-SSL frontend listen 4443 ssl bind; server_name localhost; # Comment out the next 5-lines for a non-SSL frontend ssl_certificate /usr/local/nginx/ssl/cert.pem; ssl_certificate_key /usr/local/nginx/ssl/key.pem; ssl_password_file /usr/local/nginx/ssl/password_file; ssl_protocols TLSv1.2; ssl_ciphers HIGH:!aNULL:!MD5; #root /usr/share/nginx/html; #charset koi8-r; #access_log /var/log/nginx/host.access.log main; resolver 8.8.8.8 ipv6=off; #The following location configuration is to configure your application. A corresponding API JSON should be present in ASE. location / { ase_integration_request; proxy_pass http://localhost:8080/; ase_integration_response; } #The following configuration is a Ping Intelligence configuration and do not edit set $correlationid $pid-$request_id-$server_addr-$remote_addr-$remote_port-$request_length-$connection; # ASE token must be configured # ASE certificate must be copied under /usr/local/nginx/ssl/ and update the set $certificate to the # certificate file path #Certificate location of ASE set $certificate /usr/local/nginx/ssl/test.ase.pi; #ASE Token for sideband authentication set $ase_token ; #Host header which should be send to ASE set $ase_host pi.ase; #SNI value to use for ASE set $ase_ssl_host pi.ase; #ASE Request Proxy Configuration location = /ase/request { internal; ase_integration https://pi.ase; ase_integration_method "POST"; ase_integration_http_version 1.1; ase_integration_ase_token $ase_token; ase_integration_correlation_id $correlationid; ase_integration_host $ase_host; ase_integration_ssl_trusted_certificate $certificate; ase_integration_ssl_verify off; ase_integration_ssl_verify_depth 1; ase_integration_ssl_server_name off; ase_integration_ssl_name $ase_ssl_host; ase_integration_next_upstream error timeout non_idempotent; } #ASE Response Proxy Configuration location = /ase/response { internal; ase_integration https://pi.ase; ase_integration_method "POST"; ase_integration_http_version 1.1; ase_integration_ase_token $ase_token; ase_integration_correlation_id $correlationid; ase_integration_host $ase_host; ase_integration_ssl_trusted_certificate $certificate; ase_integration_ssl_verify off; ase_integration_ssl_verify_depth 1; ase_integration_ssl_server_name off; ase_integration_ssl_name $ase_ssl_host; ase_integration_next_upstream error timeout non_idempotent; } } ```