ドキュメントには頻繁に更新が加えられ、その都度公開されています。本ページの翻訳はまだ未完成な部分があることをご了承ください。最新の情報については、英語のドキュメンテーションをご参照ください。本ページの翻訳に問題がある場合はこちらまでご連絡ください。

GitHub App による認証

You can authenticate as a GitHub App or as an installation.

ここには以下の内容があります:

秘密鍵を生成する

GitHub App の作成後は、1 つ以上の秘密鍵を生成する必要があります。 アクセストークンのリクエストに署名するには、この秘密鍵を使用します。

鍵が危殆化したり、鍵を紛失した場合にダウンタイムを回避するため、複数の秘密鍵を作成してローテーションすることができます。 秘密鍵が公開鍵と適合することを確認するには、秘密鍵を検証するを参照してください。

秘密鍵を生成するには、以下の手順に従います。

  1. 任意のページの右上で、プロフィール画像をクリックし、続いてSettings(設定)をクリックしてください。
    ユーザバーの [Settings(設定)] アイコン
  2. 左サイドバーで [Developer settings] をクリックします。
    Developer settings(開発者設定)セクション
  3. In the left sidebar, click GitHub Apps.
    GitHub Apps セクション
  4. Select the GitHub App you want to modify.
    アプリケーションの選択
  5. [Private keys] で、[Generate a private key] をクリックします。
    秘密鍵の生成
  6. お手元のコンピュータにダウンロードされた PEM フォーマットの秘密鍵が表示されます。 このファイルは必ず保存してください。GitHub では公開鍵の部分しか保存しません。

注釈: 特定のファイルフォーマットが必要なライブラリを使用している場合、ダウンロードする PEM ファイルは PKCS#1 RSAPrivateKey フォーマットになります。

秘密鍵を検証する

GitHub Enterprise Server は、 SHA-1 ハッシュ関数を使用して、秘密鍵と公開鍵との各ペアに対してフィンガープリントを生成します。 秘密鍵のフィンガープリントを生成し、GitHub Enterprise Server で表示されているフィンガープリントと比較することにより、秘密鍵が GitHub Enterprise Server に保存宇されている公開鍵と適合することを検証できます。

秘密鍵を検証するには、以下の手順に従います。

  1. GitHub App の開発者設定ページにある [Private keys] セクションで、検証する秘密鍵と公開鍵のペアを見つけます。 詳しい情報については、秘密鍵を生成するを参照してください。
    秘密鍵のフィンガープリント
  2. 次のコマンドを使用して、秘密鍵 (PEM) のフィンガープリントをローカルで生成します。
    $ openssl rsa -in PATH_TO_PEM_FILE -pubout -outform DER | openssl sha1 -c
  3. ローカルで生成されたフィンガープリントの結果と、GitHub Enterprise Server に表示されているフィンガープリントを比較します。

秘密鍵を削除する

紛失や危殆化した秘密鍵は削除できますが、最低 1 つは秘密鍵を所有する必要があります。 鍵が 1 つしかない場合、その鍵を削除する前に新しい鍵を生成する必要があります。 直近の秘密鍵を削除する

GitHub App として認証を行う

GitHub App として認証を行うと、以下のことが可能になります。

  • GitHub App について管理情報の概要を取得できます。
  • アプリケーションのインストールのため、アクセストークンをリクエストできます。

GitHub App として認証するには、PEM フォーマットで秘密鍵を生成し、ローカルマシンにダウンロードします。 この鍵を使用して JSON Web Token (JWT) に署名し、RS256 アルゴリズムを使用してエンコードします。 GitHub Enterprise Server は、トークンをアプリケーションが保存する公開鍵で検証することにより、リクエストが認証されていることを確認します。

JWT を生成するために使用できる簡単な Ruby スクリプトを掲載します。 gem install jwt を実行してから、このスクリプトを使用してください。

require 'openssl'
require 'jwt'  # https://rubygems.org/gems/jwt

# Private key contents
private_pem = File.read(YOUR_PATH_TO_PEM)
private_key = OpenSSL::PKey::RSA.new(private_pem)

# Generate the JWT
payload = {
  # issued at time
  iat: Time.now.to_i,
  # JWT expiration time (10 minute maximum)
  exp: Time.now.to_i + (10 * 60),
  # GitHub App's identifier
  iss: YOUR_APP_ID
}

jwt = JWT.encode(payload, private_key, "RS256")
puts jwt

YOUR_PATH_TO_PEMYOUR_APP_ID の値は置き換えてください。

GitHub App の識別子 (YOUR_APP_ID) を、JWT iss (発行者) クレームの値として使用します。 GitHub App 識別子は、アプリケーションを作成後の最初の webhook ping から、または GitHub.com UI のアプリケーション設定ページからいつでも取得できます。

JWT を作成後は、それを API リクエストの Header に設定します。

$ curl -i -H "Authorization: Bearer YOUR_JWT" -H "Accept: application/vnd.github.v3+json" http(s)://[hostname]/api/v3/app

YOUR_JWT の値は置き換えてください。

上記の例では、最大有効期限として 10 分間を設定し、その後は API が 401 エラーを返し始めます。

{
  "message": "'Expiration' claim ('exp') must be a numeric value representing the future time at which the assertion expires.",
  "documentation_url": "https://developer.github.com/enterprise/enterprise-server@2.22/v3"
}

有効期限が経過した後は、JWT を新しく作成する必要があります。

GitHub App として API エンドポイントにアクセスする

GitHub App の概要を取得するために使用できる REST API エンドポイントの一覧については、「GitHub App」を参照してください。

インストールとして認証を行う

インストールとして認証を行うと、そのインストールの API でアクションを実行できます。 インストールとして認証を行う前に、インストールアクセストークンを作成する必要があります。 インストールアクセストークンは、認証を行うため GitHub App により使用されます。

デフォルトでは、インストールトークンのスコープは、インストールがアクセスできるすべてのリポジトリにアクセスできるよう設定されています。 repository_ids パラメータを使用すると、インストールアクセストークンのスコープを特定のリポジトリに限定できます。 詳細については、アプリケーション (エンドポイント) に対するアクセストークンの作成を参照してください。 インストールアクセストークンは GitHub App によって設定された権限を持ち、1 時間後に期限切れになります。

インストールアクセストークンを作成するには、上記で生成した JWT を API リクエストの Authorization ヘッダに含めます。

$ curl -i -X POST \
-H "Authorization: Bearer YOUR_JWT" \
-H "Accept: application/vnd.github.v3+json" \
http(s)://[hostname]/api/v3/app/installations/:installation_id/access_tokens

レスポンスには、インストールアクセストークン、有効期限、トークンの権限、およびトークンがアクセスできるリポジトリが含まれます。 レスポンスのフォーマットに関する詳しい情報については、アプリケーション (エンドポイント) に対するアクセストークンの作成を参照してください。

インストールアクセストークンで認証を行うには、インストールアクセストークンを API リクエストの Authorization ヘッダに含めます。

$ curl -i \
-H "Authorization: token YOUR_INSTALLATION_ACCESS_TOKEN" \
-H "Accept: application/vnd.github.v3+json" \
http(s)://[hostname]/api/v3/installation/repositories

YOUR_INSTALLATION_ACCESS_TOKEN の値は置き換えてください。

インストールとして API エンドポイントにアクセスする

インストールアクセストークンを使用して GitHub App の概要を取得するために利用できる REST API エンドポイントの一覧については、「利用可能なエンドポイント」を参照してください。

インストールに関連するエンドポイントの一覧については、「インストール」を参照してください。

インストールによる HTTP ベースの Git アクセス

リポジトリの contents権限があるインストールは、インストールアクセストークンを使用して Git へのアクセスを認証できます。 インストールアクセストークンを HTTP パスワードとして使用してください。

git clone https://x-access-token:<token>@github.com/owner/repo.git

Did this doc help you?

Privacy policy

Help us make these docs great!

All GitHub docs are open source. See something that's wrong or unclear? Submit a pull request.

Make a contribution

OR, learn how to contribute.