ServiceNow Credential Resolver

Keeperボルトと連携するServiceNow向け認証情報リゾルバー

概要

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シークレットマネージャーへのアクセス (詳しくはクイックスタートガイドをご参照ください)

  • サブスクリプションでシークレットマネージャーアドオンが有効であること
  • シークレットマネージャー強制ポリシーが有効なロールに所属していること
• シークレットが共有されたKeeperシークレットマネージャーアプリケーション

  • アプリケーションの作成手順はクイックスタートガイド をご参照ください
• 外部認証情報ストレージプラグインが有効なServiceNowインスタンス

セットアップ

1. 外部認証情報ストレージ (管理者ロールが必要)

• 外部認証情報ストレージプラグインがアクティブであること
• 外部認証情報ストレージを有効にするのDiscoveryプロパティが有効であること

システムプロパティ

Enable External Credential Storage [com.snc.use_external_credentials] というプロパティは、プラグインをアクティブ化したあとで外部認証情報ストレージプラグインの有効/無効を切り替えます。このプロパティは [Discovery Definition] > [Properties and Orchestration] > [MID Server Properties] にあり、プラグインをアクティブ化するときに有効になります。

システムプロパティで外部認証情報ストレージを無効にすると、インスタンス上のすべての外部認証情報が自動的に inactiveに設定されます。このプロパティで機能を再度有効にしても、外部認証情報レコードは自動ではactiveには戻りません。各認証情報レコードを手動で再有効化する必要があります。

2. Keeper認証情報リゾルバーのインストール

• お使いのServiceNowリリース向けのKeeper認証情報リゾルバーJARを、KSMのGitHubページからダウンロードします。各リリースでは、対応するServiceNowバージョンごとに1つのJARが公開され、keeper-external-credentials-<servicenow-release>-<version>.jar という名前になります。

servicenow-integration · Releases · Keeper-Security/secrets-managerGitHub

KeeperシークレットマネージャーのServiceNow向けリリース

以下の互換表をご参照ください。

ServiceNowリリース	MID ServerのJRE	構成するリゾルバークラス
Utah	JRE 11	com.snc.discovery.CredentialResolver
Vancouver	JRE 11	com.snc.discovery.CredentialResolver
Washington DC	JRE 17	com.snc.discovery.CredentialResolver
Xanadu	JRE 17	com.snc.discovery.CredentialResolver
Yokohama (Patch 7+)	JRE 17	com.keepersecurity.secretsManager.CredentialResolver (FQCN)
Zurich	JRE 17	com.keepersecurity.secretsManager.CredentialResolver (FQCN)
Australia	JRE 17	com.keepersecurity.secretsManager.CredentialResolver (FQCN)

Yokohama (Patch 7+) 以降では、ServiceNowの外部認証情報リゾルバー構成で、完全修飾クラス名 (FQCN) を com.keepersecurity.secretsManager.CredentialResolver に設定します。FQCN版JARにはKeeper独自のクラスのみが含まれるため、同一のMID Server上で他ベンダーのリゾルバー (CyberArk、HashiCorp、Delineaなど) と共存できます。一方、すべてのリゾルバーJARが共有クラス名 com.snc.discovery.CredentialResolver を使う構成では共存できません。Xanadu以前向けには、共有クラスの legacy JARバリアントのみがあります。

• ServiceNowで [MID server - JAR files] → [New] に移動します

  • [Manage Attachments] → Keeper認証情報リゾルバーのJARをアップロード
  • 名前やバージョンなど、必要に応じて入力
  • [Submit] をクリック
• [MID server - Properties] → [New] に移動します

  • Name: ext.cred.keeper.ksm_config、Value: 対応するKSMアプリケーション用に生成した構成のBase64表現
  • 任意: プロパティ ext.cred.keeper.ksm_label_prefix を希望のプレフィックスに設定 (既定ではリゾルバーはラベルプレフィックスに mid_ を使用)
  • 任意: プロパティ ext.cred.keeper.use_ksm_cache を "true" に設定してキャッシュを有効化 (10秒あたり数千件以上のリクエストが想定される場合に使用)
  • 代替として、config.xml を直接編集します (既定では /opt/servicenow/mid/agent/ にあります)。キーを追加してサーバーを再起動します (ラベルプレフィックスの設定は任意。下記は既定のプレフィックスです)

<parameter name="ext.cred.keeper.ksm_config" secure="true" value="[KSM_CONFIG_BASE64_STRING]"/>
<!-- optional -->
<parameter name="ext.cred.keeper.ksm_label_prefix" value="mid_"/>
<!-- optional -->
<parameter name="ext.cred.keeper.use_ksm_cache" value="true"/>

機密パラメータにはすべて secure="true" オプションを使い、値を暗号化するためにサーバーの再起動を忘れないようにしてください。

詳しくは、GitHubのKeeperシークレットマネージャーServiceNow連携ソースをご参照ください。

3. 検出用認証情報の構成

MIDサーバーからKeeperボルトの認証情報を利用するには、次が必要です。

• Keeperボルトにシークレットを作成し、対応するKSMアプリケーションに共有する
• リゾルバーがそのシークレットを使うよう構成する

Keeperボルトでのシークレット作成とフィールドの対応付け

Keeperのレコードタイプはカスタマイズしやすく、ServiceNowの認証情報種別に1対1で対応する特定のレコードタイプはありません。

Keeper外部認証情報リゾルバーは、カスタムフィールドラベルを使ってレコードデータをMIDサーバーのテーブル列 (discovery_credential テーブル) に対応付けます。所定の認証情報種別についてテーブル列と一致するよう、必要なカスタムフィールドすべてにラベルを付け、そのラベルに mid_ プレフィックスを付けます (カスタムプレフィックスの設定方法は下記を参照)

