# ServiceNow Credential Resolver
## 概要
Keeperボルトと管理・計装・検出 (MID) サーバーとの連携により、ServiceNowオーケストレーション、ServiceNow検出 (Discovery)、ServiceNowサービスマッピング (Service Mapping) が、インスタンス上に認証情報を保存することなく、Keeperボルトから動的に認証情報を取得できます。
インスタンスは各認証情報に一意の識別子を割り当て、認証情報の種類 (SSH、SNMP、Windowsなど) や関連付け (アフィニティ) を管理します。MID Serverはインスタンスから識別子、認証情報の種類、IPアドレスを取得し、Keeperボルトを使用してこれらを実際に利用可能な認証情報に変換します。
## 機能
* Keeperボルトに保存されたシークレットを、ServiceNowのオーケストレーション、検出 (Discovery)、サービスマッピングの認証情報として使用できます。
* 検出およびオーケストレーション向けの外部認証情報ストレージに対応
* カスタム認証情報プロバイダーとしての利用に対応
## ユースケース
### オンデマンド検出
1. トリガー: ServiceNowの管理者が、新規追加されたインフラに対する検出プロセスを開始する
2. アクション: ServiceNowがMIDサーバーに検出開始のリクエストを送る
3. MIDサーバー: Keeperボルトから必要な認証情報 (SSH、SNMPなど) を取得し、検出を実行する
4. 結果: 検出された資産がServiceNowの構成管理データベース (CMDB) に追加される
### インシデント対応
1. トリガー: ServiceNowでインシデントが起票され、特定サーバーへの即時対応が必要になる
2. アクション: ServiceNowがMIDサーバーを含むオーケストレーションワークフローを起動する
3. MIDサーバー: 影響を受けたサーバーにログインし、定義済みの修復手順を実行するために、Keeperボルトから必要な認証情報を取得する
4. 結果: インシデントが解消され、実施した操作がServiceNowに記録される
### カスタム認証情報プロバイダー
1. トリガー: ServiceNowと連携したカスタムアプリケーションが、動作に特定の認証情報を必要とする
2. アクション: アプリケーションがServiceNowに必要な認証情報を問い合わせる
3. MIDサーバー: リクエストを受け、Keeperボルトから認証情報を取得してカスタムアプリケーションに渡す
4. 結果: カスタムアプリケーションは、Keeperボルトから安全に取得した認証情報を用いて処理を続行できる
## 要件
* Keeperシークレットマネージャーへのアクセス (詳しくは[クイックスタートガイド](/keeperpam/jp/secrets-manager/quick-start-guide.md)をご参照ください)
* サブスクリプションでシークレットマネージャーアドオンが有効であること
* シークレットマネージャー強制ポリシーが有効なロールに所属していること
* シークレットが共有されたKeeper[シークレットマネージャーアプリケーション](/keeperpam/jp/secrets-manager/about/terminology.md#application)
* アプリケーションの作成手順は[クイックスタートガイド](https://docs.keeper.io/keeperpam/jp/secrets-manager/integrations/pages/-MeRAVfQmDBzKQBC0f_c#2.-create-an-application) をご参照ください
* [外部認証情報ストレージ](https://docs.servicenow.com/bundle/utah-platform-security/page/product/credentials/concept/external_cred_storage_configuration.html)プラグインが有効なServiceNowインスタンス
## セットアップ
### 1. 外部認証情報ストレージ (管理者ロールが必要)
* [外部認証情報ストレージ](https://docs.servicenow.com/bundle/utah-platform-security/page/product/credentials/task/t_ActivateExtrnlCredStoragePlugIn.html)プラグインがアクティブであること
* [外部認証情報ストレージを有効にする](https://docs.servicenow.com/bundle/utah-platform-security/page/product/credentials/concept/c_ExternalCredentialStorage.html)のDiscoveryプロパティが有効であること
#### システムプロパティ
`Enable External Credential Storage` `[com.snc.use_external_credentials]` というプロパティは、プラグインをアクティブ化したあとで外部認証情報ストレージプラグインの有効/無効を切り替えます。このプロパティは **\[Discovery Definition]** > **\[Properties and Orchestration]** > **\[MID Server Properties]** にあり、プラグインをアクティブ化するときに有効になります。
{% hint style="danger" %}
システムプロパティで外部認証情報ストレージを無効にすると、インスタンス上のすべての外部認証情報が自動的に **inactive**に設定されます。このプロパティで機能を再度有効にしても、外部認証情報レコードは自動では**active**には戻りません。各認証情報レコードを手動で再有効化する必要があります。
{% endhint %}
### 2. Keeper認証情報リゾルバーのインストール
* 最新のKeeper認証情報リゾルバーJARファイルをKSMのGitHubページからダウンロードします。
{% embed url="" %}
KeeperシークレットマネージャーのServiceNow向けリリース
{% endembed %}
* ServiceNowで **\[MID server - JAR files]** → **\[New]** に移動します
* **\[Manage Attachments]** → Keeper認証情報リゾルバーのJARをアップロード
* 名前やバージョンなど、必要に応じて入力
* **\[Submit]** をクリック
* **\[MID server - Properties]** → **\[New]** に移動します
* *Name*: `ext.cred.keeper.ksm_config`、*Value*: 対応するKSMアプリケーション用に生成した[構成](/keeperpam/jp/secrets-manager/about/secrets-manager-configuration.md#creating-a-secrets-manager-configuration)のBase64表現
* **任意:** プロパティ `ext.cred.keeper.ksm_label_prefix` を希望のプレフィックスに設定 (既定ではリゾルバーはラベルプレフィックスに `mid_` を使用)
* **任意:** プロパティ `ext.cred.keeper.use_ksm_cache` を `"true"` に設定してキャッシュを有効化 (10秒あたり数千件以上のリクエストが想定される場合に使用)
* **代替として**、`config.xml` を直接編集します (既定では `/opt/servicenow/mid/agent/` にあります)。キーを追加してサーバーを再起動します (ラベルプレフィックスの設定は任意。下記は既定のプレフィックスです)
```
```
機密パラメータにはすべて secure="true" オプションを使い、値を暗号化するためにサーバーの再起動を忘れないようにしてください。
詳しくは、GitHubの[KeeperシークレットマネージャーServiceNow連携ソース](https://github.com/Keeper-Security/secrets-manager/tree/master/integration/servicenow-external-credential-resolver)をご参照ください。
### 3. 検出用認証情報の構成
MIDサーバーからKeeperボルトの認証情報を利用するには、次が必要です。
* Keeperボルトにシークレットを作成し、対応するKSMアプリケーションに共有する
* リゾルバーがそのシークレットを使うよう構成する
### Keeperボルトでのシークレット作成とフィールドの対応付け
Keeperのレコードタイプはカスタマイズしやすく、ServiceNowの認証情報種別に1対1で対応する特定のレコードタイプはありません。
Keeper外部認証情報リゾルバーは、カスタムフィールドラベルを使ってレコードデータをMIDサーバーのテーブル列 (`discovery_credential` テーブル) に対応付けます。所定の認証情報種別についてテーブル列と一致するよう、必要なカスタムフィールドすべてにラベルを付け、そのラベルに `mid_` プレフィックスを付けます (カスタムプレフィックスの設定方法は下記を参照)
ユーザー名/パスワードが必要な認証情報には、ログイン情報のレコードを使い、認証情報種別で求められる追加のカスタムフィールドを足します (例: type=hidden, label="mid\_pkey")
ユーザー名/パスワードがないその他のタイプには、標準フィールドを持たないファイル、あるいは写真タイプのレコードを使うと、カスタムフィールドの取り扱いが容易です。
カスタムフィールドラベルのプレフィックスを変えるには、MIDサーバーの `config.xml` を次のパラメータで更新し、MIDサーバーを再起動します。
```
```
* Keeperボルトでの表示設定に応じて、 `text`、`multiline`、`hidden` のカスタムフィールドを使用できます。
* ログイン情報タイプを使う場合、ユーザー名/パスワード用のカスタムフィールドは**無視されます** (たとえ `mid_user`、`mid_pswd` と正しくラベル付けされていても)。これらの値は常にログイン情報レコード種別の標準フィールド (ログイン名/パスワード) から取得されます。
* 「**External credential store**」オプションを使用する場合、resolveメソッドで返されるマップキーは、 `snc-automation-api.jar` の**IExternalCredential**インターフェースに準拠する必要があります (値は`VAL_` プレフィックスで始まります)。
* 現在のバージョン (Utah) でサポートされているキーは次のとおりです。\
`user`、`pswd`、`passphrase`、`pkey`、`authprotocol`、`authkey`、`privprotocol`、`privkey`、`secret_key`、`client_id`、`tenant_id`、`email`
これらに対応するフィールドラベルは、Keeperレコード内で `mid_` プレフィックスを付ける必要があります。これにより、正しく抽出およびマッピングされます。
* カスタム外部認証情報リゾルバーとして使う場合、Keeperボルトで**正しくプレフィックスが付けられ**、かつ対応する認証情報種別に存在するカスタムフィールドならマッピングできます。resolveメソッドが返す認証情報マップのキーは、**discovery\_credential** テーブルの列名と一致していることが期待されます (例: `sn_cfg_ansible`, `sn_disco_certmgmt_certificate_ca`, `cfg_chef_credentials` など)
#### **例**
* 認証情報種別 `jdbc`\
Keeperのレコード種別 `Login` に対応 (標準のログイン名/パスワードフィールドを使用。追加設定は不要)
* 認証情報種別 `api_key`\
Keeperのレコード種別 `Login` に対応し、ラベル `mid_ssh_private_key` および `mid_ssh_passphrase` (任意) の `hidden` カスタムフィールドを手動で追加
* 認証情報種別 `gcp`\
Keeperのレコード種別 `File Attachment/Photo` に対応し、必要なカスタムフィールド `mid_email` (text)、`mid_secret_key` (hidden) を手動で追加
### Keeperボルトでの認証情報の検索
有効なレコードUID (英数字22文字で「-」および「\_」を含む )、または `type:title` の形式である必要があります。
`type:title` 形式では、レコードタイプ、タイトル、またはその両方で検索できます (ただし「:」が1つのみの場合は無効な組み合わせとなります)。
`type:title` 形式を使用する場合は、一致するレコードが1つのみであることを確認してください。複数のレコードが一致するとエラーになります。
単一のレコードに確実に一致させるためには、レコードUIDの使用を推奨します。また、`type:title` による検索では、リクエストごとにすべてのレコードをダウンロードしてローカル検索を行う必要があるため (Keeperボルトのゼロ知識アーキテクチャにより検索はローカルで実行されます)、その回避にも有効です。
#### **例**
一致するレコードが0件、または2件以上の場合はエラーになります。
* レコードUIDで検索\
認証情報ID: `ABCDABCDABCDABCDABCDAB`
* 種別とタイトルで検索\
認証情報ID: `login:MyLogin`
* タイトルで検索\
認証情報ID: `:MyLogin`
* 種別で検索\
認証情報ID: `login:`
#### リゾルバーでシークレットを使う設定
ServiceNowのUIで次を行います。
* **\[Discovery - Credentials]** に移動し、**\[New]** を選択します。
* リストから認証情報のタイプを選択します。
* **\[External credential store]** チェックボックスをオンにします。ユーザー名およびパスワードのフィールドが非表示になり、**\[Credential ID]** フィールドと認証情報ストレージボルトのメニューが表示されます。
* わかりやすい名前を入力します。
* **\[Credential ID]** には、シークレットのレコードUIDを設定するか、`type:title` または `:title` の形式で検索文字列を指定し、単一のレコードに解決されることを確認します
* 認証情報ストレージボルトのメニューから、**\[None]**、Keeperボルト、またはカスタム外部認証情報ストレージボルトを選択できます。
1. カスタム外部認証情報ストレージボルトを使用する場合は、インスタンス内のVault Configurations **\[vault\_configuration.list]** に移動します。
2. カスタム認証情報リゾルバー用にインポートしたJARファイルに対応する名前で、新しいレコードを作成します。
* **任意:** **\[Test credential]** をクリックし、MID Serverとテスト対象を選択して動作を確認します。
### リクエストのキャッシュとスロットル
一定時間内にKeeperへ過剰なリクエストが送信された場合、スロットリングエラーが返されます。プラグインは既定で、この「スロットリング」エラーに対してランダムな遅延を挿入し、後で再試行することで対応します。この方法は、10秒あたり1000～3000リクエスト程度まで有効です (スロットリングは10秒あたり300～600リクエストで発生し始めます)。
10秒未満で5000件以上のリクエストが発生する場合は、キャッシュの有効化を推奨します。`config.xml` でパラメータ `ext.cred.keeper.use_ksm_cache` を「true」に設定し、MID Serverを再起動してください。
キャッシュデータは、MID Serverのworkフォルダ内にある暗号化ファイル `ksm_cache.dat` に保存されます。キャッシュは最大5分ごと、または次回リクエスト時に更新されます。
### トラブルシューティング
#### ログの確認
ログやエラーは、エージェントのインストールフォルダ内の `logs/` ディレクトリにあるログファイルをご確認ください。リゾルバーは、正常にクエリされた各Credential IDについてログを出力し、認証情報がどのフィールドから抽出されたかも記録します。
特定のCredential IDで問題が発生している場合は、ログ内でそのIDを検索し、正常にクエリされているか、また想定どおりのフィールドから認証情報が抽出されているかを確認してください。
また、レコードの特定やフィールドの取得に関するエラー、Keeperボルトとの通信に失敗した場合など、リゾルバーで発生した例外もログに記録されます。
#### 認証情報テスト機能の利用
ServiceNowのUIで認証情報を作成または設定する際、**\[Test credential]** をクリックして簡易テストを実行できます。Keeperボルトに対してクエリを実行するMID Serverを選択し、認証情報が有効であることを確認する対象を指定してください。
期待どおりに動作しない場合は、上記の手順に従ってログを確認し、エラーやデバッグ情報を確認してください。
---
# 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/keeperpam/jp/secrets-manager/integrations/servicenow.md?ask=
```
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.