--- title: Configure NGINX for PingIntelligence description: Configure the nginx.conf setup NGINX and PingIntelligence sideband integration. Following is a summary of steps to configure NGINX for PingIntelligence: component: pingintelligence version: 5.1 page_id: pingintelligence:pingintelligence_integrations:pingintelligence_configure_nginx canonical_url: https://docs.pingidentity.com/pingintelligence/5.1/pingintelligence_integrations/pingintelligence_configure_nginx.html revdate: March 29, 2024 section_ids: create-modules-directory-and-download-pingintelligence-modules: Create modules directory and download PingIntelligence modules configure-nginx-conf: Configure nginx.conf: --- # Configure NGINX for PingIntelligence Configure the `nginx.conf` setup NGINX and PingIntelligence sideband integration. Following is a summary of steps to configure NGINX for PingIntelligence: 1. Create `modules` directory inside NGINX 2. Download PingIntelligence modules 3. Copy PingIntelligence modules in the `modules` directory 4. Edit `nginx.conf` for PingIntelligence ## Create `modules` directory and download PingIntelligence modules 1. Create a `modules` directory in NGINX: ``` # mkdir /usr/local/nginx/modules ``` 2. Download the NGINX - PingIntelligence modules from the [download](https://www.pingidentity.com/en/resources/downloads/pingintelligence.html) site 3. Untar the downloaded file. ``` # tar -xvzf rhel_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 ``` The PingIntelligence modules are: * `ngx_ase_integration_module.so` * `ngx_http_ase_integration_request_module.so` * `ngx_http_ase_integration_response_module.so` Copy the three PingIntelligence modules files for RHEL to the `modules` directory of NGINX. ``` # 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 ``` ## Configure nginx.conf: Complete the following steps to configure `nginx.conf` for PingIntelligence. Make sure that the PingIntelligence module and other configurations are added at the correct place in `nginx.conf` as shown in the sample file at the end of the section. 1. **Load PingIntelligence modules:** Edit the `nginx.conf` file to load the PingIntelligence modules. Following is a snippet of `nginx.conf` file showing the loaded PingIntelligence modules: ``` 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 ``` `IP:PORT` is the IP address of primary and secondary ASE. 2. Add primary and secondary ASE hosts in `nginx.conf` in the upstream section. Following is a snippet of `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; } ``` 3. **Configure SSL certificate:** Configure a SSL certificate location and ASE sideband authentication token in `nginx.conf`. ASE certificate was extracted from ASE in [Prerequisites](pingintelligence_nginx_prepare.html). 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 sideband authentication token was created as part of the [Prerequisites](pingintelligence_nginx_prepare.html) in the PingIntelligence section. 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 ; ``` | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You can also use your own SSL certificate by providing the path to the certificate in `set $certificate`. Make sure that ASE has the updated certificate. | 4. **Configure ASE request and response:** Configure ASE request and response API endpoints in `nginx.conf`. 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; ``` | | | | - | --------------------------------------------------------------------------------------- | | | ``` [.codeph]``ase_integration_ssl_verify`` is optional for non-SSL ASE connection. ``` | 5. **Apply PingIntelligence policy:** Apply PingIntelligence modules for APIs by configuring `location` in `nginx.conf`. `ase_integration_request` should be the first and a `ase_integration_response` should be the last. ``` location / { ase_integration_request; proxy_pass http://localhost:8080/; ase_integration_response; } ``` If you have more than more than one API, configure a `location` for each API as shown above. 6. **Verify:** 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 ``` 7. **Restart:** Restart NGINX by entering the following command: ``` # sudo /usr/local/nginx/sbin/nginx -s stop # sudo /usr/local/nginx/sbin/nginx ``` 8. 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 ``` 9. Verify that NGINX has restarted by entering the following command: ``` # netstat -tulpn | grep 4443 ``` 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; } } ```