概要
APIのセクションへ移動
CSV、JSON、YAMLを使用して接続をインポート
Keeperコネクションマネージャーを使用すると、管理者はCSV、JSON、YAMLファイル をアップロードして接続を作成し、それらの接続に権限を割り当てることができます。
管理者は、以下のインポートUIの[Replace/Update existing connections] (既存の接続を置換/更新する) チェックボックスをオンにして、既存の接続を更新することもできます。
既存の接続は、名前と親接続グループによって識別されます。
APIを使用して接続をインポート
また、Keeperコネクションマネージャーを使用すると、管理者はAPI を使用して接続を作成し、それらの接続に権限を割り当てることもできます。
サポートされているファイルタイプのファイルデータ
接続のインポートでは、CSV、JSON、YAMLのファイルタイプがサポートされています。
各ファイルタイプで、以下のデータで接続が定義されています。
接続プロトコル
サポートされている接続プロトコルの一覧は、こちらのページ をご参照ください。
アクセスを許可するユーザーのリスト (オプション)
アクセスを許可するグループのリスト (オプション)
CSVを使用して接続をインポート
接続インポート用のCSVファイルには、行ごとに接続レコードが1つ含まれ、列ごとに接続フィールドを指定します。
以下のセクションでは、接続インポートCSVファイルでサポートされているすべての有効な接続フィールド (列) について解説します。
必須接続フィールド - 名前とプロトコル
少なくとも、接続のname とprotocol を指定する必要があります。
KCMでは以下の接続プロトコルがサポートされており、対応する「内部名」を使用します。
オプションの接続フィールド - 接続パラメータ
接続パラメータはご使用の接続プロトコルに左右されます。
接続プロトコルで使用可能なパラメータの詳細については、上の表からご使用のプロトコルへ移動するか、こちらのページ をご参照ください。
オプションの接続フィールド - グループまたは親識別子
接続をインポートする接続グループのIDは、「parentIdentifier」で直接指定することもできますし、「group」を使用して親グループへのパスを指定することもできます。
セミコロンで区切られたユーザー/グループのリスト内のユーザーまたはグループの識別子でセミコロンを使用する必要がある場合は、「first\;last」のようにセミコロンをバックスラッシュでエスケープできます。
オプションの接続フィールド - ユーザーとグループ
ユーザーまたはユーザーグループの識別子のリストはセミコロンで区切り、users接続フィールドとgroups 接続フィールドで定義する必要があります。
オプションの接続フィールド - 属性
その他の接続特性
例
Copy name, protocol, username, password, private-key, hostname, group, users, groups,guacd-encryption (attribute)
conn1, vnc, alice, pass1, , conn1.web.com, ROOT, guac user 1;guac user 2, Connection 1 Users,none
conn2, rdp, bob, pass2, , conn2.web.com, ROOT/Parent Group, guac user 1, ,ssl
conn3, ssh, ${KEEPER_SERVER_USERNAME}, , ${KEEPER_SERVER_KEY}, conn3.web.com, ROOT/Parent Group/Child Group, guac user 2;guac user 3, ,
conn4, kubernetes, , , , , , , , 注: 上記の例の最初の行はヘッダです。
ほとんどの場合フィールド間に競合はありませんが、必要に応じて曖昧さをなくすために「(attribute)」または「(parameter)」の接尾辞を追加できます。
JSONを使用して接続をインポート
接続インポート用のJSONファイルには、接続オブジェクトのリストが含まれます。各接続オブジェクトは、以下のキーをサポートしています。
接続をインポートする接続グループのIDは、parentIdentifierキーで直接指定することもできますし、groupキーを使用して親グループへのパスを指定することもできます (オプション)
アクセスを許可するユーザーグループの配列 (オプション)
少なくとも、接続オブジェクトごとに、接続の名前とプロトコルを指定する必要があります。
例
Copy [
{
"name" : "conn1" ,
"protocol" : "vnc" ,
"parameters" : { "username" : "alice" , "password" : "pass1" , "hostname" : "conn1.web.com" } ,
"parentIdentifier" : "ROOT" ,
"users" : [ "guac user 1" , "guac user 2" ] ,
"groups" : [ "Connection 1 Users" ] ,
"attributes" : { "guacd-encryption" : "none" }
} ,
{
"name" : "conn2" ,
"protocol" : "rdp" ,
"parameters" : { "username" : "bob" , "password" : "pass2" , "hostname" : "conn2.web.com" } ,
"group" : "ROOT/Parent Group" ,
"users" : [ "guac user 1" ] ,
"attributes" : { "guacd-encryption" : "none" }
} ,
{
"name" : "conn3" ,
"protocol" : "ssh" ,
"parameters" : { "username" : "${KEEPER_SERVER_USERNAME}" , "private-key" : "${KEEPER_SERVER_KEY}" , "hostname" : "conn3.web.com" } ,
"group" : "ROOT/Parent Group/Child Group" ,
"users" : [ "guac user 2" , "guac user 3" ]
} ,
{
"name" : "conn4" ,
"protocol" : "kubernetes"
}
] YAMLを使用して接続をインポート
接続インポート用のYAMLファイルは、JSON形式とまったく同じ構造を持つ接続オブジェクトのリストです。
Copy ---
- name : conn1
protocol : vnc
parameters :
username : alice
password : pass1
hostname : conn1.web.com
group:ROOT
users :
- guac user 1
- guac user 2
groups :
- Connection 1 Users
attributes :
guacd-encryption : none
- name : conn2
protocol : rdp
parameters :
username : bob
password : pass2
hostname : conn2.web.com
group:ROOT/Parent Group
users :
- guac user 1
attributes :
guacd-encryption : none
- name : conn3
protocol : ssh
parameters :
username : ${KEEPER_SERVER_USERNAME}
private-key : ${KEEPER_SERVER_KEY}
hostname : conn3.web.com
group:ROOT/Parent Group/Child Group
users :
- guac user 2
- guac user 3
- name : conn4
protocol : kubernetes APIを使用して接続をインポート
Keeperコネクションマネージャーでは管理者がAPIで接続を直接一括インポートすることもできます。その際、一括インポートUIがユーザーインターフェースで使用するのと同じエンドポイントを使用します。
複数の接続を作成または置換するには、/api/session/data/{DATA_SOURCE}/connectionsにある接続ディレクトリリソースでHTTP PATCHメソッドを使用する必要があります。データソースは、接続を作成する場所を指定し、通常はインストール時に選択したデータベースの名前、つまり、mysql、postgres、sqlserverなどになります。以下の例では、mysqlデータソースを使用します。
どの接続プロトコルタイプでも使用可能なパラメータの詳細は、KCMプロトコルのドキュメント をご参照ください。
ディレクトリPATCHメソッドはアトミック性が保証されます。つまり、要求全体が成功する必要があります。含まれているパッチのいずれかが失敗した場合、バッチ内の変更はすべてロールバックされます。
ログイン (API認証トークン)
他のAPIエンドポイントを使用する前に、認証トークンが必要になります。これは、ウェブアプリにログインしているユーザーのリクエストを調べるか、トークンエンドポイントに直接リクエストを発行することで抽出できます。以下に例を示します。
Copy curl 'https://kcm.example.com/api/tokens' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'username=kcm_admin&password=kcm_admin_pass123' レスポンスには、認証トークンと、ログインを許可したデータソースが含まれます。
Copy {
"authToken" : "TG9YZW0GAXBZDW0GZG9SB3IGC2L0" ,
"username" : "kcm_admin" ,
"dataSource" : "mysql" ,
"availableDataSources" : [
"mysql" ,
"mysql-shared"
]
} 任意のAPIツールをご使用いただけますが、 Postmanを使用している場合は、GETまたはPATCHを送信する際に、認証を「Inherit auth from parent」 (親から認証を継承) に設定し、KeyがGuacamoleToken、Valueがトークンであるヘッダを設定します。トークンのデフォルトの有効期限は60分となります。
接続の新規作成
作成する各接続は、「add」操作を使用して、リクエストのボディで個別のPATCHによって表記する必要があります。たとえば、新しい接続をいくつか作成する手順は以下のとおりです。
Copy cat << 'EOF' | curl 'https://kcm.example.com/api/session/data/mysql/connections' \
-X 'PATCH' \
-H 'Content-Type: application/json' \
-H 'Guacamole-Token:TG9YZW0GAXBZDW0GZG9SB3IGC2L0' \
-d '@-'
[
{
"op": "add",
"path": "/",
"value": {
"parentIdentifier":"ROOT",
"name": "conn1 ssh",
"protocol": "ssh",
"parameters": {
"hostname": "conn1.web.com",
"color-scheme": "white-black",
"username": "${KEEPER_SERVER_USERNAME}",
"private-key": "${KEEPER_SERVER_KEY}"
},
"attributes": {
"guacd-encryption": "none"
}
}
},
{
"op": "add",
"path": "/",
"value": {
"parentIdentifier":"1",
"name": "conn2 vnc",
"protocol": "vnc",
"parameters": {
"hostname": "conn2.web.com",
"username": "alice",
"password": "password123"
},
"attributes": {}
}
}
] ユーザー、ユーザーグループ、接続グループ、共有プロファイルも、接続と同じPATCHセマンティクスを使用して変更できます。それぞれのAPIエンドポイントは以下のとおりです。
/api/session/data/{DATA_SOURCE}/users
/api/session/data/{DATA_SOURCE}/userGroups
/api/session/data/{DATA_SOURCE}/connectionGroups
/api/session/data/{DATA_SOURCE}/sharingProfiles
サポートされているキーと値のペアの一覧については、本ページのこちらのセクション をご参照ください。
レスポンスには、パッチが送信されたのと同じ順序で、すべての接続の操作とIDが含まれます。
Copy {
"patches" : [
{
"op" : "add" ,
"identifier" : "1" ,
"path" : "/"
} ,
{
"op" : "add" ,
"identifier" : "2" ,
"path" : "/"
}
]
} 既存の接続を更新
既存の接続を置き換えるには、「replace」操作を使用できます。「replace」操作はすべての接続フィールドを完全に置換しますが、既存のユーザーまたはユーザーグループの権限は保持されることにご留意ください。たとえば、作成した前述の接続を置き換えるには、それぞれに「replace」パッチを送信します。
Copy cat << 'EOF' | curl 'https://kcm.example.com/api/session/data/mysql/connections' \
-X 'PATCH' \
-H 'Content-Type: application/json' \
-H 'Guacamole-Token:TG9YZW0GAXBZDW0GZG9SB3IGC2L0' \
-d '@-'
[
{
"op": "replace",
"path": "/1",
"value": {
"parentIdentifier":"ROOT",
"name": "conn1 ssh (updated)",
"protocol": "ssh",
"parameters": {
"hostname": "conn1-new.web.com",
"color-scheme": "white-black",
"username": "${KEEPER_SERVER_USERNAME}",
"private-key": "${KEEPER_SERVER_KEY}"
},
"attributes": {
"guacd-encryption": "ssl"
}
}
},
{
"op": "replace",
"path": "/2",
"value": {
"parentIdentifier":"1",
"name": "conn2 vnc (updated)",
"protocol": "vnc",
"parameters": {
"hostname": "conn2-new.web.com",
"username": "bob",
"password": "password12345"
},
"attributes": {}
}
}
] 既存の接続の完全な置換
既存の接続を完全に置き換え、その接続に付与されているすべての権限をリセットするには、接続を削除して再作成する必要があります。これは、「remove」および「add」操作を含むパッチのペアを使用して実行できます。たとえば、前に作成した接続を完全に置き換えるには、それぞれのパッチのペアを送信します。
Copy cat << 'EOF' | curl 'https://kcm.example.com/api/session/data/mysql/connections' \
-X 'PATCH' \
-H 'Content-Type: application/json' \
-H 'Guacamole-Token:TG9YZW0GAXBZDW0GZG9SB3IGC2L0' \
-d '@-'
[
{
"op": "remove",
"path": "/1"
},
{
"op": "add",
"path": "/",
"value": {
"parentIdentifier":"ROOT",
"name": "conn1 ssh (completely replaced)",
"protocol": "ssh",
"parameters": {
"hostname": "conn1-newest.web.com",
"username": "${KEEPER_SERVER_USERNAME}",
"private-key": "${KEEPER_SERVER_KEY}"
},
"attributes": {}
}
},
{
"op": "remove",
"path": "/2"
},
{
"op": "add",
"path": "/",
"value": {
"parentIdentifier":"1",
"name": "conn2 vnc (completely replaced)",
"protocol": "vnc",
"parameters": {
"hostname": "conn2-newest.web.com",
"username": "carol",
"password": "password123456789"
},
"attributes": {}
}
}
] 接続にアクセス権を付与
ユーザーまたはユーザーグループの接続にアクセス権を付与するには、接続ごと (接続ID別) にアクセス権を付与するパッチを送信します。たとえば、ユーザー「KCM_User_1」へのアクセスを許可するには、以下のパッチを送信します。
Copy cat << 'EOF' | curl 'https://kcm.example.com/api/session/data/mysql/users/KCM_User_1/permissions' \
-X 'PATCH' \
-H 'Content-Type: application/json' \
-H 'Guacamole-Token:TG9YZW0GAXBZDW0GZG9SB3IGC2L0' \
-d '@-'
[
{
"op": "add",
"path": "/connectionPermissions/1",
"value":"READ"
},
{
"op": "add",
"path": "/connectionPermissions/2",
"value":"READ"
}
] ユーザーグループに権限を付与するには、以下を使用します。
/api/session/data/{DATA_SOURCE}/userGroups/{GROUP_ID}/permissions
例
/api/session/data/mysql/userGroups/KCM%20Administrators/permissions
ログアウト
APIの使用が終了したら、認証トークンを無効にする必要があります。
Copy curl 'https://kcm.example.com/api/session' \
-X 'DELETE' \
-H 'Guacamole-Token:TG9YZW0GAXBZDW0GZG9SB3IGC2L0' エラー
パッチのリストの送信中にエラーが発生した場合は、パッチ固有のエラーを含むすべてのエラーが返されます。たとえば、同じ接続グループに同じ名前ですでに存在する接続を作成しようとした場合に返すエラーは、以下のようになります。
Copy {
"message" : "The provided patches failed to apply." ,
"translatableMessage" : {
"key" : "APP.TEXT_UNTRANSLATED" ,
"variables" : {
"MESSAGE" : "The provided patches failed to apply."
}
} ,
"statusCode" : null ,
"expected" : null ,
"patches" : [
{
"op" : "add" ,
"identifier" : null ,
"path" : "/" ,
"error" : {
"key" : "APP.TEXT_UNTRANSLATED" ,
"variables" : {
"MESSAGE" : "The connection \"KCM connection 1\" already exists."
}
}
} ,
{
"op" : "add" ,
"identifier" : null ,
"path" : "/" ,
"error" : {
"key" : "APP.TEXT_UNTRANSLATED" ,
"variables" : {
"MESSAGE" : "The connection \"KCM connection 2\" already exists."
}
}
}
] ,
"type" : "BAD_REQUEST"
} 
