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 Cloud Service Platform (CSP)

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 might optionally use this session cookie instead of the user name and password credentials. This means that the session state is specific to the particular NSX Manager that generated the session cookie. When clients make requests to the NSX Manager, it only allows clients to authenticate if the session cookie they present matches one of the cookies generated by the manager. When any user logs out of NSX Manager, the session cookie is immediately eliminated from the reverse-proxy of the NSX Manager 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

  1. 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 manager, places the session cookie in the sessions.txt file and writes all HTTP response headers to the headers.txt file. You will need to use one of the headers from headers.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
  2. 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
  3. For subsequent calls, use the session cookie and xsrf header from the previous step. 
    # curl -k -b session.txt -H "x-xsrf-token: 5a764b19-5ad2-4727-974d-510acbc171c8"
      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 cookie 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.

  4. To configure the session expiry setting, use the connection_timeout API command. The default session expiry is 1800 seconds (30 minutes).
    1. Use GET https://<nsx-mgr>/api/v1/cluster/api-service to view a snapshot of the current configuration.. 
      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
        }        ,
        {
            "name": "TLS_ECDSA_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
}
    2. Edit the JSON with the desired values and remove all the underscore fields (_xxxxx), except for _revision. 
       GET https://<nsx-mgr>/api/v1/cluster/api-service
{
    "global_api_concurrency_limit": 199,
    "client_api_rate_limit": 100,
    "client_api_concurrency_limit": 40,
    "connection_timeout": 30,
    "redirect_host": "",
    "cipher_suites": [     
      {"enabled": true, "name": "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"},
      {"enabled": true, "name": "TLS_RSA_WITH_AES_256_GCM_SHA384"},
      {"enabled": true, "name": "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"},
      {"enabled": true, "name": "TLS_RSA_WITH_AES_128_GCM_SHA256"}
      {"enabled": true, "name": "TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384}",
      {"enabled": true, "name": "TLS_RSA_WITH_AES_256_CBC_SHA256"},
      {"enabled": true, "name": "TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA"},
      {"enabled": true, "name": "TLS_RSA_WITH_AES_256_CBC_SHA"},
      {"enabled": true, "name": "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256"},
      {"enabled": true, "name": "TLS_RSA_WITH_AES_128_CBC_SHA256"},
      {"enabled": false, "name": "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA"},
      {"enabled": true, "name": "TLS_RSA_WITH_AES_128_CBC_SHA"},
  
      {"enabled": true, "name": "TLS_ECDSA_WITH_AES_256_GCM_SHA384"},
    ],
      "protocol_versions": [
        {"enabled": true, "name": "TLSv1.1"},
    {"enabled": true, "name": "TLSv1.2"}
  ]    
    "_revision": 0
}
    3. Use PUT https://<nsx-mgr>/api/v1/cluster/api-service to modify the current configuration.
  5. 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
    Response: 
    {
    "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.