Batch Import and API
Create multiple connections via API or by uploading a CSV, JSON, or YAML file
Last updated
Create multiple connections via API or by uploading a CSV, JSON, or YAML file
Last updated
Keeper Connection Manager enables administrators to create connections and assign permissions to those connections by uploading a CSV, JSON, or YAML file.
Administrators can also update existing connections by checking the "Replace/Update existing connections" checkbox within the import UI:
Existing connections are identified by their name and parent connection group.
Additionally, Keeper Connection Manager enables administrators to also create connections and assign permissions to those connections via API.
The following file types are supported for connection import: CSV, JSON, and YAML.
In each of the file types, a connection is defined with the following data:
Connection Name
Connection Protocol
For a list of supported connection protocols visit this page
Connection Parameters (optional)
Connection Group Location (optional)
List of Users to grant access (optional)
List of User Groups to grant access (optional)
Connection Attributes (optional)
The connection import CSV file has one connection record per row where each column will specify a connection field.
The following sections will cover all the valid connection fields (columns) that are supported in the connection import CSV file:
At minimum, the connection name and protocol must be specified.
KCM supports the following connections protocols, and the corresponding "Internal name" must be used:
| Protocol | Internal name |
|---|---|
| |
| |
| |
| |
| |
| |
| |
|
The connection's parameters are dependent on your connection's protocol.
For more information on the available parameters for your connection protocol, refer to the table above and navigate to your protocol or visit this page
The connection group ID that the connection should be imported into may be directly specified with "parentIdentifier", or the path to the parent group may be specified using "group".
If a user or group identifier within the semicolon-separated list of users/groups needs to contain a semicolon, the semicolon can be escaped with a backslash. For example: "first\;last"
Lists of user or user group identifiers must be semicolon-separated and defined in the users and groups connection fields
Additional connection characteristics for your connection
Note: The first row in the above example specified the header
In most cases, there should be no conflict between fields, but if needed, an " (attribute)" or " (parameter)" suffix may be added to disambiguate.
The connection import JSON file has a list of connection objects. Each connection object supports the following keys:
| Key | Description |
|---|---|
name | Name of the connection |
protocol | Connection's protocol. For a list of supported connection protocols visit this page |
parameters | Connection's parameters to establish protocol connection. For required parameters visit this page. (Optional) |
parentIdentifier or group | The connection group ID that the connection should be imported into may be directly specified with a |
users | An array of user(s) to grant access to (Optional) |
groups | An array of user group(s) to grant access to (Optional) |
attributes | Connection's attributes |
At minimum the connection name and protocol must be specified in each connection object.
A connection import YAML file is a list of connection objects with exactly the same structure as the JSON format.
Keeper Connection Manager also enables administrators to batch import connections directly through the API by using the same endpoints that the Batch Import UI uses from the user interface.
To create or replace multiple connections, the HTTP PATCH method should be used on the connection directory resource, located at /api/session/data/{DATA_SOURCE}/connections. The data source specifies where the connections should be created, and will generally be the name of the database that was selected at install time i.e. mysql, postgres, or sqlserver. In the examples provided below, the mysql data source will be used.
See the KCM protocol documentation for more information on the possible parameters for any given connection protocol type.
Note that directory PATCH methods guarantee atomicity - the entire request must succeed; if any included patch fails, all changes in the batch will be rolled back.
Before using any other API endpoints, you'll need an auth token (HEX value). This can be extracted by examining the requests of a logged in user on the web app, or by directly making a request to the tokens endpoint. For example:
The response will include the auth token, as well as the data source that authorized the login:
You can use your favorite API tool. If using Postman, when sending a GET or PATCH, set your authorization to "Inherit auth from parent", and set a header with the key Guacamole-Token with the value set to your token. Keep in mind the default expiration of tokens is 60 minutes.
Each connection to be created must be represented by a separate PATCH in the request body, using the "add" operation. For example, to create a couple of new connections:
Users, user groups, connection groups, and sharing profiles can also be modified using the same PATCH semantics as connections. The API endpoints for each of these, respectively, are:
/api/session/data/{DATA_SOURCE}/users
/api/session/data/{DATA_SOURCE}/userGroups
/api/session/data/{DATA_SOURCE}/connectionGroups
/api/session/data/{DATA_SOURCE}/sharingProfiles
For a list of supported key-value pairs, visit this section of this document
The response will include the operation and ID for every connection, in the same order the patches were submitted:
To replace an existing connection, the "replace" operation can be used. Note that the "replace" operation will completely replace any connection fields, but any existing user or user group permissions will be retained. For example, to replace the connections created above, submit a "replace" patch for each:
To fully replace an existing connection, resetting all permissions granted for that connection, the connection should be deleted and recreated. This can be done using a pair of patches with the "remove" and "add" operations. For example, to fully replace the connections created earlier, submit a pair of patches for each:
To grant access to connections for a user or user group, submit a patch to grant access for each connection, by connection ID. For example, to grant access to the user "KCM_User_1", submit the following patches:
To grant permissions to a user group, use: /api/session/data/{DATA_SOURCE}/userGroups/{GROUP_ID}/permissions
e.g.:
/api/session/data/mysql/userGroups/KCM%20Administrators/permissions
Once you're done using the API, the auth token should be explicitly disabled:
If an error is encountered while submitting a list of patches, an overall error will be returned, including any patch-specific errors. For example, when attempting to create connections that already exist with the same name at the same connection group: