Product Documentation

NetScaler MAS as an API Proxy Server

Nov 08, 2016

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

  • Validation of API requests. NetScaler MAS validates all API requests against configured security and role-based access control (RBAC) policies. NetScaler MAS is also tenant-aware and ensures that API activity does not cross tenant boundaries.

  • Centralized auditing. NetScaler MAS maintains an audit log of all API activity related to its managed instances.

  • Session management. NetScaler MAS frees API clients from the task of having to maintain sessions with managed instances.

How NetScaler MAS Works as an API Proxy Server

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

  1. Without modifying the request, NetScaler MAS 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, NetScaler MAS identifies a session that is maintained by the instance session manager and then sends the request to the managed instance.

How to Use NetScaler MAS as an API Proxy Server

The following examples show REST API requests that an API client sends to a NetScaler MAS server that has an IP address of 192.0.2.5. NetScaler MAS 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 MAS the API requests, the API client must log in to NetScaler MAS, obtain a session ID, and include the session ID in subsequent API requests. The logon API request is of the following form:

API Request to Log On Copy

POST /nitro/v1/config/login HTTP/1.1

Host: 192.0.2.5

Cache-Control: no-cache

object=

{

"login":

    {

        "username":"nsroot",

        "password":"nsroot"

     }

}

NetScaler MAS 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 NetScaler MAS an API request of the following form:

Retrieve Load Balancing Virtual Server Statistics Copy

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 NetScaler MAS an API request of the following form:

Create Load Balancing Virtual Server Copy

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 NetScaler MAS an API request of the following form:

Modify a Load Balancing Virtual Server Copy

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 NetScaler MAS an API request of the following form:

Delete a Load Balancing Virtual Server Copy

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