Application Delivery Management

Citrix ADM as an API proxy server

December 31, 2023

Contributed by:

In addition to being able to receive NITRO REST API requests for its own management and analytics functionality, Citrix Application Delivery Management (Citrix 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 Citrix ADM. Citrix 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, Citrix ADM provides you with the following benefits:

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

How Citrix ADM Works as an API Proxy Server

When you want Citrix 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 System > 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 Citrix ADM identify an API request as one that it must forward to a managed instance. The value of the header helps Citrix 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, Citrix ADM processes the request as follows:

Without modifying the request, Citrix 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, Citrix 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 System > Administration.

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

How to use Citrix ADM as an API proxy server

The following examples show REST API requests that an API client sends to a Citrix ADM server that has an IP address of 192.0.2.5. Citrix 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 Citrix ADM the API requests, the API client must:

Log in to Citrix 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-->

Citrix 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-->