Configure trusted proxies

 

We strongly encourage you to use the Conjur configuration file to define trusted proxies. Once defined, settings can be applied across single or multiple nodes, simplifying configuration. For more information, see Manage Conjur configuration.

Trusted proxies are defined inside the Conjur Server container for the Leader, Standbys, and Followers.

Trusted proxies are configured as IP address blocks in CIDR (Classless Inter Domain Routing) notation, allowing you to designate trusted proxies by either individual or multiple IP addresses, or by trusted IP subnets.

Trusted proxies can be configured in the following ways:

  • Conjur configuration file

  • evoke proxy commands

Conjur configuration file

You can configure trusted proxies in the Conjur configuration file. A conjur.yml file is required for each node in your environment and its settings are applied by running evoke configuration apply on each node.

You can find the conjur.yml file in /etc/conjur/config.

Single IP address or subnet

  1. Open the conjur.yml file.

  2. Add the IP address of a trusted proxy using a single argument:

     
    trusted_proxies:
      - 192.168.1.1
    
  3. Run:

    evoke configuration apply

    If validation is successful, a Conjur server reboot is initiated and the new configuration is applied.

    If validation is not successful, evoke terminates the command, issues an error code to the console, and displays the incorrect variable. The configuration of the target node is not updated and Conjur services continue to operate with the prior configuration.

Multiple IP addresses

  1. Open the conjur.yml file.

  2. Add the IP addresses of multiple trusted proxies using multiple arguments:

     
    trusted_proxies:
      - 192.0.2.1 
      - 192.0.2.2 
      - 192.0.2.3
    
  3. Run:

    evoke configuration apply

    If validation is successful, a Conjur server reboot is initiated and the new configuration is applied.

    If validation is not successful, evoke terminates the command, issues an error code to the console, and displays the incorrect variable. The configuration of the target node is not updated and Conjur services continue to operate with the prior configuration.

CIDR blocks

  1. Open the conjur.yml file.

  2. For example, to add the network IP address range 192.0.2.0/24 (192.0.2.0 - 192.0.2.255), add the address range as shown below:

     
    trusted_proxies:
      - 192.0.2.0/24
  3. Run:

    evoke configuration apply

    If validation is successful, a Conjur server reboot is initiated and the new configuration is applied.

    If validation is not successful, evoke terminates the command, issues an error code to the console, and displays the incorrect variable. The configuration of the target node is not updated and Conjur services continue to operate with the prior configuration.

Evoke proxy commands

You can also configure trusted proxies using evoke proxy commands (add, list, remove, unset).

 

The evoke proxy commands are deprecated and will be removed in a future release. If you use evoke proxy commands, you'll see a warning message on the console. We strongly recommend configuring trusted proxies in the conjur.yml file.

Add trusted proxies

The evoke proxy add command allows you to add new trusted proxy IP addresses or CIDR blocks.

 

When the evoke proxy add, evoke proxy remove, and evoke proxy unset commands run, they restart the Conjur service in Conjur to apply the changes. API clients that are connected or attempt to connect during this restart, receive an HTTP error response. Subsequent API client connections should be successful once the Conjur service resumes.

 

Trusted proxy configuration is not replicated from the Leader node and must be defined on all Conjur nodes. This requires running evoke proxy add on each Leader, Standby and Follower, as described below.

Single IP address or subnet

To add a new trusted proxy, use the evoke proxy add command with the IP address as the single argument:

 
$ docker exec container1 sh -c "
  evoke proxy add 192.0.2.0
"

Result:

 
Stopping service 'conjur'... 
ok: down: conjur: 0s, normally up 
Starting service 'conjur'... 
ok: run: conjur: (pid 8146) 0s 
192.0.2.0

Multiple IP addresses

Multiple IP addresses, or CIDR blocks, can be provided to evoke proxy add to configure more than one trusted proxy at a time.

For example, to add the following IP addresses: 192.0.2.1, 192.0.2.2, 192.0.2.3, run the following command:

 
$ docker exec container1 sh -c "evoke proxy add 192.0.2.1 192.0.2.2 192.0.2.3”

Result:

 
Stopping service 'conjur'...  
ok: down: conjur: 0s, normally up  
Starting service 'conjur'...  
ok: run: conjur: (pid 6395) 1s  
192.0.2.1,192.0.2.2,192.0.2.3

CIDR blocks

To add a subnet to the trusted proxies configuration, use a CIDR-notated address range as the argument for evoke proxy add.

For example, to add the network IP address range 192.0.2.0/24(192.0.2.0 - 192.0.2.255), run the command:

 
$ docker exec container1 sh -c "evoke proxy add 192.0.2.0/24”

Result:

 
Stopping service 'conjur'...  
ok: down: conjur: 0s, normally up  
Starting service 'conjur'...  
ok: run: conjur: (pid 17860) 1s  
192.0.2.0/24

Verify trusted proxies

After configuring trusted proxies, it is important to verify their configuration by issuing a REST API request from a known IP address using the /whoami API endpoint. The IP address returned in the REST API response uses the configured trusted proxies to determine the client IP. If the response IP equals the client's actual IP, then Conjur has been properly configured to source IP addresses for your clients.

There are two additional ways in which to view and verify the client IP address:

  • HTTP request entries in the application logs contain the IP address as shown in the following example:

     
    <14>1 2020-10-06T19:20:50.000+00:00 c2cbedf1dc33 conjur-possum 1057 - [meta sequenceId="12"] [origin=12.16.23.17] [request_id=11a3de4c-cda9-40a2-8edf-0163fabce221] [tid=1276] Started POST "/authn/demo/admin/authenticate" for 12.16.23.17 at 2020-10-06 19:20:50 +0000

    Where [origin=12.16.23.17] denotes the client IP address. General information about the application logs can be found in Conjur logs.

  • The audit logs contain the IP address in the client@43868 section of structured data. For more information, see Audit Log Structure.

Troubleshoot trusted proxies

If Conjur does not correctly identify each client's actual IP address and you are using Layer 7 load balancers, you can use the NGINX logs to troubleshoot the X-Forwarded-For header. Each request to Conjur is proxied by an NGINX process in the Conjur container.

Each log entry created by NGINX contains both the TCP origin IP address, as well as the value of the X-Forwarded-For header, if provided. Here is an example:

 
<13>1 2020-10-06T19:20:51.117+00:00 c2cbedf1dc33 nginx - - [meta sequenceId="23"] 192.0.2.1 "12.16.23.17, 192.168.2.1" "POST /authn/demo/admin/authenticate HTTP/1.1" 200 624 "-" "rest-client/2.1.0 (linux-gnu x86_64) ruby/2.5.1p57" 0.058 0.058

Using the NGINX logs, you can verify if any Layer 7 load balancers in front of Conjur are properly modifying the X-Forwarded-For header.

In this example, 192.0.2.1 is the IP address of the load balancer from which Conjur received the request, and the X-Forwarded-For header value that Conjur received is 12.16.23.17,192.168.2.1.