16.1.1.16. Machine endpoints¶
This REST API is used to list machines from Machine Resolvers.
The code is tested in tests/test_api_machines
- POST /machine/tokenoption¶
This sets a Machine Token option or deletes it, if the value is empty.
- Parameters
hostname – identify the machine by the hostname
machineid – identify the machine by the machine ID and the resolver name
resolver – identify the machine by the machine ID and the resolver name
serial – identify the token by the serial number
application – the name of the application like “luks” or “ssh”.
mtid – the ID of the machinetoken definition
Parameters not listed will be treated as additional options.
- Return
- GET /machine/authitem/(application)¶
- GET /machine/authitem¶
This fetches the authentication items for a given application and the given client machine.
- Parameters
challenge (basestring) – A challenge for which the authentication item is calculated. In case of the Yubikey this can be a challenge that produces a response. The authentication item is the combination of the challenge and the response.
hostname (basestring) – The hostname of the machine
- Return
dictionary with lists of authentication items
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "id": 1, "jsonrpc": "2.0", "result": { "status": true, "value": { "ssh": [ { "username": "....", "sshkey": "...." } ], "luks": [ { "slot": ".....", "challenge": "...", "response": "...", "partition": "..." ] } }, "version": "privacyIDEA unknown" }
- POST /machine/token¶
Attach an existing token to a machine with a certain application.
- Parameters
hostname – identify the machine by the hostname
machineid – identify the machine by the machine ID and the resolver name
resolver – identify the machine by the machine ID and the resolver name
serial – identify the token by the serial number
application – the name of the application like “luks” or “ssh”.
Parameters not listed will be treated as additional options.
- Return
json result with “result”: true and the machine list in “value”.
Example request:
POST /token HTTP/1.1 Host: example.com Accept: application/json { "hostname": "puckel.example.com", "machienid": "12313098", "resolver": "machineresolver1", "serial": "tok123", "application": "luks" }
- GET /machine/token¶
Return a list of MachineTokens either for a given machine or for a given token.
- Parameters
serial – Return the MachineTokens for a the given Token
hostname – Identify the machine by the hostname
machineid – Identify the machine by the machine ID and the resolver name
resolver – Identify the machine by the machine ID and the resolver name
<options> – You can also filter for options like the ‘service_id’ or ‘user’ for SSH applications, or ‘count’ and ‘rounds’ for offline applications. The filter allows the use of “*” to match substrings.
- Query Parameters
sortby – sort the output by column. Can be ‘serial’, ‘service_id’…
sortdir – asc/desc
application – The type of application like “ssh” or “offline”.
- Return
JSON list of dicts
- [{‘application’: ‘ssh’,
‘id’: 1, ‘options’: {‘service_id’: ‘webserver’,
‘user’: ‘root’},
‘resolver’: None, ‘serial’: ‘SSHKEY1’, ‘type’: ‘sshkey’},
… ]
- GET /machine/¶
List all machines that can be found in the machine resolvers.
- Parameters
hostname – only show machines, that match this hostname as substring
ip – only show machines, that exactly match this IP address
id – filter for substring matching ids
resolver – filter for substring matching resolvers
any – filter for a substring either matching in “hostname”, “ip” or “id”
- Return
json result with “result”: true and the machine list in “value”.
Example request:
GET /hostname?hostname=on HTTP/1.1 Host: example.com Accept: application/json
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "id": 1, "jsonrpc": "2.0", "result": { "status": true, "value": [ { "id": "908asljdas90ad0", "hostname": [ "flavon.example.com", "test.example.com" ], "ip": "1.2.3.4", "resolver_name": "machineresolver1" }, { "id": "1908209x48x2183", "hostname": [ "london.example.com" ], "ip": "2.4.5.6", "resolver_name": "machineresolver1" } ] }, "version": "privacyIDEA unknown" }
- DELETE /machine/token/(serial)/(machineid)/(resolver)/(application)¶
- DELETE /machine/token/(serial)/(application)/(mtid)¶
Detach a token from a machine with a certain application.
- Parameters
machineid – identify the machine by the machine ID and the resolver name
resolver – identify the machine by the machine ID and the resolver name
serial – identify the token by the serial number
application – the name of the application like “luks” or “ssh”.
mtid – the ID of the machinetoken definition
- Return
json result with “result”: true and the machine list in “value”.
Example request:
DELETE /token HTTP/1.1 Host: example.com Accept: application/json { "hostname": "puckel.example.com", "resolver": "machineresolver1", "application": "luks" }