---
title: Configuring NGINX Plus with PingAccess agent for PingIntelligence
description: You can install PingIntelligence sideband policy on NGINX Plus R22 or R23 systems with PingAccess agent.
component: pingintelligence
version: 5.2
page_id: pingintelligence:pingintelligence_integrations:pingintelligence_configure_nginx_plus_with_pa_agent
canonical_url: https://docs.pingidentity.com/pingintelligence/5.2/pingintelligence_integrations/pingintelligence_configure_nginx_plus_with_pa_agent.html
revdate: April 3, 2024
section_ids:
  before-you-begin: Before you begin
  about-this-task: About this task
  steps: Steps
  next-steps: Next steps
---

# Configuring NGINX Plus with PingAccess agent for PingIntelligence

You can install PingIntelligence sideband policy on NGINX Plus R22 or R23 systems with PingAccess agent.

## Before you begin

Make sure the following prerequisites are complete before you configure NGINX Plus with PingIntelligence policy:

* API Security Enforcer (ASE) is installed, and the pre-conditions listed under [prequisites for PingIntelligence](pingintelligence_nginx_plus_prepare.html) are met.

* PingAccess and PingFederate are installed.

* PingAccess agent is installed and configured on NGINX. For more information, see [PingAccess Agent for NGINX](https://docs.pingidentity.com/bundle/pingaccess-62/page/avq1564006746975.html).

* PingAccess is configured to use PingFederate as a token provider and token introspection is enabled on PingAccess. For more information, see [Configure PingFederate as the token provider for PingAccess](https://docs.pingidentity.com/bundle/pingaccess-62/page/avq1564006746975.html).

## About this task

Configure the `nginx.conf` to setup NGINX Plus and PingIntelligence sideband policy. Complete the following steps to integrate the sideband policy:

## Steps

1. Download the NGINX Plus - PingIntelligence modules from the [download](https://www.pingidentity.com/en/resources/downloads/pingintelligence.html) site

2. Untar the downloaded file.

   ```
   # tar -xvzf pi-api-nginx-plus-policy-5.0.tar
   ```

3. Copy the PingIntelligence modules files for RHEL to the modules directory of NGINX Plus and `pi-pf.conf` file to `/nginx/conf/` directory.

4. Change to `root` user.

   ```
   # sudo su
   ```

5. Configure the `nginx.conf` file. Complete the following steps to configure `nginx.conf` for PingIntelligence:

   * Edit the `nginx.conf` file to load the PingIntelligence modules. Following is a snippet of `nginx.conf` file showing the loaded PingIntelligence module.

     ```
     user  nginx;
     worker_processes  auto;
     error_log  /var/log/nginx/error.log debug;
     pid        /var/run/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;load_module modules/ngx_http_paa_module.so;

     events {
         worker_connections  1024;
     }
     ```

     |   |                                                                  |
     | - | ---------------------------------------------------------------- |
     |   | Make sure the modules are loaded in the order highlighted above. |

   * Configure ASE primary and secondary node IP address by replacing IP:PORT in the `nginx.conf` file as shown in the following snippet.

     ```
     http {

         upstream test.ase.pi {
            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;
     #      keepalive_timeout 3600s; # NOT allowed < 1.15.3
        }
     ```

   * Configure the following ASE parameters in `ngnix.conf` file:

     | Parameter      | Description                            |
     | -------------- | -------------------------------------- |
     | `certificate`  | Certificate location of ASE            |
     | `ase_token`    | ASE Token for sideband authentication  |
     | `ase_host`     | Host header that should be send to ASE |
     | `ase_ssl_host` | SNI value to use for ASE               |

     ```
     #DO NOT EDIT BELOW VARIABLE
         set $correlationid $pid-$request_id-$server_addr-$remote_addr-$remote_port-$request_length-$connection;
         #Certificate location of ASE
         set  $certificate  /etc/ssl/nginx/test.ase.pi;
         #ASE Token for sideband authentication
         set  $ase_token  76748f33353940efab31e9fbe15d930a;
         #Host header which should be send to ASE
         set  $ase_host  test.ase.pi;
         #SNI value to use for ASE
         set  $ase_ssl_host  test.ase.pi;
     ```

6. Add PingIntelligence sideband policy

   * To apply PingIntelligence policy globally, add`ase_integration_request` and `ase_integration_response`in the server section of `nginx.conf` as shown in the following snippet:

     ```
     server {
         listen              44444 ssl bind;
         server_name         localhost;
         ssl_certificate     /etc/nginx/ssl/cert.pem;
         ssl_certificate_key /etc/nginx/ssl/key.pem;
         ssl_protocols       TLSv1.2;
         ssl_ciphers         HIGH:!aNULL:!MD5;
         add_header Allow "GET, POST, HEAD" always;
          ase_integration_request;
          ase_integration_response;

             truncated nginx.conf file
     ```

   * To apply PingIntelligence sideband policy for a specific API, configure`location` in`nginx.conf` as shown in the following snippet:

     ```
     location / {
            include /usr/local/nginx/conf/pi-pf.conf;
            ase_integration_request;
            proxy_pass http://localhost:8080/;
            ase_integration_response;
     }

     truncated nginx.conf file
     ```

   Note: When configuring the policy for individual APIs, comment-out `ase_integration_request` and`ase_integration_response`that are added to apply PingIntelligence policy globally.

7. Run the following command and verify syntactical correctness of `nginx.conf`file:

   ```
   # /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
   ```

8. Restart NGINX by entering the following command.

   ```
   # /usr/local/nginx/sbin/nginx -s stop
   # /usr/local/nginx/sbin/nginx
   ```

## Next steps

* Verify that NGINX has restarted by entering the following command:

  ```
  # netstat -tulpn | grep <NGINX port number>
  For example : # netstat -tulpn | grep 4443
  ```

* Configure API JSON file as explained in [Configuring API JSON to extract user information](pingintelligence_nginx_plus_configure_api_json.html).

Sample nginx.conf file - The following is a sample `nginx.conf` file.

```
user  nginx;
worker_processes  auto;

error_log  /var/log/nginx/error.log debug;
pid        /var/run/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;
load_module modules/ngx_http_paa_module.so;

events {
    worker_connections  1024;
}

http {
    include       /etc/nginx/paa/http.conf;
    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';

    access_log  /var/log/nginx/access.log  main;

    sendfile        on;
    #tcp_nopush     on;

    keepalive_timeout  65;
    upstream test.ase.pi {
       server 127.1.1.1:8443  max_fails=1 max_conns=100 fail_timeout=10;
       server 127.1.1.1:8443  max_fails=1 max_conns=100 fail_timeout=10 backup;
       keepalive 32;
#      keepalive_timeout 3600s; # NOT allowed < 1.15.3
   }

  server {
    listen              44444 ssl bind;
    server_name         localhost;
    ssl_certificate     /etc/nginx/ssl/cert.pem;
    ssl_certificate_key /etc/nginx/ssl/key.pem;
    ssl_protocols       TLSv1.2;
    ssl_ciphers         HIGH:!aNULL:!MD5;
    add_header Allow "GET, POST, HEAD" always;
   location /todo/api-only {
       ase_integration_request;
       proxy_pass https://172.16.40.38:8443/todo/api-only;
       proxy_ssl_verify              off;
       ase_integration_response;
          }
    location /shopapi {
      proxy_pass https://172.16.40.70:4100/shopapi;
     proxy_ssl_verify              off;
          }
 #DO NOT EDIT BELOW VARIABLE
    set $correlationid $pid-$request_id-$server_addr-$remote_addr-$remote_port-$request_length-$connection;
    #Certificate location of ASE
    set $certificate /etc/ssl/nginx/test.ase.pi;
    #ASE Token for sideband authentication
    set $ase_token 76748f33353940efab31e9fbe15d930a;
    #Host header which should be send to ASE
    set $ase_host test.ase.pi;
    #SNI value to use for ASE
    set $ase_ssl_host test.ase.pi;
    #ASE Request Proxy Configuration
    location = /ase/request {
       internal;
       ase_integration https://test.ase.pi;
       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;
       # set token key here.
       ase_integration_token_key access_token;
       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://test.ase.pi;
       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;
    }

location /introspect {
      internal;
        proxy_method    POST;
        if ($arg_auth_token) {
            set $auth_token $arg_auth_token;
        }
        if ($http_authorization ~* .?(bearer)(\s+)([-a-zA-Z0-9._~+/]+)(,|\s|$)) {
            set $auth_token $3;
        }
        #proxy_set_header  Content-Type "application/x-www-form-urlencoded";
        proxy_pass_request_body off;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_pass      $oauth_url;
        proxy_read_timeout   60;
        proxy_set_header authorization "";
    }

}

 include /etc/nginx/conf.d/.conf;

  }
```