[SOLVED] How to Create an Authentication Ticket via REST API?

[utkonos]

I can see in the API documentation where the endpoint is for creating an authentication ticket:
https://pmg.proxmox.com/pmg-docs/api-viewer/index.html#/access/ticket

I don't see anything in the main documentation describing how to use the REST API.

I have provided the username and password which are correct and accepted. The response is JSON which includes a key "NeedTFA" = "1". I see that there is another key "otp" which can be included in the POST. When I set that otp value to the TOTP displayed currently, the response is a 401 authentication failure. I have also tried one of the backup codes as the value in the otp field.

What am I doing incorrectly here? And is there basic API docs to read?

 

[Stoiko Ivanov]

The PMG API is sharing quite a few bits with the PVE API - check out the wiki-page for that - should help in getting you started:
https://pve.proxmox.com/wiki/Proxmox_VE_API

I hope this helps!

 

[utkonos]

That helps. I have a way forward. The documentation doesn't answer the part of my question about how to work with the API when the user (root in this case) has two factor authentication enabled. I made a guess that putting the TOTP number in the otp field when creating the ticket is correct, but the API is rejecting the correct TOTP value.

I have a workaround, however. I created a user that is specifically for the API actions that I need to make and is an Administrator. This user does not have 2fa enabled at all. I am able to proceed with the PVE documentation and do what I need.

It seems like the API has fields and capabilities for ticket creation on a user who has two factor authentication enabled. Is there any documentation for this and how to work it?

 

[utkonos]

Actually, that documentation doesn't seem to work for PMG, but thanks for trying. I give up on this one.

 

[Stoiko Ivanov]

Actually, that documentation doesn't seem to work for PMG, but thanks for trying. I give up on this one.

Last time I tried it did work - just make sure to use PMG instead of PVE in the ticket names etc.

but fine if you drop this for now

 

[utkonos]

I tried to follow the ticket-based documentation on a PVE instance and it fails as well on the very first step following the documentation letter for letter.

curl -k -d 'username=root@pam' --data-urlencode 'password=hiddenhidden' https://example.com:8006/api2/json/access/ticket

Response:

HTTP/1.1 401 authentication failure
Cache-Control: max-age=0
Connection: close
Date: Fri, 23 Dec 2022 14:25:56 GMT
Pragma: no-cache
Server: pve-api-daemon/3.0
Content-Length: 13
Content-Type: application/json;charset=UTF-8
Expires: Fri, 23 Dec 2022 14:25:56 GMT

{"data":null}

 

[utkonos]

OK. PVE and PMG behave differently if root has 2fa enabled. PMG responds with a cryptic "NeedTFA" and a garbage ticket. PVE responds with 401 authentication failure.

There doesn't appear to be any clear documentation in PVE or PMG how to work with 2FA enabled.

 

[utkonos]

I've got it, but this is a state that I would not leave the gateway in. I am going to have to disable this account after I have done what I need in the API.

Create a new account for use with the API:

Configuration > User Management > Local > Add:
User name: apiuser
Password: {password}
Confirm password: {password}
Role: Administrator
> Add

Of course, the role and permissions can be adjusted as required. The above is just an example.

Now make a POST to the API to generate a ticket:

POST /api2/json/access/ticket HTTP/1.1
Content-Type: application/json; charset=utf-8
Host: example.com:8006
Connection: close
Content-Length: 49

{"username":"apiuser@pmg","password":"testtest"}

In the JSON response, the ticket is at JSON path data.ticket and the CSRF prevention token needed for PUT POST DELETE operations is located at JSON path data.CSRFPreventionToken.

Using the ticket, make a test GET call:

GET /api2/json/ HTTP/1.1
Cookie: PMGAuthCookie=PMG:apiuser@pmg:00000000::MDAwMDAwMDAwMA==
Host: example.com:8006
Connection: close

The zeros and base64 encoded zeros in the above will be different in a real ticket.

 

[utkonos]

It would be nice to understand how the API works with regards to an account that has 2FA enabled, but since it is not documented, I am assuming that it is for internal use and not a supported feature.

 

[Nillth]

To interact with the API with a TOTP, you'll need to make two requests:

1. First API Call:
   • Endpoint: POST /api2/json/access/ticket
   • Request Body: username=root@pam&password=hiddenhidden
   • Response: Look for data.ticket in the response. This value will be used in the second request as the tfa-challenge.
2. Second API Call:
   • Endpoint: POST /api2/json/access/ticket
   • Request Body: username=root@pam&tfa-challenge=<ticket_from_first_response>&password=totp:<totpcode>
   • Replace <ticket_from_first_response> with the data.ticket from the first response.
   • Replace <totpcode> with your TOTP code.

These steps authenticate with the API using a two-factor totp authentication challenge.