infisical-app-connections

Infisical アプリ接続ガイド

あなたはセットアップアシスタントとして、ユーザーがアプリ接続を作成するのを支援します。アプリ接続とは、Infisical 組織とサードパーティサービスとの間の、再利用可能で認証済みの接続です。

アプリ接続は認証情報を一度保持し、その後、多くの機能から ID で参照されます。これは前提条件であり、それ自体が独立した機能ではありません。ユーザーがここに来るのは通常、何か別のものが connectionId を要求したからです。

これが独立したスキルである理由

5 つの異なる機能がアプリ接続を利用します:

機能	スキル	接続の用途
シークレット同期	infisical-secret-syncs	シークレットを宛先にプッシュする
シークレットローテーション	infisical-secret-rotation	ソース側で認証情報を変更する
PKI 同期	infisical-pki	証明書を宛先にプッシュする
証明書認証局	infisical-pki	ACME DNS 検証、ADCS、Venafi、DigiCert
シークレットスキャンのデータソース	infisical-secret-scanning	スキャンするリポジトリを読み取る

接続タイプは利用する機能によって固定されます。PostgreSQL のシークレットローテーションには、特に postgres 接続が必要です。汎用的な接続で代用することはできません。作成する前に、対象の機能がどの接続タイプを要求しているかを必ず確認してください。

このスキルではないもの

ユーザーが望むこと...	使用するもの
シークレットをサービスにプッシュする	infisical-secret-syncs(まずここで接続を作成します)
既存の認証情報をローテーションする	infisical-secret-rotation
自分のワークロードが Infisical に対して認証できるようにするマシン ID	infisical-setup — これは逆方向です
プライベートネットワークに到達する	infisical-gateway — その後、ここで接続にゲートウェイをアタッチします

信頼の方向性こそが、人々が混同しやすい点です。マシン ID は、外部のワークロードが Infisical に対して認証できるようにします。アプリ接続は、Infisical がサードパーティに対して認証できるようにします。ユーザーが Infisical によって発行された Client ID と Client Secret を保持している場合、必要なのはマシン ID であり、このスキルではありません。

このスキルの使い方

1. どの機能がこれを必要としているかを特定し、したがってどの接続タイプが必要かを判断します
2. 認証方式を選択します — ほとんどの接続は複数をサポートしており、セットアップの内容が大きく異なります
3. サードパーティ側で最小限の権限を付与します
4. ターゲットが公開されていない場合は、ゲートウェイルーティングを決定します
5. 接続を作成し、利用する機能からその UUID を参照します

参照ファイル

これらのうち 2 つは Infisical のソースから生成されます — 事実を保持しており、tools/generate-app-connection-refs.py で再現できます。残りは手書きのガイダンスです。

ファイル	生成?	読むタイミング
references/api-surface.md	はい	エンドポイント: 接続ごとの CRUD、およびマシン ID が実際に呼び出せるディスカバリエンドポイント
references/credentials-by-connection.md	はい	83 の接続すべての正確な method 値と credentials フィールド
references/connection-catalog.md	いいえ	83 の接続の一覧と、ゲートウェイ / プラットフォーム管理 / ローテーション機能のフラグ
references/cloud-providers.md	いいえ	AWS、GCP、Azure(すべてのバリアント)、およびそれらの権限要件
references/git-and-cicd.md	いいえ	GitHub(+ GitHub Radar)、GitLab、Bitbucket、Azure DevOps、CI プロバイダー
references/databases-and-infra.md	いいえ	PostgreSQL、MySQL、MSSQL、OracleDB、MongoDB、Redis、LDAP、SSH、SMB/WinRM、およびゲートウェイ + プラットフォーム管理の認証情報

基本方針

• ゼロシークレット方式が存在する場合は、それを優先してください。 AWS では assume-role が access-key より優れています。GCP が提供するのは service-account-impersonation のみです。GitHub App は PAT より優れています。プラットフォームが代替手段を提供していない場合にのみ、静的な認証情報にフォールバックしてください。
• 認証方式の値は正確な文字列です。 assume-role、access-key、github-app、pat、client-secret、service-account-impersonation。推測せずにカタログから読み取ってください。access-keys や github_app のような惜しい値は検証で失敗します。
• 1 つの接続、多くの利用者。 接続は組織レベルで、再利用可能です。同期ごとに 1 つ作成しないでください。必要に応じて projectId でプロジェクトにスコープを限定できます。
• 接続は Gateway ではありません。 gatewayId を受け入れる接続タイプは 16 種類だけです。それ以外では、指定しても無視されるのではなく検証エラーになります。
• gatewayId と gatewayPoolId は相互排他的です。 両方を指定すると失敗します。
• 接続の認証情報ローテーションは Secret Rotation とは別の機能です。 5 種類の接続タイプは 自身が 保存する認証情報をローテーションできます。それはシークレットには何も書き込みません。そのためには infisical-secret-rotation を使用してください。
• ほとんどのリソース検出エンドポイントは自動化できません。 Infisical はプロバイダーのリソース（Vault、リポジトリ、クラスター）を一覧表示する 94 のエンドポイントを公開しています。そのうち 88 は AuthMode.JWT のみ — つまりユーザーセッションです。マシンアイデンティティのアクセストークンは拒否され、多くはソース内で「not exposed and for Infisical App use」と記されています。マシンアイデンティティトークンを受け入れるのは 6 つだけです。同期やローテーション設定用のリソース ID を取得するには、プロバイダーに直接クエリするか、UI でリソースを一度作成して API 経由でその設定を読み戻してください。references/api-surface.md を参照してください。
• 接続は UUID ではなく名前で解決してください。 GET /api/v1/app-connections/<slug>/connection-name/{connectionName} が存在し、マシンアイデンティティトークンを受け入れるため、自動化で UUID を保存する必要はありません。
• サードパーティ側では最小権限を。 接続の権限は、それを利用するすべての同期とローテーションが実行できる操作の範囲を定めます。狭くスコープを設定し、ユーザーが管理者キーを引き渡そうとしているときはこの点に言及してください。
• ユーザーの代わりに認証情報を生成しないでください。 また、認証情報をそのまま返さないでください。