# Royal TS/TSX

<figure><img src="https://859776093-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPL6k1aGsLiFiiJ3Y7zCl%2Fuploads%2Fgit-blob-245771c5085c155a3034d05e96124769d5b6ff24%2FKeeper%2BRoyal%20TS.png?alt=media" alt=""><figcaption></figcaption></figure>

**Keeperシークレットマネージャー (KSM)** を [Royal TS](https://www.royalapplications.com/ts/win) (Windows) および [Royal TSX](https://www.royalapplications.com/ts/mac) (macOS) と組み合わせると、サーバーやデータベースに接続できます。ボルトのレコードは**動的認証情報**として表示され、接続時にKeeperからシークレットが取得されます。

本ページでは、公式のPythonパッケージ `keeper-secrets-manager-core` を介してKeeperと通信する **Keeper KSM (Python)** ダイナミックフォルダのインストール手順と使い方を説明します。

***

### 概要 <a href="#overview" id="overview"></a>

|                |                                                                                      |
| -------------- | ------------------------------------------------------------------------------------ |
| **役割**         | KeeperボルトのサーバーおよびデータベースレコードをRoyalの**ダイナミックフォルダ**に取り込み、接続にKeeper由来の認証情報を紐付けられるようにします。 |
| **シークレットの所在**  | パスワードなどの機密項目は**Keeper**側に残ります。接続の都度、KSM経由で参照されます。                                    |
| **対応プラットフォーム** | **Royal TS** v7以降 (Windows)、**Royal TSX** v6以降 (macOS)。                              |
| **認証方式**       | Keeper組織のシークレットマネージャーアプリケーションに紐付く**KSM構成ファイル**。                                      |

{% hint style="info" %}
本連携には**Keeperシークレットマネージャー**とKSMクライアントSDKライブラリが必要です。
{% endhint %}

#### 実行できること <a href="#what-you-can-do" id="what-you-can-do"></a>

* **サーバー**レコードを使い、SSH、SFTP、RDPの接続に利用できます。Royalで接続を作成し、一致する動的認証情報を選びます。
* **データベース**レコードでは **MySQL**、**PostgreSQL**、**Microsoft SQL Server**、**Oracle**、**MongoDB**、**Redis** のクライアントセッションを、生成された接続ツリーから開けます。**Royalを実行しているマシン上**のデータベースクライアント実行ファイルのパスを設定します。各レコードの**データベースサーバー**は**ローカルでもリモートでも**構いません (ホストとポートはKeeperの値を使用します)。
* 構成は両OSでボルトから**JSONまたはBase64**のファイルを使う方法に加え、macOSでは `ksm init` で得た **INI** ファイルも利用できます。

***

### 要件 <a href="#requirements" id="requirements"></a>

| 要件                     | 詳細                                                                                                                                                                   |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Keeperプラン**          | **シークレットマネージャー**へのアクセス (組織のプランに応じたコンシューマー、ビジネス、またはエンタープライズ)。                                                                                                         |
| **KSMアプリケーション**        | **Keeper管理コンソール**のシークレットマネージャーアプリケーションと、ボルトのレコードをそのアプリケーションへ**共有**した状態。[クイックスタートガイド](https://docs.keeper.io/jp/keeperpam/secrets-manager/quick-start-guide)をご参照ください。 |
| **Royal TS** (Windows) | バージョン**7**以降。                                                                                                                                                        |
| **Royal TSX** (macOS)  | バージョン**6**以降。                                                                                                                                                        |
| **Python**             | **3.9**以降 (3.13推奨)。Royal TS / Royal TSX がダイナミックフォルダのスクリプトに使う **同一** の `python` 実行ファイルであること。                                                                          |
| **Pythonパッケージ**        | そのPython環境に `keeper-secrets-manager-core` をインストール済みであること。                                                                                                            |
| **構成ファイル**             | ボルトからダウンロードしたJSONまたはBase64ファイル (WindowsおよびmacOS)、またはmacOSのみ `ksm init` で得た `.ini`。                                                                                   |

**任意 — Keeperのデータベースレコードのみ使う場合**

|                  |                                                                                                                                                                         |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **インストールするもの**   | **Royal TS または Royal TSX をインストールしたのと同一のコンピューター**に、**データベースクライアント** (例: `mysql`、`psql`、`sqlcmd`、`mongosh`、`redis-cli`、`sqlplus`) をインストールします。データベースサーバー側には不要です。           |
| **Royalで設定する内容** | ダイナミックフォルダの**カスタムプロパティ**で、**MySQL Path**、**PostgreSQL Path** などがそれら**ローカルのクライアント実行ファイル**を指すようにします。**実際に使うエンジンごと**にパスを設定します (例: MySQLのデータベースレコードだけなら **MySQL Path** のみ)。 |
| **データベースの実行場所**  | **データベースサーバー**は**このマシン上でもネットワーク上のどこでも**構いません (クラウド、データセンター、他拠点など)。各**Keeperデータベース**レコードの**ホスト**と**ポート**がそのサーバーを示し、ローカルクライアントがネットワーク経由で接続します。                            |

**サーバー**レコード (SSH、RDP、SFTP) **のみ**でデータベースレコードを**使わない**場合は、データベースクライアントやこれらのパスは**不要**です。

***

### 事前準備 <a href="#before-you-begin" id="before-you-begin"></a>

1. **KSMアプリケーションを新規作成または既存を利用**し、構成ファイルを用意します。ボルトから**JSONまたはBase64**をダウンロードする方法 (WindowsおよびmacOS)、またはmacOSのみ **`ksm init`** で**INI**を作成する方法があります。[クイックスタートガイド](https://docs.keeper.io/jp/keeperpam/secrets-manager/quick-start-guide)をご参照ください。
2. そのKSMアプリケーションに**ボルトのレコードを共有**します。共有されていないレコードは表示されないか、接続時に認証情報の取得に失敗します。
3. [Royal Applications Toolbox](https://github.com/royalapplications/toolbox/tree/master/Dynamic%20Folder/Keeper)からダイナミックフォルダパッケージ **`Keeper KSM (Python).rdfx`** をダウンロードします。

***

### Windowsでのインストール (Royal TS) <a href="#install-on-windows-royal-ts" id="install-on-windows-royal-ts"></a>

#### 1. Pythonのインストール <a href="#id-1-install-python" id="id-1-install-python"></a>

**Python 3.9+** (3.13推奨) をインストールします。Royal TSがスクリプトに呼び出すビルドを選びます。

#### 2. KSM Pythonパッケージのインストール <a href="#id-2-install-the-ksm-python-package" id="id-2-install-the-ksm-python-package"></a>

Royal TSは **\[ファイル]** → **\[オプション]** → **\[プラグイン]** (スクリプトインタープリター) で設定したインタープリターを使います。**その** `python.exe` でパッケージをインストールします。

```cmd
"C:\Path\To\Python\python.exe" -m pip install keeper-secrets-manager-core
```

パスはRoyal TSに表示されているインタープリターに合わせて置き換えます。

#### 3. ディスク上にKSM構成ファイルを置く <a href="#id-3-add-a-ksm-configuration-file-on-disk" id="id-3-add-a-ksm-configuration-file-on-disk"></a>

**Keeperボルト**で **\[シークレットマネージャー]** → **\[デバイスを追加]** → **\[構成ファイル]** → **\[ダウンロード]** と進み、**JSON**または**Base64**の構成ファイルを取得します。PC上の分かりやすい場所に保存します (例: `C:\Users\YourName\keeper-config.json`)。

#### 4. Royalドキュメントの新規作成または開く <a href="#id-4-create-or-open-a-royal-document" id="id-4-create-or-open-a-royal-document"></a>

新規ドキュメントを作成し保存します (例: `My Connections.rtsz`)。

#### 5. ダイナミックフォルダのインポート <a href="#id-5-import-the-dynamic-folder" id="id-5-import-the-dynamic-folder"></a>

**\[ファイル]** → **\[開く]** → **\[インポート]** → ファイルの種類に **\[ダイナミックフォルダ]** を選び、**`Keeper KSM (Python)`** を指定して **\[OK]**。

<figure><img src="https://859776093-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPL6k1aGsLiFiiJ3Y7zCl%2Fuploads%2Fgit-blob-ddb1d07a3772f767b5b8ad6aa9858f8d93dbd95e%2Fimage%20(130)-ja.png?alt=media" alt=""><figcaption></figcaption></figure>

#### 6. カスタムプロパティの設定 <a href="#id-6-set-custom-properties" id="id-6-set-custom-properties"></a>

**Keeper Secrets Manager (Python)** を右クリック → **\[プロパティ]** → **\[カスタムプロパティ]**。

* **KSM Config Path (Windows)** — KSM構成ファイル (**`.json`** または **`.base64`**) のフルパス。例: `C:\Users\YourName\keeper-config.json`。

<figure><img src="https://859776093-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPL6k1aGsLiFiiJ3Y7zCl%2Fuploads%2Fgit-blob-2857290944fe2e2f9fc08c581df68ef09f2a8c7a%2Fimage%20(1)%20(5)%20(2).png?alt=media" alt=""><figcaption></figcaption></figure>

**データベースクライアントのパス (データベースレコードを使う場合のみ):** 各パスは**このWindows PC上**のクライアントツールを指します。接続先データベースの**ホスト**と**ポート**はここには入力せず、各**Keeperデータベース**レコードから取得します。**実際に使うエンジンの行だけ**設定します。

| カスタムプロパティ                 | 例                                                                                     |
| ------------------------- | ------------------------------------------------------------------------------------- |
| MySQL Path (Windows)      | `C:\Program Files\MySQL\MySQL Server 8.0\bin\mysql.exe`                               |
| PostgreSQL Path (Windows) | `C:\Program Files\PostgreSQL\16\bin\psql.exe`                                         |
| MSSQL Path (Windows)      | `C:\Program Files\Microsoft SQL Server\Client SDK\ODBC\170\Tools\Binn\SQLCMD.EXE`     |
| Oracle Path (Windows)     | `C:\oracle\instantclient\sqlplus.exe`                                                 |
| MongoDB Path (Windows)    | `C:\Program Files\MongoDB\mongosh.exe`                                                |
| Redis Path (Windows)      | `C:\Program Files\Redis\redis-cli.exe` または `C:\Program Files\Memurai\memurai-cli.exe` |

#### 7. フォルダの再読み込み <a href="#id-7-reload-the-folder" id="id-7-reload-the-folder"></a>

ダイナミックフォルダを右クリック → **\[再読み込み]**。ツリーを展開し、認証情報が表示されることを確認します。

#### 任意: データベースクライアントのインストール (Windows) <a href="#optional-install-database-clients-windows" id="optional-install-database-clients-windows"></a>

Royal がデータベースクライアントを起動できるよう、**お使いのPC上**にインストールします。接続先は各Keeperレコードの**ホスト**に従い、**ローカルまたはリモート**のデータベースになります。ベンダー公式の**Windows**用インストーラーまたはパッケージで、必要なクライアントだけをインストールしてください。

| エンジン                     | 一般的な手順                                                                                                                                                                            |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **MySQL**                | [MySQL Installer](https://dev.mysql.com/downloads/installer/) (クライアントツール / シェル) または単体の**MySQL Shell**ビルド。インストール後の `mysql.exe` のパスをカスタムプロパティに指定します。                                |
| **PostgreSQL**           | [Windows用インストーラ](https://www.postgresql.org/download/windows/)。`psql.exe` を含みます (多くの場合 `C:\Program Files\PostgreSQL\<version>\bin\`)。                                             |
| **Microsoft SQL Server** | Microsoftの [sqlcmd](https://learn.microsoft.com/en-us/sql/tools/sqlcmd/sqlcmd-utility)およびODBCツール (多くの場合 `...\Microsoft SQL Server\Client SDK\ODBC\...\Binn\`。インストール済みバージョンに合わせる)。 |
| **MongoDB**              | Windows用 [mongosh](https://www.mongodb.com/try/download/shell)。                                                                                                                   |
| **Redis**                | **redis-cli**または**Memurai**の **`memurai-cli.exe`** (同一の **`-h`** / **`-p`** / **`-a`** / **`--user`** フラグ)。**Redis Path**を実際の `redis-cli.exe` または `memurai-cli.exe` に合わせます。       |
| **Oracle**               | [Oracle Instant Client](https://www.oracle.com/database/technologies/instant-client/winx64-downloads.html) (またはフルクライアント)。`sqlplus.exe` のパスはインストール先に依存します。                         |

インストール後は**カスタムプロパティ**を実際の `.exe` パスに合わせます (手順6の例を参照)。

***

### macOSでのインストール (Royal TSX) <a href="#install-on-macos-royal-tsx" id="install-on-macos-royal-tsx"></a>

#### 1. Pythonのインストール <a href="#id-1-install-python-1" id="id-1-install-python-1"></a>

**Python 3.9+** (3.13推奨) をインストールします。

#### 2. KSM Pythonパッケージのインストール <a href="#id-2-install-the-ksm-python-package-1" id="id-2-install-the-ksm-python-package-1"></a>

Royal TSXは **\[設定]** → **\[プラグイン]** → **\[Python]** (または **\[設定]** → **\[Python]**) でPythonを選び、多くの場合バージョンメニューから指定します。**その**インタープリターに `keeper-secrets-manager-core` をインストールします。ターミナルで `which python3` の結果がRoyal TSXの選択と一致する場合は、同じ `python3` で問題ありません。

```bash
python3 -m pip install keeper-secrets-manager-core
```

確認用:

```bash
python3 -c "import keeper_secrets_manager_core; print('ok')"
```

{% hint style="warning" %}
**Homebrew**のPythonで **`externally-managed-environment`** が出る場合は、実際のPythonパスで以下のようにインストールします。

```bash
/opt/homebrew/bin/python3 -m pip install keeper-secrets-manager-core --break-system-packages
```

または**仮想環境**を用意し、Royal TSXがそのPythonを指せる構成にします。
{% endhint %}

#### 3. ディスク上にKSM構成ファイルを置く <a href="#id-3-add-a-ksm-configuration-file-on-disk-1" id="id-3-add-a-ksm-configuration-file-on-disk-1"></a>

構成ファイルの取得方法は**2通り**あります。**いずれか一方**だけ使います。

* **オプションA — ボルトの構成ファイル (JSONまたはBase64)** — **ボルト** → **\[シークレットマネージャー]** → **\[デバイスを追加]** → **\[構成ファイル]** → **\[ダウンロード]**。(macOSではJSONを推奨します。)
* **オプションB — Keeper CLIのINIファイル** — トークン取得後に `ksm init default --token YOUR_TOKEN` を実行します ([クイックスタートガイド](https://docs.keeper.io/jp/keeperpam/secrets-manager/quick-start-guide))。`keeper.ini` などの `.ini` が生成されます。

#### 4. Royalドキュメントの新規作成または開く <a href="#id-4-create-or-open-a-royal-document-1" id="id-4-create-or-open-a-royal-document-1"></a>

**\[ファイル]** → **\[新規ドキュメント]** → **\[ファイル]** → **\[保存]**。

#### 5. ダイナミックフォルダのインポート <a href="#id-5-import-the-dynamic-folder-1" id="id-5-import-the-dynamic-folder-1"></a>

**\[ファイル]** → **\[インポート]** → **\[ダイナミックフォルダ]** → **`Keeper KSM (Python)`** → **\[インポート]**。

<figure><img src="https://859776093-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPL6k1aGsLiFiiJ3Y7zCl%2Fuploads%2Fgit-blob-a64cdc423e42c13e5400092afa47010ce2201e6e%2FScreenshot%202026-04-09%20at%206.02.37%E2%80%AFPM.png?alt=media" alt=""><figcaption></figcaption></figure>

#### 6. カスタムプロパティの設定 <a href="#id-6-set-custom-properties-1" id="id-6-set-custom-properties-1"></a>

**Keeper Secrets Manager (Python)** を右クリック → **\[プロパティ]** → **\[カスタムプロパティ]**。

* **KSM Config Path (macOS)** — **1つ**のファイルのフルパス: **`.json`**、**`.base64`**、または **`.ini`**。例: `/Users/yourname/keeper-config.json` または `/Users/yourname/keeper.ini`。

<figure><img src="https://859776093-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPL6k1aGsLiFiiJ3Y7zCl%2Fuploads%2Fgit-blob-031daca3e0a7943a72a50075d9e2f8f40f67af8a%2FScreenshot%202026-03-30%20at%204.16.48%E2%80%AFPM.png?alt=media" alt=""><figcaption></figcaption></figure>

**データベースクライアントのパス (データベースレコードを使う場合のみ):** 各パスは**このMac上**のクライアントツールです。データベースの**ホスト**と**ポート**は各**Keeperデータベース**レコードで定義し、カスタムプロパティには含めません。**実際に使うエンジンの行だけ**設定します。

| カスタムプロパティ               | 例                                            |
| ----------------------- | -------------------------------------------- |
| MySQL Path (macOS)      | `/opt/homebrew/opt/mysql-client/bin/mysql`   |
| PostgreSQL Path (macOS) | `/opt/homebrew/opt/libpq/bin/psql`           |
| MSSQL Path (macOS)      | `/opt/homebrew/opt/mssql-tools18/bin/sqlcmd` |
| Oracle Path (macOS)     | `/usr/local/bin/sqlplus`                     |
| MongoDB Path (macOS)    | `/opt/homebrew/bin/mongosh`                  |
| Redis Path (macOS)      | `/opt/homebrew/bin/redis-cli`                |

#### 7. フォルダの再読み込み <a href="#id-7-reload-the-folder-1" id="id-7-reload-the-folder-1"></a>

ダイナミックフォルダを右クリック → **\[再読み込み]** (または **Cmd+R**)。

#### 任意: データベースクライアントのインストール (macOS) <a href="#optional-install-database-clients-macos" id="optional-install-database-clients-macos"></a>

Royalがデータベースクライアントを起動できるよう、**お使いのMac上**にインストールします。接続先は各Keeperレコードの**ホスト**に従い、**ローカルまたはリモート**のデータベースになります。多くのユーザーは [Homebrew](https://brew.sh/)でCLIをインストールします。例:

```bash
brew install mysql-client libpq mongosh redis
brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew install mssql-tools18
```

Oracle Instant Clientのパスはインストール方法に依存します。

***

### サーバーレコードの利用 (SSH、SFTP、RDP) <a href="#use-server-records-ssh-sftp-rdp" id="use-server-records-ssh-sftp-rdp"></a>

**サーバー**レコードには、ホスト、ポート、ログイン、パスワードが含まれます。Royalで接続オブジェクト (ターミナル、ファイル転送、リモートデスクトップ) を作成し、そのレコードに対応する動的認証情報に**紐付け**ます。

SSHでは、ダイナミックフォルダが公開する**サーバー**認証情報グループから認証情報を選びます (SSH鍵のみの項目は、運用ガイドに別記がない限り使わないでください)。

#### 例: SSH <a href="#example-ssh" id="example-ssh"></a>

**Keeper — サーバーレコード**

| 項目    | 例                |
| ----- | ---------------- |
| タイトル  | `Production web` |
| ログイン  | `deploy`         |
| パスワード | *(ボルト内)*         |
| ホスト   | `203.0.113.10`   |
| ポート   | `22`             |

**Royal TS / Royal TSX**

1. ダイナミックフォルダを再読み込みします。
2. **\[追加]** → **\[ターミナル]** を選択します。
3. **接続の種類**を**SSH接続**にし、**コンピューター名**に `203.0.113.10`、**ポート**に `22` を設定します。
4. **\[認証情報]** で**認証情報名を指定**を選び、一致する**Keeper**の動的認証情報を選択します。
5. 保存して接続します。

#### 例: SFTP <a href="#example-sftp" id="example-sftp"></a>

SSHと同じ**サーバー**レコード構造を使います。**ファイル転送**プラグイン (**\[設定]** → **\[プラグイン]**) をインストールします。**\[追加]** → **\[ファイル転送]** → **SFTP** でホストとポートを設定し、同様の動的認証情報を付けます。

#### 例: RDP <a href="#example-rdp" id="example-rdp"></a>

**Keeper — サーバーレコード**

| 項目    | 例                     |
| ----- | --------------------- |
| タイトル  | `Finance workstation` |
| ログイン  | `CORP\jdoe`           |
| パスワード | *(ボルト内)*              |
| ホスト   | `192.168.50.100`      |
| ポート   | `3389`                |

**リモートデスクトップ**プラグインをインストールします。**\[追加]** → **\[リモートデスクトップ]** でホストとポートを入力し、認証情報を付けます。

{% hint style="warning" %}
接続先のWindowsエディションは、受信リモートデスクトップを許可する必要があります (**Pro**、**Enterprise**、**Education**、または **Windows Server**)。**Windows 11/10 Home** にはRDPサーバー機能がありません。
{% endhint %}

***

### データベースレコードの利用 <a href="#use-database-records" id="use-database-records"></a>

**データベース**レコードは、ダイナミックフォルダ内の**databaseCredentials**配下に**自動**で接続エントリを生成します。データベースCLIのパスを設定して再読み込みしたら、エンジン用のサブフォルダ (例: **MySQL Connections**) を開き、エントリを**ダブルクリック**します。Royalは**ワークステーション上**のクライアントを起動し、そのクライアントがKeeperレコードに保存された**ホストとポート**へ接続します (同一マシンでも**リモート**でも可。VPNやファイアウォールなど、ネットワーク経路で到達できる必要があります)。

#### Keeperでデータベース種別を設定する <a href="#set-the-database-type-in-keeper" id="set-the-database-type-in-keeper"></a>

ボルトで**データベース**レコードを作成または編集するとき、**種別**フィールドを設定します (標準のKeeper**データベース**テンプレートでは、エンジン識別に使われるフィールドです)。連携はその値を読み取り、対応するフォルダ (**MySQL Connections**、**PostgreSQL Connections** など) にレコードを配置します。

**種別**には以下の文字列のいずれかを使います (大文字小文字は無視)。よく使う別名も受け付けます。

| 使いたいDB               | 有効な**種別**の例                                   |
| -------------------- | --------------------------------------------- |
| MySQL                | `MySQL`, `MariaDB`                            |
| PostgreSQL           | `PostgreSQL`, `Postgres`, `PG`                |
| Microsoft SQL Server | `MSSQL`, `SQL Server`, `Microsoft SQL Server` |
| Oracle               | `Oracle`, `OracleDB`                          |
| MongoDB              | `MongoDB`, `Mongo`                            |
| Redis                | `Redis`                                       |

{% hint style="warning" %}
**種別**が**空**、または対応値に**一致しない**場合、連携はレコードを**MySQL**として扱います。MySQL以外では**種別**を必ず明示してください。
{% endhint %}

各例は同じ**Keeperデータベース**レコード構造を使います。**ホスト**と**ポート**は、データベースが待ち受ける場所 (ローカルまたはリモート) に合わせます。**カスタムプロパティ**に該当クライアントのパスを入れたうえでダイナミックフォルダを**再読み込み**し、**databaseCredentials** → そのエンジンのフォルダ (例: **MySQL Connections**、**PostgreSQL Connections**) を開きます。**Windows**では多くの場合、データベースクライアントが**外部アプリケーション**経由で起動します。**macOS**では**ヘルパースクリプト**がターミナルセッションでクライアントを実行します。

#### 例: MySQL <a href="#example-mysql" id="example-mysql"></a>

| 項目     | 例               |
| ------ | --------------- |
| レコード種別 | Database        |
| 種別     | MySQL           |
| タイトル   | `Staging MySQL` |
| ログイン   | `appuser`       |
| パスワード  | *(ボルト内)*        |
| ホスト    | `127.0.0.1`     |
| ポート    | `3306`          |

OSに合わせて**MySQL Path**をカスタムプロパティに設定し、ダイナミックフォルダを再読み込みしてから**databaseCredentials** → **MySQL Connections**を開きます。

#### 例: PostgreSQL <a href="#example-postgresql" id="example-postgresql"></a>

| 項目     | 例                        |
| ------ | ------------------------ |
| レコード種別 | Database                 |
| 種別     | PostgreSQL               |
| タイトル   | `Staging Postgres`       |
| ログイン   | `postgres` *(またはDBユーザー)* |
| パスワード  | *(ボルト内)*                 |
| ホスト    | `127.0.0.1`              |
| ポート    | `5432`                   |

OSに合わせて**PostgreSQL Path**をカスタムプロパティに設定し、ダイナミックフォルダを再読み込みしてから **databaseCredentials** → **PostgreSQL Connections**を開きます。**Windows**では**psql**が **`cmd /k`** 経由で実行され、コンソールが開いたままになります。

#### 例: Microsoft SQL Server <a href="#example-microsoft-sql-server" id="example-microsoft-sql-server"></a>

| 項目     | 例                                |
| ------ | -------------------------------- |
| レコード種別 | Database                         |
| 種別     | MSSQL                            |
| タイトル   | `Local SQL`                      |
| ログイン   | `sa` *(またはSQLログイン)*              |
| パスワード  | *(ボルト内)*                         |
| ホスト    | `127.0.0.1`                      |
| ポート    | `1433` *(または**TCPポート**。下記ヒント参照)* |

OSに合わせて**MSSQL Path**をカスタムプロパティに設定し、ダイナミックフォルダを再読み込みしてから **databaseCredentials** → **MSSQL Connections** を開きます。

{% hint style="info" %}
接続がタイムアウトする場合は **`localhost`** ではなく **`127.0.0.1`** を使います (IPv6解決の問題)。**SQL Express** は**既定以外のポート**を使うことが多いです。**SQL Server構成マネージャー** → **TCP/IP** → **IPAll**の**TCP Port**または**TCP Dynamic Port**を確認し、その値を**ポート**に入れます。現在の **`sqlcmd`** (ODBC Driver 18) は既定で暗号化します。本連携では **`-C -No`** を渡します (サーバー証明書を信頼し、暗号化は任意)。**SSMS** の**サーバー証明書を信頼**に近い挙動です。**SQLログイン**を使う場合、サーバーは**混合モード** (SQL + Windows認証) である必要があります。
{% endhint %}

#### 例: Oracle <a href="#example-oracle" id="example-oracle"></a>

| 項目     | 例                               |
| ------ | ------------------------------- |
| レコード種別 | Database                        |
| 種別     | Oracle                          |
| タイトル   | `Local XE`                      |
| ログイン   | `system` *(またはアプリユーザー)*         |
| パスワード  | *(ボルト内)*                        |
| ホスト    | `127.0.0.1` *(またはリモートリスナーのホスト)* |
| ポート    | `1521`                          |

カスタムプロパティの**Oracle Path**を **`sqlplus`** (またはインストール済みパス) に設定し、ダイナミックフォルダを再読み込みしてから **databaseCredentials** → **Oracle Connections**を開きます。連携は既定でEasy Connectの **`…/XEPDB1`** を使います (Oracle **21c XE** PDB)。別の **`SERVICE_NAME`** (**`XE`**、**`ORCL`** など) ではダイナミックフォルダスクリプトの編集が必要になる場合があります。**Windows**では**sqlplus**が **`cmd /k`** 経由で実行されます。

#### 例: MongoDB <a href="#example-mongodb" id="example-mongodb"></a>

| 項目     | 例                          |
| ------ | -------------------------- |
| レコード種別 | Database                   |
| 種別     | MongoDB                    |
| タイトル   | `Dev Mongo`                |
| ログイン   | *(認証なしの場合は空)* またはユーザー      |
| パスワード  | *(ボルト内)*、またはサーバーに認証がない場合は空 |
| ホスト    | `127.0.0.1`                |
| ポート    | `27017`                    |

カスタムプロパティの**MongoDB Path**を **`mongosh`** に設定し、ダイナミックフォルダを再読み込みしてから **databaseCredentials** → **MongoDB Connections**を開きます。**Windows**では**mongosh**が **`cmd /k`** 経由で実行されます。

#### 例: Redis <a href="#example-redis" id="example-redis"></a>

| 項目     | 例                          |
| ------ | -------------------------- |
| レコード種別 | Database                   |
| 種別     | Redis                      |
| タイトル   | `Local Memurai`            |
| ログイン   | *(認証なしの場合は空)* またはACLユーザー名  |
| パスワード  | *(認証なしの場合は空)* または *(ボルト内)* |
| ホスト    | `127.0.0.1`                |
| ポート    | `6379`                     |

カスタムプロパティの**Redis Path**を **`redis-cli.exe`** または **`memurai-cli.exe`** に設定し、ダイナミックフォルダを再読み込みします (**ログイン** / **パスワード** を変えた場合はスクリプトが認証を検出できるよう再読み込みしてください)。その後**databaseCredentials** → **Redis Connections**を開きます。**認証なし:** **ログイン**と**パスワード**を空にします。**requirepass:** **パスワード**のみ設定します。**ACL:** **ログイン**と**パスワード**を設定します。**Windows**ではクライアントが **`cmd /k`** 経由で実行されます。

***

### 機能のまとめ <a href="#feature-summary" id="feature-summary"></a>

| ワークフロー           | Windows (Royal TS) | macOS (Royal TSX) |
| ---------------- | ------------------ | ----------------- |
| SSH / SFTP / RDP | 手動の接続 + 動的認証情報     | 同様                |
| データベースCLI        | 接続の自動一覧、ダブルクリック    | 同様                |

***

### トラブルシューティング <a href="#troubleshooting" id="troubleshooting"></a>

#### Pythonとダイナミックフォルダ <a href="#python-and-the-dynamic-folder" id="python-and-the-dynamic-folder"></a>

| 表示・症状                                                               | 想定原因                                 | 対処                                                                                                                                                                              |
| ------------------------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`ImportError`** または `pip install keeper-secrets-manager-core` の促し | Royalが使うPythonと**異なる**環境にパッケージを入れている | Royalの設定にある**その** `python.exe` または `python3` でインストールします。確認: `python3 -c "import keeper_secrets_manager_core"` (macOS)、または **\[ファイル]** → **\[オプション]** → **\[プラグイン]** のWindowsパス。 |
| **`externally-managed-environment`** (macOS)                        | システムPythonへのPEP 668制限                | そのインタープリターで `--break-system-packages` を使うか、Royal TSXが使える**venv**を利用します。                                                                                                         |

#### KSM構成とボルトへのアクセス <a href="#ksm-configuration-and-vault-access" id="ksm-configuration-and-vault-access"></a>

| 表示・症状                                 | 想定原因                | 対処                                                                     |
| ------------------------------------- | ------------------- | ---------------------------------------------------------------------- |
| **KSM Config Path is not configured** | カスタムプロパティ未設定        | \*\*KSM Config Path (Windows)**または**KSM Config Path (macOS)\*\*を設定します。 |
| **Config file not found**             | パス誤りまたは権限           | ファイルパスと、ユーザーが読み取れることを確認します。                                            |
| **Record not found**                  | KSMアプリケーションにレコード未共有 | Keeperで、構成ファイルに紐付くシークレットマネージャーアプリケーションにレコードを共有します。                     |

#### データベースクライアント <a href="#database-clients" id="database-clients"></a>

| 表示・症状                                      | 想定原因                        | 対処                                                                                                                                              |
| ------------------------------------------ | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **No such file or directory**              | 実行ファイルのパスが未設定または誤り          | カスタムプロパティの**MySQL / PostgreSQL / … Path**を正しく設定し、再読み込みします。                                                                                      |
| **Connection refused**                     | サービス停止またはネットワーク             | Keeperレコードのホスト/ポートでデータベースが待ち受け、到達できることを確認します。                                                                                                   |
| **MSSQL login timeout / server not found** | ホスト/ポート誤りまたはTCP無効           | **`127.0.0.1`** を使います。**Express**では**TCP/IP**を有効にし、**ポート**を**構成マネージャー** → **TCP/IP** → **IPAll**の値に合わせます (多くの場合 **1433** ではありません)。              |
| **MSSQL certificate / SSL errors**         | ODBC 18 + 自己署名証明書           | 最新のダイナミックフォルダを再読み込み (**`-C -No`**)。手動の **`sqlcmd`**: **`-C -No`** を付与。**SSMS**: **オプション** → **サーバー証明書を信頼**。                                     |
| **MSSQL Login failed** (SQLユーザー)           | Windows認証のみ、またはログイン無効       | **SSMS** → サーバーの**プロパティ** → **セキュリティ**で**混合モード**を有効にし、SQL Serverを再起動します。ログインが存在し有効であることを確認します。                                                  |
| **Oracle**リスナーなし / タイムアウト                  | リスナーのホスト誤りまたはサービス停止         | **リスナー**に合う**ホスト**を使います (ローカルでは多くの場合 **`127.0.0.1`**)。**Oracle**のリスナーとDBサービスを起動します。LAN専用IPから変えた場合は **`LOCAL_LISTENER`** と**listener.ora**を揃えます。 |
| **Oracle** ORA-12514                       | サービス未登録                     | **SYSDBA** で **`ALTER SYSTEM REGISTER`** を実行します。**`lsnrctl status`** に **`xepdb1`** / **`XE`** が出ることを確認します。                                     |
| **Redis AUTH**エラー                          | サーバーにパスワードがないのにパスワードを設定している | Keeperレコードのパスワードをクリアします。                                                                                                                        |

#### macOSでのSSH (ローカル検証) <a href="#ssh-on-macos-local-testing" id="ssh-on-macos-local-testing"></a>

| 表示・症状                                        | 想定原因       | 対処                                                                            |
| -------------------------------------------- | ---------- | ----------------------------------------------------------------------------- |
| **Connection closed** または**このMac**への繰り返し認証失敗 | リモートログイン制限 | **システム設定** → **共有** → **リモートログイン** → **オプション** で、ユーザーを許可するか**すべてのユーザー**を選びます。 |

#### リモートデスクトップ <a href="#remote-desktop" id="remote-desktop"></a>

| 表示・症状                     | 想定原因      | 対処                                          |
| ------------------------- | --------- | ------------------------------------------- |
| **Home**エディションのPCへRDPできない | RDPサーバーなし | **Pro**以上、**Windows Server**、または別の接続先を使います。 |

***

### セキュリティとコンプライアンス <a href="#security-and-compliance" id="security-and-compliance"></a>

* シークレットは**Keeper**の管理下に残り、解決された動的認証情報がRoyalドキュメントに保存されたパスワードとして書き込まれることはありません。
* **KSM構成ファイル**は、ボルトへのアクセス権を持つシークレットと同様に保護します。組織の方針に従い、ファイル権限とデバイスのアクセスを制限します。

#### データベースのパスワードの渡し方 <a href="#how-database-passwords-are-passed" id="how-database-passwords-are-passed"></a>

**macOS**では、クライアントが対応する場合、パスワードをコマンドライン引数ではなく**環境変数**または**アクセス権を限定した一時ファイル**で渡すヘルパースクリプトを使います。

| クライアント               | 方法                                                  |
| -------------------- | --------------------------------------------------- |
| MySQL                | 環境変数 `MYSQL_PWD`                                    |
| PostgreSQL           | 環境変数 `PGPASSWORD`                                   |
| Microsoft SQL Server | 環境変数 `SQLCMDPASSWORD`                               |
| Oracle               | モード0600の一時SQLファイルで `sqlplus -L /nolog @file`、終了時に削除 |
| MongoDB              | 引数としてURIを渡す (`mongosh` には環境変数でのパスワード指定がない)          |
| Redis                | 環境変数 `REDISCLI_AUTH`                                |

**Windows**ではデータベース接続に**外部アプリケーション**とRoyalの認証情報トークン (`$$EffectivePassword$$`) を使います。Royalが起動時にコマンドラインへ値を展開します。以下の点に注意してください。

* 解決されたシークレットが**プロセス一覧**に見える場合があります。外部アプリケーション方式に内在する挙動です。
* パスワードに **`&`**、**`%`**、**`"`**、**`!`** が含まれると、コマンドライン解釈を壊し認証に失敗することがあります。該当する場合は、外部アプリケーション経由で起動するデータベース接続では、Keeperレコードのパスワードからこれらの文字を避けることを検討してください。

#### macOSヘルパーファイルの安全性 <a href="#macos-helper-file-safety" id="macos-helper-file-safety"></a>

* **`~/.config/royal-keeper/`** 以下のランチャーおよびヘルパースクリプトは、**原子的書き込み** (一時ファイル → chmod → 置換) で書き込み、ディレクトリ権限は**0700**に設定します。
* ランチャースクリプトに埋め込む引数はすべて **`shlex.quote()`** でエスケープし、パスに含まれる引用符やメタ文字からのシェルインジェクションを防ぎます。

#### Base64構成のクリーンアップ <a href="#base64-configuration-cleanup" id="base64-configuration-cleanup"></a>

* **`.base64`** のKSM構成ファイルを使う場合、デコード結果を**モード0600**の一時ファイルに書き、KSMセッションに使用し、スクリプト終了時に **`finally`** で**削除**します。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.keeper.io/jp/keeperpam/secrets-manager/integrations/royalts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.