英語 ▾ トピック ▾ 最新バージョン ▾ git-credential は 2.46.0 で最終更新されました

名前

git-credential - ユーザー認証情報を取得および保存

書式

'git credential' (fill|approve|reject|capability)

説明

Git には、システム固有のヘルパーから認証情報を保存および取得したり、ユーザーにユーザー名とパスワードを要求したりするための内部インターフェースがあります。git-credential コマンドは、Git と同じ方法で認証情報を取得、保存、または要求したいスクリプトにこのインターフェースを公開します。このスクリプト可能なインターフェースの設計は、内部 C API をモデルにしています。概念の詳細については、credential.h を参照してください。

git-credential はコマンドラインで "action" オプション (fill、approve、または reject のいずれか) を受け取り、標準入力から認証情報の記述を読み込みます (入力/出力形式 を参照)。

アクションが fill の場合、git-credential は設定ファイルを読み込んだり、設定されている認証ヘルパーに問い合わせたり、ユーザーにプロンプトを表示したりすることで、記述に "username" と "password" 属性を追加しようとします。その後、認証情報の記述のユーザー名とパスワード属性は、既に提供されている属性と共に標準出力に表示されます。

アクションが approve の場合、git-credential は記述を設定されている認証ヘルパーに送信し、ヘルパーは認証情報を後で使用するために保存する場合があります。

アクションが reject の場合、git-credential は記述を設定されている認証ヘルパーに送信し、ヘルパーは記述に一致する保存済みの認証情報を消去する場合があります。

アクションが capability の場合、git-credential はサポートする機能があれば標準出力に通知します。

アクションが approve または reject の場合、出力は行われません。

GIT CREDENTIAL の典型的な使用例

git-credential を使用するアプリケーションは、通常、以下の手順で git credential を使用します。

  1. コンテキストに基づいて認証情報の記述を生成します。

    例えば、https://example.com/foo.git のパスワードが必要な場合、次の認証情報記述を生成するかもしれません (末尾の空行を忘れないでください。これは、アプリケーションが持っているすべての情報の入力を完了したことを git credential に伝えます)。

    protocol=https
host=example.com
path=foo.git

  2. この記述に対するユーザー名とパスワードを git-credential に要求します。これは git credential fill を実行し、ステップ (1) の記述を標準入力に与えることによって行われます。完全な認証情報記述 (認証情報そのもの、すなわちログインとパスワードを含む) は、次のように標準出力に生成されます。

    protocol=https
host=example.com
username=bob
password=secr3t

    ほとんどの場合、これは入力で与えられた属性が出力で繰り返されることを意味しますが、Git は認証情報の記述を変更することもできます。例えば、プロトコルが HTTP(s) で credential.useHttpPath が false の場合に path 属性を削除するなどです。

    git credential がパスワードを知っていた場合、このステップではユーザーが実際にパスワードを入力する必要がなかったかもしれません (ユーザーは代わりにキーチェーンのロックを解除するためにパスワードを入力したか、キーチェーンがすでにロック解除されていた場合はユーザー操作は行われませんでした) password=secr3t を返す前に。

  3. 認証情報を使用し (例えば、ステップ (2) のユーザー名とパスワードで URL にアクセスし)、それが受け入れられるかを確認します。

  4. パスワードの成功または失敗を報告します。認証情報が操作を正常に完了させた場合、それは次の呼び出しで再利用するように git credential に伝えるために「承認 (approve)」アクションでマークすることができます。認証情報が操作中に拒否された場合、次の呼び出しで git credential が新しいパスワードを要求するように「拒否 (reject)」アクションを使用します。どちらの場合も、git credential にはステップ (2) で取得した認証情報の記述 (ステップ (1) で提供されたフィールドも含む) を与える必要があります。

入力/出力形式

git credential は、使用されるアクションに応じて、認証情報を標準入出力で読み書きします。この情報は、git credential がログイン情報を取得するキー (例: ホスト、プロトコル、パス) に対応する場合もあれば、取得される実際の認証情報データ (ユーザー名/パスワード) に対応する場合もあります。

認証情報は、名前付き属性のセットに分割され、各行に1つの属性が記述されます。各属性は、= (イコール) 記号で区切られたキーと値のペアで指定され、その後に改行が続きます。

キーには、=、改行、または NUL 以外の任意のバイトを含めることができます。値には、改行または NUL 以外の任意のバイトを含めることができます。実装が効率的に解析できるように、末尾の改行を含む行は 65535 バイトを超えてはなりません。

C スタイルの配列括弧 [] で終わるキーを持つ属性は、複数の値を持つことができます。複数値属性の各インスタンスは、値の順序付きリストを形成します。繰り返される属性の順序が値の順序を定義します。空の複数値属性 (key[]=\n) は、以前のエントリをクリアし、リストをリセットする役割を果たします。

すべての場合において、すべてのバイトはそのまま扱われます (つまり、引用符付けはなく、改行または NUL を含む値を送信することはできません)。属性のリストは、空行またはファイル終端で終了します。

Git は以下の属性を理解します。

protocol

認証情報が使用されるプロトコル (例: https)。

host

ネットワーク認証情報のリモートホスト名。ポート番号が指定されている場合も含まれます (例: "example.com:8088")。

path

認証情報が使用されるパス。例えば、リモートの https リポジトリにアクセスする場合、これはサーバー上のリポジトリのパスになります。

username

認証情報のユーザー名 (既にある場合。例: URL、設定、ユーザー、または以前に実行されたヘルパーから)。

password

認証情報のパスワード (保存を要求している場合)。

password_expiry_utc

