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