From 2c12e1492f7b4c0ec3ae8388d5d0b39b6297c9c0 Mon Sep 17 00:00:00 2001 From: Samir Chahine Date: Thu, 5 Sep 2019 17:00:43 +1000 Subject: [PATCH] GUACAMOLE-872: Guacamole Rest API Documentation --- src/chapters/guacamole-rest-api.xml | 836 ++++++++++++++++++++++++++++ src/gug.xml | 1 + 2 files changed, 837 insertions(+) create mode 100644 src/chapters/guacamole-rest-api.xml diff --git a/src/chapters/guacamole-rest-api.xml b/src/chapters/guacamole-rest-api.xml new file mode 100644 index 00000000..3c344d69 --- /dev/null +++ b/src/chapters/guacamole-rest-api.xml @@ -0,0 +1,836 @@ + + + Guacamole REST API + + API + JavaScript + + + guacamole-rest-api + + + There are many ways to communicate with the Guacamole protocol, but it is + also beneficial to understand how the API works. This allows you to have the + flexibility of incorporate Guacamole within your application + without having to worry about which language to use or what packages + to download. + + + +
+ Base URL + There are four things you will need to set the base url before + you can start talking to the endpoints. + + + + Method + + Protocol your Guacamole instance is using e.g. http, https + + + + Hostname + + Where your Guacamole is hosted e.g. guacamole.example.com + + + + URL Path + + The pathway to your Guacamole (where you can see the login page) e.g /guacamole + + + + Data Source + + Database your Guacamole is running on e.g. mysql, postgresql + + + + + When you have the data listed above you can set your base url which will look + like the url below and you can start talking to the API. + + + http:// guacamole.example.com /guacamole /api/data/ mysql + + +
+ +
+ Authentication + You will need to request an authentication token before being able to + call any endpoint. + + You can request your tokens from the endpoint below: + /api/tokens + + + Include your username and password in the form/body of the request. + +{ + "username": "adminuser", + "password": "adminpassword" +} + + + You will recieve the following authentication object: + + +{ + authToken: {token}, + username: 'adminuser', + dataSource: 'mysql', + availableDataSources: [ 'mysql', 'mysql-shared' ] +} + + + You can now use this token token query any endpoint by appending it to the url: + + + +api/session/data/mysql/activeConnections?token={token} + + + + + Make sure you keep your authentication details safe and unexposed. + + +
+ +
+ Connections + The following endpoints can be used to retrieved data regarding connections + in your Guacamole instance. + +
+ Return all active connections. + + Returning Active Connections + + GET : api/session/data/{data_source}/activeConnections + + + + Returns + + +{ + "644227fd-6d7f-2b5d-8b37-224323d1ea58": { + "identifier": "644227fd-6d7f-2b5d-8b37-224323d1ea58", + "connectionIdentifier": "14", + "startDate": 1560240188568, + "remoteHost": "10.126.251.39", + "username": "adminuser" + } +} + + + +
+
+ Return all child connections and connection groups. + + All Connections and Connection Groups + + GET : api/session/data/{data_source}/connectionGroups/ROOT/tree + + + + Returns + + +{ + "name": "ROOT", + "identifier": "ROOT", + "type": "ORGANIZATIONAL", + "activeConnections": 0, + "childConnectionGroups": [ + { + "name": "example_group_name", + "identifier": "1", + "parentIdentifier": "ROOT", + "type": "ORGANIZATIONAL", + "activeConnections": 0, + "attributes": { + "max-connections": null, + "max-connections-per-user": null, + "enable-session-affinity": "" + }, + ... + ], + "childConnections": [ + ... + ], + "attributes": {} +} + + + +
+
+ Returns connection groups. + + Returning All Connection Groups + + POST : api/session/data/{data_source}/connectionGroups + + + + Returns + + +{ + "1": { + "name": {name}, + "identifier": "1", + "parentIdentifier": "ROOT", + "type": "ORGANIZATIONAL", + "activeConnections": 0, + "attributes": { + "max-connections": null, + "max-connections-per-user": null, + "enable-session-affinity": "" + } + }, + ... +} + + + +
+
+ Delete a connection group. + + Deleting a Connection Group + + DELETE : api/session/data/{data_source}/connectionGroups/{identifier} + + + + Returns + + None + + +
+
+ Editing a connection group. + + Editing a Connection Group + + + PUT : api/session/data/{data_source}/connectionGroups/{identifier} + {identifier} is the identifier property retrieved from one of the above API calls. + + + + Example Payload + + +{ + "parentIdentifier":"ROOT", + "name":"New Connection Name", + "type":"ORGANIZATIONAL", + "attributes": { + "max-connections":"", + "max-connections-per-user":"" + } +} + + + + Returns + + +{ + "name": "New Connection Name", + "identifier": "3", + "parentIdentifier": "ROOT", + "type": "ORGANIZATIONAL", + "activeConnections": 0, + "attributes": { + "max-connections": null, + "max-connections-per-user": null, + "enable-session-affinity": "" + } +} + + + +
+
+ Return all connections. + + Returning All Connections + + + GET : api/session/data/{data_source}/connections + + + Returns + + +{ + "1": { + "name": "Connection Name", + "identifier": "1", + "parentIdentifier": "ROOT", + "protocol": "ssh", + "attributes": { + "guacd-encryption": null, + "failover-only": null, + "weight": null, + "max-connections": null, + "guacd-hostname": null, + "guacd-port": null, + "max-connections-per-user": null + }, + "activeConnections": 0, + "lastActive": 1559870652000 + }, + ... +} + + + +
+
+ Add a connection. + + Adding a Connection + + + POST : api/session/data/{data_source}/connections + + + Example Payload (protocol dependent) + + +// RDP Connection Payload +{ + "name":"", + "identifier":"", + "parentIdentifier":"ROOT", + "protocol":"rdp", + "attributes": { + "max-connections":"","max-connections-per-user":"" + }, + "activeConnections":0, + "parameters": { + "disable-audio":"", + "server-layout":"", + "domain":"", + "hostname":"", + "enable-font-smoothing":"", + "security":"rdp", + "port":"3389", + "disable-auth":"", + "ignore-cert":"", + "console":"", + "width":"", + "height":"", + "dpi":"", + "color-depth":"", + "console-audio":"", + "enable-printing":"", + "enable-drive":"", + "create-drive-path":"", + "enable-wallpaper":"", + "enable-theming":"", + "enable-full-window-drag":"", + "enable-desktop-composition":"", + "enable-menu-animations":"", + "preconnection-id":"", + "enable-sftp":"", + "sftp-port":"" + } +} + +// VNC Connection Payload +{ + "parentIdentifier": "ROOT", + "name": "", + "protocol": "vnc", + "parameters": { + "port": "5900", + "read-only": "", + "swap-red-blue": "", + "cursor": "", + "color-depth": "", + "clipboard-encoding": "", + "dest-port": "", + "create-recording-path": "", + "enable-sftp": "", + "sftp-port": "", + "sftp-server-alive-interval": "", + "enable-audio": "", + "hostname": "", + "password": "" + }, + "attributes": { + "max-connections": "", + "max-connections-per-user": "", + "weight": "", + "failover-only": "", + "guacd-port": "", + "guacd-encryption": "", + "guacd-hostname": "" + } +} + +// SSH Connection Payload +{ + 'activeConnections': 0, + 'attributes': { + 'max-connections': '', + 'max-connections-per-user': '' + }, + 'identifier': '', + 'name': '', + 'parameters': { + 'hostname': '', + 'password': '', + 'port': '22', + 'username': '' + }, + 'parentIdentifier': 'ROOT', + 'protocol': 'ssh' +} + + + + Returns + + +{ + "name": "New Connection Name", + "identifier": "22", + "parentIdentifier": "ROOT", + "protocol": "ssh", + "attributes": { + "guacd-encryption": null, + "failover-only": null, + "weight": null, + "max-connections": "1", + "guacd-hostname": null, + "guacd-port": null, + "max-connections-per-user": "1" + }, + "activeConnections": 0, + "lastActive": 1559895631000 +} + + + +
+
+ Delete a connection. + + Deleting a Connection + + + DELETE : api/session/data/{data_source}/connections/{identifier} + {identifier} is the identifier property retrieved from one of the above API calls. + + + Returns + + +{ + "name": "Example Name", + "identifier": "3", + "parentIdentifier": "ROOT", + "protocol": "ssh", + "attributes": { + "guacd-encryption": null, + "failover-only": null, + "weight": null, + "max-connections": "1", + "guacd-hostname": null, + "guacd-port": null, + "max-connections-per-user": "1" + }, + "activeConnections": 0, + "lastActive": 1559895631000 +} + + + +
+
+ Return a connection. + + Returning a Connection + + + GET : api/session/data/{data_source}/connections/{identifier} + {identifier} is the identifier property retrieved from one of the above API calls. + + + Returns + + +{ + "name": "Example Name", + "identifier": "2", + "parentIdentifier": "ROOT", + "protocol": "ssh", + "attributes": { + "guacd-encryption": null, + "failover-only": null, + "weight": null, + "max-connections": "1", + "guacd-hostname": null, + "guacd-port": null, + "max-connections-per-user": "1" + }, + "activeConnections": 0, + "lastActive": 1559895631000 +} + + + +
+
+ Edit a connection. + + Editing a Connection + + + PUT : api/session/data/{data_source}/connections/{identifier} + {identifier} is the identifier property retrieved from one of the above API calls. + + + Example Payload + + +{ + "name":"New Connection Name", + "parentIdentifier":"ROOT", + "protocol":"rdp", + "attributes":{"max-connections":"","max-connections-per-user":""}, + "activeConnections":0, + "parameters": { + "disable-audio":"true", + "server-layout":"fr-fr-azerty", + "domain":"dt", + "hostname":"127.0.0.1", + "enable-font-smoothing":"true", + "security":"rdp", + "port":"3389", + "disable-auth":"", + "ignore-cert":"", + "console":"", + "width":"", + "height":"", + "dpi":"", + "color-depth":"", + "console-audio":"", + "enable-printing":"", + "enable-drive":"", + "create-drive-path":"", + "enable-wallpaper":"", + "enable-theming":"", + "enable-full-window-drag":"", + "enable-desktop-composition":"", + "enable-menu-animations":"", + "preconnection-id":"", + "enable-sftp":"", + "sftp-port":"" + } +} + + + + Returns + + +{ + "name": "New Connection Name", + "identifier": "2", + "parentIdentifier": "ROOT", + "protocol": "ssh", + "attributes": { + "guacd-encryption": null, + "failover-only": null, + "weight": null, + "max-connections": "1", + "guacd-hostname": null, + "guacd-port": null, + "max-connections-per-user": "1" + }, + "activeConnections": 0, + "lastActive": 1559895631000 +} + + + +
+
+ Get connection parameters. + + Returning Connection Parameters + + + GET : api/session/data/{data_source}/connections/{identifier}/parameters + {identifier} is the identifier property retrieved from one of the above API calls. + + + Returns + + +{ + "port": "22", + "hostname": "10.26.195.93" +} + + + +
+
+
+ Users + +
+ Return all users. + + Returning All Users + + + GET : api/session/data/{data_source}/users + + + Returns + + +{ + "admin": { + "username": "admin", + "attributes": { + "guac-email-address": "john.smith@example.com", + "guac-organizational-role": "Developer", + "guac-full-name": "Guacamole Admin", + "expired": null, + "timezone": null, + "access-window-start": null, + "guac-organization": "GG", + "access-window-end": null, + "disabled": null, + "valid-until": null, + "valid-from": null + }, + "lastActive": 1560481951000 + }, + ... +} + + + +
+
+ Add a user. + + Adding a User + + + POST : api/session/data/{data_source}/users + + + Example Payload + + +{ + 'username': '', + 'password': '', + 'attributes': { + 'disabled': '', + 'expired': '', + 'access-window-start': '', + 'access-window-end': '', + 'valid-from': '', + 'valid-until': '', + 'timezone': '' + } +} + + + + Returns + + +{ + "username": "admin", + "attributes": { + "guac-email-address": "admin.roger@example.com", + "guac-organizational-role": "Developer", + "guac-full-name": "Guacamole Admin", + "expired": null, + "timezone": null, + "access-window-start": null, + "guac-organization": "GG", + "access-window-end": null, + "disabled": null, + "valid-until": null, + "valid-from": null + }, + "lastActive": 1560481951000 +} + + + +
+
+ Delete a user. + + Deleting a User + + + DELETE : api/session/data/{data_source}/users/{username} + {username} is the username property retrieved from one of the above API calls. + + + Returns + + +{ + "username": "admin", + "attributes": { + "guac-email-address": "admin.roger@example.com", + "guac-organizational-role": "Developer", + "guac-full-name": "Guacamole Admin", + "expired": null, + "timezone": null, + "access-window-start": null, + "guac-organization": "GG", + "access-window-end": null, + "disabled": null, + "valid-until": null, + "valid-from": null + }, + "lastActive": 1560481951000 +} + + + +
+
+ Return a user's permissions. + + Returning a User's Permissions + + + GET : api/session/data/{data_source}/users/{username}/permissions + {username} is the username property retrieved from one of the above API calls. + + + Returns + + +{ + "connectionPermissions": { + "1": [ + "READ" + ], + "3": [ + "READ" + ], + "4": [ + "READ" + ] + }, + "connectionGroupPermissions": {}, + "sharingProfilePermissions": {}, + "activeConnectionPermissions": {}, + "userPermissions": { + "admin": [ + "READ" + ] + }, + "userGroupPermissions": {}, + "systemPermissions": [] +} + + + +
+
+ Edit a user's permissions. + + Editing a User's Permissions + + + PATCH : api/session/data/{data_source}/users/{username}/permissions + {username} is the username property retrieved from one of the above API calls. + + + Example Payload + + +{ + "connectionPermissions": { + "1": [ + "READ" + ], + "3": [ + "READ" + ], + "4": [ + "READ" + ] + }, + "connectionGroupPermissions": {}, + "sharingProfilePermissions": {}, + "activeConnectionPermissions": {}, + "userPermissions": { + "admin": [ + "READ" + ] + }, + "userGroupPermissions": {}, + "systemPermissions": [ + "CREATE_USER" + ] +} + + + + Returns + + +{ + "connectionPermissions": { + "1": [ + "READ" + ], + "3": [ + "READ" + ], + "4": [ + "READ" + ] + }, + "connectionGroupPermissions": {}, + "sharingProfilePermissions": {}, + "activeConnectionPermissions": {}, + "userPermissions": { + "admin": [ + "READ" + ] + }, + "userGroupPermissions": {}, + "systemPermissions": [ + "CREATE_USER" + ] +} + + + +
+
+ + diff --git a/src/gug.xml b/src/gug.xml index c0c930c1..02b18003 100644 --- a/src/gug.xml +++ b/src/gug.xml @@ -178,6 +178,7 @@ +