Citrix ADM as an API proxy server

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:

  • _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.

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:

localized image

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

  1. Without modifying the request, Citrix ADM forwards the request to the instance API proxy engine.

  2. The instance API proxy engine forwards the API request to a validator and logs the details of the API request in the audit log.

  3. The validator ensures that the request does not violate configured security policies, RBAC policies, tenancy boundaries, and so on. It performs additional 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.

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, and include the session ID in subsequent API requests. The logon API request is of the following form:

    POST /nitro/v1/config/login HTTP/1.1
    Host: 192.0.2.5
    Cache-Control: no-cache
    object=
    {
    "login":
        {
            "username":"nsroot",
            "password":"nsroot"
         }
    }

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"

    }

  \]

}

Example 1: Retrieve Load Balancing Virtual Server Statistics

The client must send Citrix ADM an API request of the following form:

    GET /nitro/v1/stat/lbvserver HTTP/1.1
    Host: 192.0.2.5
    _MPS_API_PROXY_MANAGED_INSTANCE_IP: 192.0.2.10
    SESSID: ##D2BF9C5F40E5B2E884A9C45C89F0ADE24DA8A8169BE6358D39F5D471B73D
    Content-type: application/json
    Cache-Control: no-cache

Example 2: Create a Load Balancing Virtual Server

The client must send Citrix ADM an API request of the following form:


    POST /nitro/v1/config/lbvserver/sample_lbvserver HTTP/1.1
    Host: 192.0.2.5
    _MPS_API_PROXY_MANAGED_INSTANCE_IP: 192.0.2.10
    SESSID: ##D2BF9C5F40E5B2E884A9C45C89F0ADE24DA8A8169BE6358D39F5D471B73D
    Content-type: application/vnd.com.citrix.netscaler.lbvserver+json
    Accept-type: application/vnd.com.citrix.netscaler.lbvserver+json
    Cache-Control: no-cache
    {"lbvserver":{"name":"sample_lbvserver","servicetype":"HTTP","ipv46":"10.102.1.11","port":"80"}}

Example 3: Modify a Load Balancing Virtual Server

The client must send Citrix ADM an API request of the following form:

    PUT /nitro/v1/config/lbvserver HTTP/1.1
    Host: 192.0.2.5
    SESSID: ##D2BF9C5F40E5B2E884A9C45C89F0ADE24DA8A8169BE6358D39F5D471B73D
    _MPS_API_PROXY_MANAGED_INSTANCE_IP: 192.0.2.10
    Content-type: application/vnd.com.citrix.netscaler.lbvserver+json
    Accept-type: application/vnd.com.citrix.netscaler.lbvserver+json
    Cache-Control: no-cache
    {"lbvserver":{"name":"sample_lbvserver","appflowlog":"DISABLED"}}

Example 4: Delete a Load Balancing Virtual Server

The client must send Citrix ADM an API request of the following form:

    DELETE /nitro/v1/config/lbvserver/sample_lbvserver HTTP/1.1
    Host: 192.0.2.5
    SESSID: ##D2BF9C5F40E5B2E884A9C45C89F0ADE24DA8A8169BE6358D39F5D471B73D
    _MPS_API_PROXY_MANAGED_INSTANCE_IP: 192.0.2.10
    Cache-Control: no-cache

Citrix ADM as an API proxy server