14.1.1.15. Machine endpoints¶

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

The code is tested in tests/test_api_machines

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

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

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’},

… ]

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": "eduMFA unknown"
 }