OAuth アクセストークンなどの生成されたパスワードには、有効期限がある場合があります。ヘルパーから認証情報を読み込む際、git credential fill は期限切れのパスワードを無視します。Unix 時刻 UTC、1970年からの秒数で表されます。

oauth_refresh_token

OAuth アクセストークンであるパスワードには、OAuth リフレッシュトークンが伴う場合があります。ヘルパーは、この属性をパスワード属性と同様に機密情報として扱う必要があります。Git 自体は、この属性に対して特別な動作はしません。

url

この特殊な属性が git credential によって読み込まれると、値は URL として解析され、その構成要素が読み込まれたかのように扱われます (例: url=https://example.com は、protocol=https と host=example.com が提供されたかのように動作します)。これにより、呼び出し元は自分で URL を解析する手間を省くことができます。

プロトコルの指定は必須であり、URL がホスト名を指定しない場合 (例: "cert:///path/to/file")、認証情報には値が空文字列のホスト名属性が含まれることに注意してください。

URL から欠落しているコンポーネント (例: 上記の例ではユーザー名がない) は未設定のままになります。

authtype

これは、問題の認証スキームが使用されるべきであることを示します。HTTP および HTTPS の一般的な値には、basic、bearer、digest がありますが、後者は安全ではなく使用すべきではありません。credential が使用される場合、これは問題のプロトコル (通常は HTTP) に適した任意の文字列に設定できます。

この値は、入力で適切な機能 (下記参照) が提供されない限り、送信すべきではありません。

credential

問題のプロトコル (通常は HTTP) に適した、事前にエンコードされた認証情報。このキーが送信される場合、authtype は必須であり、username と password は使用されません。HTTP の場合、Git は authtype の値とこの値を単一のスペースで連結して、Authorization ヘッダーを決定します。

この値は、入力で適切な機能 (下記参照) が提供されない限り、送信すべきではありません。

ephemeral

この真偽値は、真の場合、credential フィールドの値が認証ヘルパーによって保存されるべきではないことを示します。なぜなら、その有用性が時間的に制限されているためです。例えば、HTTP Digest credential の値は nonce を使用して計算され、それを再利用しても認証は成功しません。これは、短期間 (例: 24時間) の認証情報の場合にも使用できます。デフォルト値は false です。

認証ヘルパーは、操作が成功したかどうかを判断できるように、引き続き store または erase で呼び出されます。

この値は、入力で適切な機能 (下記参照) が提供されない限り、送信すべきではありません。

state[]

この値は、このヘルパーが再度呼び出された場合に渡される不透明な状態を提供します。認証ヘルパーごとに一度だけこれを指定できます。値には認証ヘルパーに固有のプレフィックスを含める必要があり、そのプレフィックスに一致しない値は無視すべきです。

この値は、入力で適切な機能 (下記参照) が提供されない限り、送信すべきではありません。

continue

これは真偽値であり、有効になっている場合、この認証が多段階認証ステップの最終ではない部分であることを示します。これは、NTLM や Kerberos などのプロトコルで一般的であり、クライアント認証の2ラウンドが必要な場合、このフラグを設定することで認証ヘルパーが多段階認証ステップを実装できるようになります。このフラグは、さらなる段階が必要な場合にのみ送信されるべきです。つまり、別の認証ラウンドが予想される場合です。

この値は、入力で適切な機能 (下記参照) が提供されない限り、送信すべきではありません。この属性は、認証ヘルパーから Git (または git credential を呼び出す他のプログラム) へ情報を渡す一方通行です。

wwwauth[]

Git が1つ以上の WWW-Authenticate 認証ヘッダーを含む HTTP レスポンスを受信した場合、これらは Git によって認証ヘルパーに渡されます。

各 WWW-Authenticate ヘッダー値は、複数値属性 wwwauth[] として渡され、属性の順序は HTTP レスポンスに表示される順序と同じです。この属性は、Git から認証ヘルパーに追加情報を渡す一方通行です。

capability[]

これは、Git または必要に応じてヘルパーが、問題の機能をサポートしていることを示します。これは、プロトコルの一部として、より良い、より具体的なデータを提供するために使用できます。capability[] ディレクティブは、それに依存する値の前に置かれなければならず、これらのディレクティブはプロトコルで最初に通知される項目であるべきです。

現在サポートされている機能は2つあります。1つ目は authtype であり、authtype、credential、および ephemeral の値が理解されることを示します。2つ目は state であり、state[] と continue の値が理解されることを示します。

機能がサポートされているからといって、追加機能の使用が義務付けられているわけではありませんが、機能なしでそれらを提供すべきではありません。

認識されない属性と機能は、黙って破棄されます。

機能の入力/出力形式

git credential capability の場合、形式が若干異なります。まず、プロトコルの現在のバージョンを示す version 0 のアナウンスが行われ、次に各機能が capability authtype のような行でアナウンスされます。認証ヘルパーも、capability 引数を使用してこの形式を実装する場合があります。将来的に追加の行が追加される可能性があります。呼び出し元は、理解できない行を無視すべきです。

これは認証ヘルパープロトコルの新しい部分であるため、古いバージョンの Git や一部の認証ヘルパーはこれをサポートしていない場合があります。ゼロ以外の終了ステータスが返された場合、または最初の行が version という単語とスペースで始まらない場合、呼び出し元は機能がサポートされていないと見なすべきです。

この形式の目的は、認証情報の出力と明確に区別することです。常に同じ出力を生成する非常にシンプルな認証ヘルパー (例: インラインシェルスクリプト) を使用することは可能です。異なる形式を使用することで、ユーザーは機能の通知を正しく実装したり、機能を問い合わせる呼び出し元を誤って混乱させたりする心配なしに、この構文を使い続けることができます。

GIT

git[1] スイートの一部

scroll-to-top