一括インポートとAPI

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

少なくとも、接続の name (名前) と protocol (プロトコル) を指定する必要があります。

KCMは以下の接続プロトコルに対応しており、それぞれに対応する「Internal name」(内部名) を使用する必要があります。

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

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

接続のパラメータは、接続のプロトコルに依存します。

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

オプションの接続フィールド - group または parentIdentifier

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

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

オプションの接続フィールド - users と groups

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

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

接続の追加の特性を指定します。

例

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コネクションマネージャーでは、管理者がBatch Import UIと同じエンドポイントを使用して、API経由で接続を直接一括インポートすることもできます。

複数の接続を作成または置換するには、接続ディレクトリリソース (/api/session/data/{DATA_SOURCE}/connections) に対してHTTP PATCHメソッドを使用します。データソースは接続の作成先を指定し、通常はインストール時に選択したデータベースの名前、つまり mysql、postgres、または sqlserver になります。以下の例では、mysql データソースを使用します。

任意の接続プロトコルタイプで使用可能なパラメータについて詳しくは、KCMプロトコルのドキュメントをご参照ください。

ディレクトリのPATCHメソッドではアトミック性が保証されます。リクエスト全体が成功する必要があり、含まれるいずれかのパッチが失敗した場合、バッチ内のすべての変更がロールバックされます。

ログイン - API認証トークン

他のAPIエンドポイントを使用する前に、認証トークン (HEX値) が必要です。Webアプリにログインしたユーザーのリクエストを確認するか、tokens エンドポイントに直接リクエストを送信することで取得できます。以下は、その例です。

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] に設定し、キーを Guacamole-Token、値をトークンとしたヘッダーを設定します。トークンのデフォルトの有効期限は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"
}