VMware vCenter | Error: 'authentication required'

Overview 💥

This article addresses an issue where the VMware vCenter Inspector fails in Liongard with an authentication-related error returned by the VMware vSphere Automation REST API.

The error appears when Liongard attempts to authenticate to the vCenter appliance API but receives a response indicating missing, invalid, or rejected credentials. This problem can be caused by incorrect login details, domain formatting, permission issues, SSL certificate mismatches, or API access restrictions on the vCenter appliance.

Why Does This Happen? 🤔

When Liongard connects to VMware vCenter, it uses the vSphere Automation REST API. The API requires a valid session created through Basic Authentication. If authentication fails at this stage, vCenter returns an unauthenticated error similar to:

{"type":"com.vmware.vapi.std.errors.unauthenticated","value":{"messages":[
{"args":[],"default_message":"This method requires authentication.","id":"vapi.method.authentication.required"}]}}

Common reasons this occurs include:

1️⃣ Incorrect Credentials

Wrong username or password.
Username missing required domain prefix
(e.g., using Administrator instead of domain.local\Administrator).
Password expired or recently changed.

2️⃣ Account Issues

Account is locked out.
Account lacks permissions to access the vSphere API.
The user does not have sufficient role privileges for API calls.

3️⃣ Connectivity or Certificate Issues

HTTPS/SSL certificate warnings causing REST API rejection.
Self-signed certificates that require disabling SSL verification during testing.

4️⃣ vCenter API Access Problems

vCenter service is unreachable on port 443.
REST API endpoint /rest/com/vmware/cis/session is not responding.

Testing the connection with Postman helps isolate whether the issue is with credentials, API availability, or permissions.

Steps to Resolve 👨‍💻

✅ Step 1: Test API Authentication Using Postman

We use Postman to validate:

API connectivity
Credentials
Session creation
Permission validity

Download Postman

‼️ Note: In environments using self-signed certificates (common in on-prem vCenter), you may need to disable SSL certificate verification under:
Settings → General → Disable SSL Certificate Verification.
This is recommended only for troubleshooting, not production.

✅ Step 2: Import the Provided Troubleshooting Collection

In Postman:

Go to File → Import
Choose Raw Text
Paste the full collection JSON exactly as provided:

{ "info": { "_postman_id": "8d3d91af-3793-4b70-a99f-d4829bdd9cb9", "name": "Liongard VMware vSphere Inspector Troubleshooting", "description": "This collection includes two requests that may be used to troubleshoot connectivity issues with the vSphere Automation REST API:\n\ncis session: create\nPOST https://{server}/rest/com/vmware/cis/session\n\ndescription: Creates a session with the API. This is the equivalent of login. This operation exchanges user credentials supplied in the security context for a session identifier that is to be used for authenticating subsequent calls. To authenticate subsequent calls clients are expected to include the session key.\n\nand\n\nappliance system version: get\nGET https://{server}/rest/appliance/system/version\n\ndescription: Returns the vSphere appliance version\n\nThe following environment variables must be set under the 'Variables' tab:\nhostname - The IP address of vSphere\nuser - The vCenter login username. This often is in the from: \"domain.local\\Administrator\"\npassword", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"" }, "item": [ { "name": "Login", "request": { "method": "POST", "header": [], "url": { "raw": "https://{{hostname}}/rest/com/vmware/cis/session", "protocol": "https", "host": [ "{{hostname}}" ], "path": [ "rest", "com", "vmware", "cis", "session" ] } }, "response": [] }, { "name": "Version", "request": { "method": "GET", "header": [], "url": { "raw": "https://{{hostname}}/rest/appliance/system/version", "protocol": "https", "host": [ "{{hostname}}" ], "path": [ "rest", "appliance", "system", "version" ] } }, "response": [] } ], "auth": { "type": "basic", "basic": [ { "key": "password", "value": "{{password}}", "type": "string" }, { "key": "username", "value": "{{user}}", "type": "string" } ] }, "event": [ { "listen": "prerequest", "script": { "id": "ad85a990-6378-4a57-984f-48329c09ad26", "type": "text/javascript", "exec": [ "" ] } }, { "listen": "test", "script": { "id": "7ebc4f2c-20f7-40d4-8e2d-f0e144417c3b", "type": "text/javascript", "exec": [ "" ] } } ], "variable": [ { "id": "92c51318-91cd-4bce-a0d5-ef7916f494a1", "key": "hostname", "value": "", "type": "string" }, { "id": "c9a3c47e-4622-4843-9dfa-d885f121a153", "key": "user", "value": "", "type": "string" }, { "id": "bd4b1545-7230-432d-94a0-ee5fb6fc6e39", "key": "password", "value": "", "type": "string" } ], "protocolProfileBehavior": {} }

This collection tests the two most important REST endpoints:

Request	Endpoint	Purpose
Login	`POST https://{server}/rest/com/vmware/cis/session`	Creates an authenticated session; validates credentials
Version	`GET https://{server}/rest/appliance/system/version`	Confirms API access and connectivity

✅ Step 3: Set Required Variables

Under the Variables tab in the collection:

Variable	Description
hostname	IP or FQDN of vCenter (e.g., `10.0.0.5` or `vcenter.domain.local`)
user	Username including domain (e.g., `domain.local\Administrator`)
password	Account password

‼️ Important:
Missing the domain prefix is one of the primary causes of authentication failures.

Step 4: Send the Requests

Run Login (POST)
- Should return 200 OK with a session ID.
Run Version (GET)
- Should also return 200 OK with appliance version info.

If both succeed, authentication and vCenter API access are working properly and the Liongard inspection should succeed unless another issue exists.

Common Causes of Authentication Failure 🧑‍🏫

1. Incorrect Username Format

Must include domain.
Example:
❌ Administrator
✔️ corp.local\Administrator

2. Invalid Password

Recently changed passwords not updated in Liongard.
Typographical errors.
Password fails complexity enforcement.

3. Account Permission Issues

The account must have adequate vSphere permissions, such as:

Administrator
Or a custom role with API access

4. Account Disabled / Locked Out

Verify via vCenter or domain controller.

5. SSL / Certificate Problems

Self-signed certs may cause API calls to fail.
In testing, disable SSL verification in Postman.

6. API Service Problems

vCenter services may be down.

Restart services if required:

service-control --status service-control --restart vpxd

When to Contact Liongard Support 🦁

Open a support ticket with Liongard if any of these are true:

API works in Postman but fails in Liongard.
You receive unexpected or inconsistent session results.
The inspector succeeds intermittently.

Include the following in the ticket:

Screenshot of Postman results (Login + Version).
vCenter version (API output will show this).
Username format used.
Any certificate-related warnings in Liongard logs.
Any security tools that might block API access (EDR, firewall, IDS).

References 🤩

Third-party links disclaimer 🚨

We sometimes link to external sites and vendor documentation for convenience. These resources are provided as-is. Liongard does not control, endorse, or guarantee the content, availability, or behaviour of third-party websites. Use third-party tools and documentation at your own discretion.