This REST API is used to list machines from Machine Resolvers.

The code is tested in tests/test_api_machines

16.1.1.13. Machine endpoints

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”.

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
Return:
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)

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”.
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" }