NSX API Authentication Using a Session Cookie

This topic describes how to use NSX session-based authentication to generate a JSESSIONID cookie when using the API. Use this method to reduce the number of times you have to enter your username and password. You can use this type of authentication with vIDM and LDAP authentication.

NSX uses several different mechanisms to authenticate NSX users. They include:

HTTP authentication
Session-based authentication
Principal identity or certificate-based authentication
Single sign on using vIDM and RBAC

The NSX uses a username and password to generate a session cookie during session creation. Once the session cookie has been created, subsequent API requests can use this session cookie instead of the user name and password credentials. This means that the session state is local to the server on which it is performed. When clients make requests to the NSX Manager, it only allows clients to authenticate if the session ID they present matches one of the IDs generated by the server. When any user logs out of NSX Manager, the session identifier is immediately eliminated and cannot be reused. Idle sessions time out automatically or you can delete them using the API.

Access using the API request generates audit log details. This logging is always enabled and cannot be disabled. Auditing of sessions is initiated at system startup. Audit log messages include the text audit="true" in the structured data part of the log message.

This example describes using cURL to create session-based authentication for API calls.

Procedure

To create a new session cookie that authenticates to the NSX Manager and retrieves xsrf from header enter:
```
# curl -i -k -c session.txt -X POST -d '[email protected]&j_password=SecretPwsd3c4d' https://<nsx-manager>/api/session/create 2>&1 > response.txt
```
In this example, the cURL command authenticates to the server, places the session cookie in the sessions.txt file and writes headers and response into response.txt file. You will need to use one of the headers from session.txt, the x-xsrf-token header, to provide in subsequent requests.

You can also use the standard unicode/URI encoding for the @ in the username.

An example of the session contents follows:
```
# cat session.txt
      # Netscape HTTP Cookie File
      # https://curl.haxx.se/docs/http-cookies.html
      # This file was generated by libcurl! Edit at your own
        risk.
      # HttpOnly_172.182.183.135 FALSE / TRUE 0 JSESSIONID CFG588DF6DGF493C0EAEFC62685C42E1
```

If you need to create two sessions, change the name of the session.txt files so that both sessions are valid.

curl -i -k -c session.txt -X POST -d '[email protected]&j_password=SecretPwsd3c4d' https://<nsx-manager>/api/session/create 2>&1 > response.txt
# curl -i -k -c session2.txt -X POST -d 'j_username= [email protected]&j_password=SecretPwsd3c4d' https://<nsx-manager>/api/session/create 2>&1 > response2.txt

For subsequent calls, use the session cookie and xsrf header from the previous step. Note the response.txt corresponds with the file in the previous steps.

# curl -k -b session.txt -H "x-xsrf-token: `grep -i xsrf response.txt | awk '{print $2}'`" https://<nsx-manager>/policy/api/v1/infra/segments

      {
        "results" : [ {
          "type" : "ROUTED",
          "subnets" : [ {
            "gateway_address" : "192.168.10.1/24",
            "network" : "192.168.10.0/24"
          } ],
          "connectivity_path" :
        "/infra/tier-1s/test_t1",
          "transport_zone_path" :
        "/infra/sites/default/enforcement-points/default/transport-zones/1b3a2f36-bfd1-443e-a0f6-4de01abc963e",
          "advanced_config" : {
            "address_pool_paths" : [ ],
            "hybrid" : false,
            "multicast" : true,
            "inter_router" : false,
            "local_egress" : false,
            "urpf_mode" : "STRICT",
            "connectivity" : "ON"
          },
          "admin_state" : "UP",
          "replication_mode" : "MTEP",
          "resource_type" : "Segment",
          "id" : "seg1",
          "display_name" : "seg1",
          "path" : "/infra/segments/seg1",
          "relative_path" : "seg1",
          "parent_path" : "/infra",
          "unique_id" :
        "6573d2c9-f4f9-4b37-b410-71bded8857c3",
          "marked_for_delete" : false,
          "overridden" : false,
          "_create_user" : "admin",
          "_create_time" : 1633331197569,
          "_last_modified_user" : "admin",
          "_last_modified_time" : 1633331252660,
          "_system_owned" : false,
          "_protection" : "NOT_PROTECTED",
          "_revision" : 1
        } ],
        "result_count" : 1,
        "sort_by" : "display_name",
        "sort_ascending" : true

If you use the same session with another node in the cluster, the command fails with the error message:

The credentials were incorrect or the account specified has been locked.","error_code":403.

When the session expires, NSX Manager responds with a 403 Forbidden HTTP response. You must then obtain a new session cookie and x-xsrf-token.

To configure the session expiry setting, use the connection_timeout API command. The default session expiry is set to 1800 seconds (30 minutes).

GET https://<nsx-mgr>/api/v1/cluster/api-service

{
    "session_timeout": 1800,
    "connection_timeout": 30,
    "protocol_versions": [
        {
            "name": "TLSv1.1",
            "enabled": true
        },
        {
            "name": "TLSv1.2",
            "enabled": true
        }
    ],
    "cipher_suites": [
        {
            "name": "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA",
            "enabled": true
        },
        {
            "name": "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256",
            "enabled": true
        },
        {
            "name": "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
            "enabled": true
        },
        {
            "name": "TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA",
            "enabled": true
        },
        {
            "name": "TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384",
            "enabled": true
        },
        {
            "name": "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
            "enabled": true
        },
        {
            "name": "TLS_RSA_WITH_AES_128_CBC_SHA",
            "enabled": true
        },
        {
            "name": "TLS_RSA_WITH_AES_128_CBC_SHA256",
            "enabled": true
        },
        {
            "name": "TLS_RSA_WITH_AES_128_GCM_SHA256",
            "enabled": true
        },
        {
            "name": "TLS_RSA_WITH_AES_256_CBC_SHA",
            "enabled": true
        },
        {
            "name": "TLS_RSA_WITH_AES_256_CBC_SHA256",
            "enabled": true
        },
        {
            "name": "TLS_RSA_WITH_AES_256_GCM_SHA384",
            "enabled": true
        }
    ],
    "redirect_host": "",
    "client_api_rate_limit": 100,
    "global_api_concurrency_limit": 199,
    "client_api_concurrency_limit": 40,
    "basic_authentication_enabled": true,
    "cookie_based_authentication_enabled": true,
    "resource_type": "ApiServiceConfig",
    "id": "reverse_proxy_config",
    "display_name": "reverse_proxy_config",
    "_create_time": 1658339081246,
    "_create_user": "system",
    "_last_modified_time": 1658339081246,
    "_last_modified_user": "system",
    "_system_owned": false,
    "_protection": "NOT_PROTECTED",
    "_revision": 0
}

To delete a session cookie, use the /api/session/destroy API command.

curl -k -b session.txt -H "x-xsrf-token: `grep -i xsrf response.txt | awk '{print $2}'`" https://<nsx-manager>/api/v1/node/version

For example:

curl -k -b session.txt -H "x-xsrf-token: `grep -i xsrf response.txt | awk '{print $2}'`" https://<nsx-manager>/api/v1/node/version

{
    "module_name" : "common-services",
    "error_message" : "The credentials were incorrect or the account specified has been locked.",
    "error_code" : "403"
}

What to do next

To review the requirements to authenticate users with your session-based supported authentication service, see Integration with VMware Identity Manager/Workspace ONE Access or Integration with LDAP..