Application Delivery Management

NetScaler ADM as an API proxy server

March 11, 2024

Contributed by:

R C

In addition to being able to receive NITRO REST API requests for its own management and analytics functionality, NetScaler Application Delivery Management (NetScaler ADM) can function as a REST API proxy server for its managed instances. Instead of sending API requests directly to the managed instances, REST API clients can send the API requests to NetScaler ADM. NetScaler ADM can differentiate between the API requests to which it must respond and the API requests that it must forward unchanged to a managed instance.

As an API proxy server, NetScaler ADM provides you with the following benefits:

Validation of API requests. NetScaler ADM validates all API requests against configured security and role-based access control (RBAC) policies. NetScaler ADM is also tenant-aware and ensures that API activity does not cross tenant boundaries.
Centralized auditing. NetScaler ADM maintains an audit log of all API activity related to its managed instances.
Session management. NetScaler ADM frees API clients from the task of having to maintain sessions with managed instances.

How NetScaler ADM Works as an API Proxy Server

When you want NetScaler ADM to forward a request to a managed instance, you configure the API client to include any one of the following HTTP headers in the API request:

Header values	Description
_MPS_API_PROXY_MANAGED_INSTANCE_NAME	Name of the managed instance.
_MPS_API_PROXY_MANAGED_INSTANCE_IP	IP address of the managed instance.
_MPS_API_PROXY_MANAGED_INSTANCE_ID	ID of the managed instance.
_MPS_API_PROXY_TIMEOUT	Timeout value for a NITRO API request. Set the timeout value in seconds. When you set a proxy timeout, ADM waits for the specified duration before it times out the request.
_MPS_API_PROXY_MANAGED_INSTANCE_USERNAME	User name to access the managed ADC instance.
_MPS_API_PROXY_MANAGED_INSTANCE_PASSWORD	Password to access the managed ADC instance.
_MPS_API_PROXY_MANAGED_INSTANCE_SESSID	Session ID to access the managed instance.

Note

In Settings > Administration > System Configurations > Basic Settings, if you select Prompt Credentials for Instance Login, ensure to configure user name and password of a managed instance. Alternatively, you can also specify the instance session ID.

The presence of any of these HTTP headers helps NetScaler ADM identify an API request as one that it must forward to a managed instance. The value of the header helps NetScaler ADM identify the managed instance to which it must forward the request.

This flow is depicted in the following figure:

Device-API

As shown in the above figure, when one of these HTTP headers appears in a request, NetScaler ADM processes the request as follows:

Without modifying the request, NetScaler ADM forwards the request to the instance API proxy engine.
The instance API proxy engine forwards the API request to a validator and logs the details of the API request in the audit log.
The validator ensures that the request does not violate configured security policies, RBAC policies, tenancy boundaries, and so on. It performs extra checks, such as a check to determine whether the managed instance is available.

If the API request is valid and can be forwarded to the managed instance, NetScaler ADM identifies a session that is maintained by the instance Session Manager and then sends the request to the managed instance.

Note

Ensure the Prompt Credentials for Instance Login option is disabled. To do so:

Navigate to Settings > Administration.

In System Configurations, select System, Time zone, Allowed URLs and Message of the day.

How to use NetScaler ADM as an API proxy server

The following examples show REST API requests that an API client sends to a NetScaler ADM server that has an IP address of 192.0.2.5. NetScaler ADM is required to forward the requests, unchanged, to a managed instance with IP address 192.0.2.10. All examples use the _MPS_API_PROXY_MANAGED_INSTANCE_IP header.

Before sending NetScaler ADM the API requests, the API client must:

Log in to NetScaler ADM
Obtain a session ID
Include the session ID in subsequent API requests.

The logon API request is of the following form:

    POST /nitro/v1/config/login
    Content-Type: application/json

    {
        "login": {
            "username":"nsroot",
            "password":"nsroot"
         }
    }
<!--NeedCopy-->

NetScaler ADM responds to the logon request with a response that includes the session ID. The following sample response body shows a session ID:

{

  "errorcode": 0,

  "message": "Done",

  "operation": "add",

  "resourceType": "login",

  "username": "***********",

  "tenant_name": "Owner",

  "resourceName": "nsroot",

  "login": [

    {

      "tenant_name": "Owner",

      "permission": "superuser",

      "session_timeout": "36000",

      "challenge_token": "",

      "username": "",

      "login_type": "",

      "challenge": "",

      "client_ip": "",

      "client_port": "-1",

      "cert_verified": "false",

      "sessionid": "##D2BF9C5F40E5B2E884A9C45C89F0ADE24DA8A8169BE6358D39F5D471B73D",

      "token": "b2f3f935e93db6a"
    }

  ]

}
<!--NeedCopy-->