HTTP Authentication using APIs on NSX

Products

• VMware NSX

Issue/Introduction

The NSX REST API supports several authentication schemes to secure management plane interactions. While the web interface handles credentials automatically, API consumers must manually implement authentication headers or session management. This article provides the precise technical requirements for HTTP Basic and Session-Based authentication.

Resolution

HTTP Based Authentication

HTTP Basic Authentication sends credentials in the Authorization header as a Base64-encoded string in the format:

Authorization: Basic <base64(username:password)>

cURL Example

curl -k -u admin:password https://<NSX_MANAGER>/api/v1/logical-ports

Here, the -k flag tells cURL to skip verification of the server’s self-signed SSL certificate.

Recommended Secure Usage

For better security, verify the server certificate using a trusted Certificate Authority (CA):

curl --cacert /home/me/certs/rootca.crt -u admin:password https://MANAGER/api/v1/logical-ports

Supported Usernames

Local user: admin

Remote user: user@domain (the domain must match a configured VIDM or LDAP identity source)

 

Session-Based Authentication

Session-based authentication uses a login API to create a session and returns a session cookie. This cookie, along with an X-XSRF-TOKEN header, must be included in subsequent API requests.

1. Create a Session

Send credentials as form data (application/x-www-form-urlencoded) to /api/session/create:

curl -k -c cookies.txt -D headers.txt -X POST -d 'j_username=USERNAME&j_password=PASSWORD' https://MANAGER/api/session/create

Session cookies are saved to cookies.txt

Response headers (including X-XSRF-TOKEN) are saved to headers.txt

2. Use the Session

Include the cookie and XSRF token in subsequent requests:

curl -k -b cookies.txt -H "grep -i X-XSRF-TOKEN headers.txt | tr -d '\r\n'" https://MANAGER/api/v1/logical-ports

Session behaviour

• Sessions are server-local
• Idle sessions expire automatically
• Expired sessions return 403 Forbidden, requiring re-authentication
  
  
  

3. Destroy a Session

To explicitly end a session:

curl -k -b cookies.txt -H "`grep -i X-XSRF-TOKEN headers.txt | tr -d '\r\n'`" -X POST https://MANAGER/api/session/destroy

Using POSTMAN to run the API calls


For Basic Authentication

Run the desired API call, with the Authorization as Basic Auth, where you can add the username and password.

 

For SESSION based Authentication 

1. Create a SESSION :

•  Run the POST API call for creating the session.
•  In the Body section, select the x-www-form-urlencoded and add the key value pairs of j_username=USERNAME and j_password=PASSWORD.
•  You should be able to see a 200 OK status, with a Cookie and Header files generated.
•  Under the Header, x-xsrf-token value should be seen.
  
  
  
  

2. USE the SESSION :

• Run the API call as desired. For example, https://MANAGER/api/v1/logical-ports
• Under the Headers section add a key-value pair of x-xsrf-token and the value copied from steps mentioned above.
• Keeping the cookies.txt intact, run the desired API call. You shall be able to see the output, with status 200 OK.

3. Destroy SESSION :

• Run the POST API call https://MANAGER/api/session/destroy
  
  
•