接続の一括インポート

APIを使用するかCSV、JSON、YAMLファイルをアップロードして複数の接続を作成

概要

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では以下の接続プロトコルがサポートされており、対応する「内部名」を使用します。

プロトコル	内部名
VNC	vnc
RDP	rdp
SSH	ssh
Telnet	telnet
Kubernetes	kubernetes
MySQL	mysql
PostgreSQL	postgresql
Microsoft SQL Server	sql-server

オプションの接続フィールド - 接続パラメータ

接続パラメータはご使用の接続プロトコルに左右されます。

接続プロトコルで使用可能なパラメータの詳細については、上の表からご使用のプロトコルへ移動するか、こちらのページをご参照ください。

オプションの接続フィールド - グループまたは親識別子

接続をインポートする接続グループのIDは、「parentIdentifier」で直接指定することもできますし、「group」を使用して親グループへのパスを指定することもできます。

セミコロンで区切られたユーザー/グループのリスト内のユーザーまたはグループの識別子でセミコロンを使用する必要がある場合は、「first\;last」のようにセミコロンをバックスラッシュでエスケープできます。

オプションの接続フィールド - ユーザーとグループ

ユーザーまたはユーザーグループの識別子のリストはセミコロンで区切り、users接続フィールドとgroups接続フィールドで定義する必要があります。

オプションの接続フィールド - 属性

その他の接続特性

例

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ファイルには、接続オブジェクトのリストが含まれます。各接続オブジェクトは、以下のキーをサポートしています。

キー	説明
name	接続の名前
protocol	接続のプロトコル。サポートされている接続プロトコルの一覧については、こちらのページをご参照ください
parameters	プロトコル接続を確立するための接続のパラメータ。必須パラメータについては、こちらのページをご参照ください (オプション)
parentIdentifierまたはgroup	接続をインポートする接続グループのIDは、parentIdentifierキーで直接指定することもできますし、groupキーを使用して親グループへのパスを指定することもできます (オプション)
users	アクセスを許可するユーザーの配列 (オプション)
groups	アクセスを許可するユーザーグループの配列 (オプション)
attributes	接続の属性

少なくとも、接続オブジェクトごとに、接続の名前とプロトコルを指定する必要があります。

例

[
  {
    "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形式とまったく同じ構造を持つ接続オブジェクトのリストです。

---
  - 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エンドポイントを使用する前に、認証トークンが必要になります。これは、ウェブアプリにログインしているユーザーのリクエストを調べるか、トークンエンドポイントに直接リクエストを発行することで抽出できます。以下に例を示します。

curl 'https://kcm.example.com/api/tokens' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'username=kcm_admin&password=kcm_admin_pass123'

レスポンスには、認証トークンと、ログインを許可したデータソースが含まれます。

{
  "authToken":"TG9YZW0GAXBZDW0GZG9SB3IGC2L0",
  "username": "kcm_admin",
  "dataSource": "mysql",
  "availableDataSources": [
    "mysql",
    "mysql-shared"
  ]
}

任意のAPIツールをご使用いただけますが、 Postmanを使用している場合は、GETまたはPATCHを送信する際に、認証を「Inherit auth from parent」 (親から認証を継承) に設定し、KeyがGuacamoleToken、Valueがトークンであるヘッダを設定します。トークンのデフォルトの有効期限は60分となります。

Postmanを使用したサンプル

接続の新規作成

作成する各接続は、「add」操作を使用して、リクエストのボディで個別のPATCHによって表記する必要があります。たとえば、新しい接続をいくつか作成する手順は以下のとおりです。

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が含まれます。

{
  "patches": [
    {
      "op": "add",
      "identifier":"1",
      "path": "/"
    },
    {
      "op": "add",
      "identifier":"2",
      "path": "/"
    }
  ]
}

既存の接続を更新

既存の接続を置き換えるには、「replace」操作を使用できます。「replace」操作はすべての接続フィールドを完全に置換しますが、既存のユーザーまたはユーザーグループの権限は保持されることにご留意ください。たとえば、作成した前述の接続を置き換えるには、それぞれに「replace」パッチを送信します。

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」操作を含むパッチのペアを使用して実行できます。たとえば、前に作成した接続を完全に置き換えるには、それぞれのパッチのペアを送信します。

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」へのアクセスを許可するには、以下のパッチを送信します。

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の使用が終了したら、認証トークンを無効にする必要があります。

curl 'https://kcm.example.com/api/session' \
  -X 'DELETE' \
  -H 'Guacamole-Token:TG9YZW0GAXBZDW0GZG9SB3IGC2L0'

エラー

パッチのリストの送信中にエラーが発生した場合は、パッチ固有のエラーを含むすべてのエラーが返されます。たとえば、同じ接続グループに同じ名前ですでに存在する接続を作成しようとした場合に返すエラーは、以下のようになります。

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