GitHub App による認証

秘密鍵を生成する

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

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

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

1. 任意のページの右上で、プロフィール画像をクリックし、続いてSettings（設定）をクリックしてください。
2. 左サイドバーで [Developer settings] をクリックします。
3. 左のサイドバーでGitHub Appsをクリックしてください。
4. 変更したいGitHub Appの右でEdit（編集）をクリックしてください。
5. [Private keys] で、[Generate a private key] をクリックします。
6. お手元のコンピュータにダウンロードされた PEM フォーマットの秘密鍵が表示されます。 このファイルは必ず保存してください。GitHub では公開鍵の部分しか保存しません。

秘密鍵を検証する

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, 60 seconds in the past to allow for clock drift
  iat: Time.now.to_i - 60,
  # 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_PEM と YOUR_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.machine-man-preview+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://docs.github.com/enterprise/2.21/rest"
}

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

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

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

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

インストールとして認証を行うと、そのインストールの API でアクションを実行できます。 インストールとして認証を行う前に、インストールアクセストークンを作成する必要があります。 Ensure that you have already installed your GitHub App to at least one repository; it is impossible to create an installation token without a single installation. インストールアクセストークンは、認証を行うため GitHub App により使用されます。 詳しい情報については「GitHub Appのインストール」を参照してください。

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

To list the installations for an authenticated app, include the JWT generated above in the Authorization header in the API request:

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

The response will include a list of installations where each installation's id can be used for creating an installation access token. For more information about the response format, see "List installations for the authenticated app."

To create an installation access token, include the JWT generated above in the Authorization header in the API request and replace :installation_id with the installation's id:

$ curl -i -X POST \
-H "Authorization: Bearer YOUR_JWT" \
-H "Accept: application/vnd.github.machine-man-preview+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.machine-man-preview+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