ユーザー名/パスワードが必要な認証情報には、LoginまたはPAM User (pamUser) タイプのレコードを使い、認証情報種別で求められるカスタムフィールドを追加します (例: type=hidden, label="mid_pkey")

ユーザー名/パスワードを持たないその他の種別では、標準フィールドのないFile Attachment/Photoレコードを使うと、カスタムフィールドを扱いやすくなります。

カスタムフィールドラベルのプレフィックスを変えるには、MIDサーバーの config.xml を次のパラメータで更新し、MIDサーバーを再起動します。

<parameter name="ext.cred.keeper.ksm_label_prefix" value="mid_"/>

• Keeperボルトでの表示設定に応じて、 text、multiline、hidden のカスタムフィールドを使用できます。
• LoginまたはPAM User (pamUser) レコードタイプを使う場合、ユーザー名/パスワード用のカスタムフィールドは無視されます (mid_user、mid_pswd と正しくラベル付けされていても同様です)。これらの値は常にレコード標準のLogin/Passwordフィールドから取得されます。
• 「External credential store」オプションを使用する場合、resolveメソッドで返されるマップキーは、snc-automation-api.jar のIExternalCredentialインターフェースに準拠する必要があります (値は VAL_ プレフィックスで始まります)。

  • 現在のバージョン (Utah) で利用できるキーは、user、pswd、passphrase、pkey、sshcert、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分ごと、または次回リクエスト時に更新されます。

キャッシュを有効にした場合や、type:title 形式の認証情報IDを使った場合、リゾルバーは対象レコードだけでなく、Keeperシークレットマネージャーアプリケーションに共有されたすべてのレコードを取得します。取得量を抑えるには、レコードUIDの認証情報IDを優先してください。UIDによる検索はサーバー側で絞り込まれます。同一アプリケーションにPAMなど他のレコードタイプが共有されていても動作します。リゾルバー1.0.0以降では、解析できないレコードをスキップするため、バッチ全体が失敗することはありません。

診断とエラーメッセージ

リゾルバーはフィールドラベルを検査し、構成ミスのあるレコードを修正できるよう問題をログに記録します。これらの検査は情報用途のみで、agent.log への書き込みにとどまり、例外を発生させたり、正常に解決できる認証情報の処理を止めたりすることはありません。

• mid_ プレフィックス付きのカスタムフィールドで、サフィックスが認識済みのキー名でない場合でも値はそのまま渡されます (discovery_credential の任意の列を意図的に許可しています) が、警告が記録されます。これは、インターフェースのキー名 (mid_privkey、mid_pswd) ではなく、ServiceNowのフォーム名や列名をラベルにコピーしてしまう誤り (例: mid_private_key や mid_password) を検出するためです。サフィックスが認識済みの名前に近い誤字の場合は、「もしかして…?」の候補が追加されます (例: mid_authykey → mid_authkey)。
• ラベルが認識済みのキー名と完全一致しているものの、プレフィックスがないカスタムフィールド (例: mid_authkey ではなく authkey) は無視され、名前の変更を促す警告が記録されます。Login/PAM Userレコードでは、プレフィックスのない user/pswd ラベルについて、標準のLogin/Passwordフィールドから取得される旨が記録されます。
• 検索のたびに1回、プレフィックスなしの認識済みキー名がログに記録されます (プレフィックスは構成可能なため、一度だけ出力されます)。
• フィールドラベルは大文字小文字を区別します (mid_authkey であり、mid_AuthKey ではありません)。

認証情報IDに一致するレコードがない場合や複数ある場合、あるいは一致したレコードから利用可能な値が得られない場合は、理由が有効なラベルとともにログに記録されます。リゾルバーは処理を止めず、解決できた内容を返します。トラブルシューティングには agent.log をご確認ください。

トラブルシューティング

ログの確認

ログやエラーは、エージェントのインストールフォルダ内の logs/ ディレクトリにあるログファイルをご確認ください。リゾルバーは、正常にクエリされた各Credential IDについてログを出力し、認証情報がどのフィールドから抽出されたかも記録します。

特定のCredential IDで問題が発生している場合は、ログ内でそのIDを検索し、正常にクエリされているか、また想定どおりのフィールドから認証情報が抽出されているかを確認してください。

また、レコードの特定やフィールドの取得に関するエラー、Keeperボルトとの通信に失敗した場合など、リゾルバーで発生した例外もログに記録されます。

Serializer for subclass 'pamSettings' is not found (および類似のポリモーフィックエラー)

MID Serverのログにこのエラーが出る場合、デプロイ済みのリゾルバーJARに同梱されているKeeperシークレットマネージャーSDKが古く、同一アプリケーションに共有されている新しいフィールドやレコードタイプ (PAMレコードなど) に対応していないことを意味します。現行のKSM SDKを同梱したリゾルバーJAR1.0.0以降にアップグレードしてください。この版では解析できないレコードをスキップするため、バッチ全体が失敗しません。暫定的な回避策としては、アプリケーションの共有フォルダからPAMレコードを削除し、キャッシュを無効にしたうえで、レコードUIDの認証情報IDを使用します。

認証情報テスト機能の利用

ServiceNowのUIで認証情報を作成または設定する際、[Test credential] をクリックして簡易テストを実行できます。Keeperボルトに対してクエリを実行するMID Serverを選択し、認証情報が有効であることを確認する対象を指定してください。

期待どおりに動作しない場合は、上記の手順に従ってログを確認し、エラーやデバッグ情報を確認してください。