Skip to main content
Version: v42

REST API Access via PrivX

You can use PrivX to control access to REST APIs, which improves security with:

  • Session-recording support for improved auditability.
  • PrivX hides the target API credentials from the end user, forcing users to access the API through PrivX. Access is provided in a role-based fashion.

High-level setup steps involve:

  1. Add your APIs as API targets into PrivX.
  2. Set up API credentials for your PrivX user account.
  3. Configure your native API client to connect to the PrivX API Proxy.

These steps are described in more detail in the following sections of this guide.

Prerequisites​

  • Your PrivX license must allow the API Access feature, see Licensable Features.
  • Your deployment must allow TCP connections to PrivX Server's port 20080. In high-availability deployments the port 20080 must be served by a network load balancer that uses IP-based session stickiness, and either operates in transparent mode or supports passing the client IP address to PrivX using the PROXY protocol.
  • The API service must allow bearer-token authentication. You will need to generate a bearer token for PrivX that allows any API operations users are expected to perform.

Configuring API Targets​

You will need to add API targets to PrivX before users can connect to them.

Set up and/or manage API targets via the PrivX GUI, on Administration→API Targets. Each API target must at least specify:

  • A unique name.
  • Roles that can access the API target.
  • Target credentials (bearer token).
  • Authorized endpoints. Use these to specify the APIs and the types of commands users are allowed to run. Each authorized endpoint must at least specify:
    • Host: The host and port where the API is located.
    • Protocols: Protocols allowed to connect to the API.
    • Methods: HTTP methods (such as GET, POST, PUT etc.) allowed for querying the API.
    • Paths: Allowed query paths. To allow access to the entire API, set to **.
    • Match unauthenticated requests: Controls if unauthenticated requests are matched to this endpoint.

You may optionally specify the following in API Targets:

  • TLS trust anchors for validating the target API TLS certificates or disable TLS certificate verification.

  • Unauthorized endpoints for blocking access to specific API endpoints.

  • NAT target host for authorized endpoints. When set, the API Proxy forwards the request to this address instead of the Host address.

    If you have API targets behind subnets that aren't directly accessible via PrivX, you will need to set up PrivX Extenders in those network segments, then set the NAT Target Host to the Extender prefix.

Creating API Proxy Credentials​

PrivX users need API credentials for accessing API targets. These can be created as follows:

  • For one's own account: Log into the PrivX GUI, then under your Account page go to Credentials and click API Proxy Credentials. Click Add API Proxy Credential.
  • For others' accounts by PrivX administrators: Select a user from Administration→Users, go to their Credentials and select API Proxy Credentials. Then click Add API Proxy Credential.

Each API proxy credential must at least specify:

  • A name.
  • An API target.
  • Validity period.

You may additionally restrict the allowed client IP addresses or subnets.

Configuring The API Client​

The client application used for making REST API requests must be configured as follows:

  • HTTP proxy address: Set to the address of API Proxy's listener port 20080.
  • TLS trust anchor: Configure as PrivX API Proxy's CA X.509 certificate.
  • Credential: Configure as the API Proxy credential secret.

End users can get the above information from PrivX GUI, in Connections→API Targets.

Monitoring API Session​

PrivX administrators can inspect ongoing and past API sessions from Monitoring→Connections. You can instantly Terminate ongoing connections. If session recording is enabled, you can view trail logs of an API connection after it's closed.

When the administrator terminates an API session or the user has lost roles that grant access to the API target, the API session is marked as terminated or unauthorized, and moved to a cool down phase. During this cool down phase all requests mapped to this API session are rejected. The length of the cool down period is set in Settings→API Proxy with Session Cool Down Margin (Seconds).

API sessions are implicitly closed when no requests have been processed within the configured idle timeout or when the API session has reached maximum lifetime. These values can be configured via Settings→API Proxy with Idle Session Timeout (Seconds) and Maximum Session Lifetime (Seconds) respectively.

Additional API Proxy Configuration​

For more advanced API Proxy configuration topics, including proxy-protocol and session settings, see API Proxy Configuration.