Batch Import and API
Create multiple connections via API or by uploading a CSV, JSON, or YAML file
Overview
Importing Connections with CSV, JSON, or YAML
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.
Importing Connections via API
Additionally, Keeper Connection Manager enables administrators to also create connections and assign permissions to those connections via API.
File Data in Supported File Types
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)
Importing Connections with CSV
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:
Required Connection Fields - name & protocol
At minimum, the connection name and protocol must be specified.
KCM supports the following connections protocols, and the corresponding "Internal name" must be used:
Optional Connection Fields - connection parameters
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
Optional Connection Fields - group or parentIdentifier
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"
Optional Connection Fields - users and groups
Lists of user or user group identifiers must be semicolon-separated and defined in the users and groups connection fields
Optional Connection Fields - attributes
Additional connection characteristics for your connection
Examples
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.
Importing Connections with JSON
The connection import JSON file has a list of connection objects. Each connection object supports the following keys:
At minimum the connection name and protocol must be specified in each connection object.
Examples
Importing Connections with YAML
A connection import YAML file is a list of connection objects with exactly the same structure as the JSON format.
Importing Connections via API
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.
Logging In - API Authentication Token
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.
Creating New Connection
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:
Updating Existing Connections
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:
Fully Replacing Existing Connections
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:
Granting Access to Connections
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
Logging Out
Once you're done using the API, the auth token should be explicitly disabled:
Errors
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:
Last updated