16.1.1.17. Machine endpoints¶

The machine REST API lists machines resolved by configured machine resolvers, attaches and detaches tokens to those machines via application plugins, and fetches the authentication items the plugins need at runtime. See Applications and Machines or Services for the conceptual chapter and Application Plugins for the available applications.

All endpoints require admin authentication. Listing is gated by the admin policy action machinelist; attaching, detaching and managing token-machine options by manage_machine_tokens; the runtime /machine/authitem endpoint by fetch_authentication_items.

GET /machine/¶

List machines from every configured machine resolver. Filters can be combined; any performs a substring match across hostname, IP and id at once.

Requires admin authentication and the policy action machinelist.

Query Parameters:

hostname – substring match against the machine’s hostnames.
ip – exact match against the machine’s IP address.
id – substring match against the machine id.
resolver – substring match against the resolver name.
any – substring match against hostname, ip or id.

Status Codes:

200 OK – list of machine dictionaries in result.value.

Example request:

GET /machine/?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"
}

POST /machine/token¶

Attach an existing token to a machine for use with a given application plugin (ssh, luks, offline, …). The machine can be identified either by hostname or by the pair (machineid, resolver). Any body fields not listed below are forwarded to the application plugin as options.

Requires admin authentication and the policy action manage_machine_tokens.

JSON Parameters:

hostname – identify the target machine by hostname.
machineid – identify the target machine by machine id (combine with resolver).
resolver – machine resolver name.
serial – token serial number (required).
application – application plugin name (required).

Jsonparam:

any other field is treated as a plugin option.

Status Codes:

200 OK – id of the new machine-token row in result.value.

Example request:

POST /machine/token HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "hostname": "puckel.example.com",
  "machineid": "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. Two URL shapes are accepted: /machine/token/<serial>/<machineid>/<resolver>/<application> identifies the binding by machine-id + resolver, /machine/token/<serial>/<application>/<mtid> by the machine-token row id directly.

Requires admin authentication and the policy action manage_machine_tokens.

Parameters:

serial – path component, the token serial.
machineid – path component, the machine id.
resolver – path component, the machine resolver name.
application – path component, the application plugin name.
mtid – path component, the machine-token row id (alternative to machineid + resolver).

Status Codes:

200 OK – number of removed bindings in result.value.

GET /machine/token¶

List machine-token bindings, either for a given machine or for a given token. Without machine identification but with serial and no extra filters, returns the machines that the given token is attached to.

Requires admin authentication and the policy action manage_machine_tokens.

Query Parameters:

serial – token serial (supports the * wildcard for substring matching).
hostname – identify the machine by hostname.
machineid – identify the machine by machine id.
resolver – machine resolver name.
application – filter by application plugin name (ssh, offline, …).
sortby – column to sort by — serial or any option key (e.g. service_id). Default serial.
sortdir – asc (default) or desc.

Query:

any other key is treated as an option filter (e.g. service_id, user for SSH; count, rounds for offline). Filter values support the * wildcard.

Status Codes:

200 OK – list of machine-token bindings in result.value.

Example response value:

[
  {
    "application": "ssh",
    "id": 1,
    "options": {"service_id": "webserver", "user": "root"},
    "resolver": null,
    "serial": "SSHKEY1",
    "type": "sshkey"
  }
]

POST /machine/tokenoption¶

Set or remove options on a machine-token binding. Body fields not listed below are treated as options: a non-empty value adds or updates the option, an empty value removes it. The binding may be addressed either by mtid or by the (machine, token, application) tuple.

Requires admin authentication and the policy action manage_machine_tokens.

JSON Parameters:

hostname – identify the machine by hostname.
machineid – identify the machine by machine id.
resolver – machine resolver name.
serial – token serial.
application – application plugin name.
mtid – machine-token row id (alternative to the tuple).

Jsonparam:

any other field — non-empty values add/update an option, empty values remove it.

Status Codes:

200 OK – {"added": <n>, "deleted": <m>} in result.value.

GET /machine/authitem/(application)¶

GET /machine/authitem¶

Fetch the authentication items the application plugin needs at runtime for the given client machine. Each plugin defines its own item shape — for example SSH returns a list of {username, sshkey} records, LUKS returns a list of {slot, challenge, response, partition} records.

Without application in the path, items for every plugin attached to the machine are returned, keyed by application name.

Requires admin authentication and the policy action fetch_authentication_items.

Parameters:

application – optional path component, the application plugin name to limit the response to.

Query Parameters:

hostname – hostname of the calling client machine (required).
challenge – challenge value for plugins that compute a challenge/response item (e.g. Yubikey). The returned item is the combination of challenge and response.

Query:

any other key is forwarded as an additional plugin filter.

Status Codes:

200 OK – dict of authentication items keyed by application in result.value.

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