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 generates a fingerprint for each private and public key pair using the SHA-256 hash function. 秘密鍵のフィンガープリントを生成し、GitHub Enterprise Server で表示されているフィンガープリントと比較することにより、秘密鍵が GitHub Enterprise Server に保存宇されている公開鍵と適合することを検証できます。

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

1. GitHub App の開発者設定ページにある [Private keys] セクションで、検証する秘密鍵と公開鍵のペアを見つけます。 詳しい情� �については、秘密鍵を生成するを参照してく� さい。
2. 次のコマンドを使用して、秘密鍵 (PEM) のフィンガープリントをローカルで生成します。

   $ openssl rsa -in PATH_TO_PEM_FILE -pubout -outform DER | openssl sha256 -binary | openssl base64

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.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://docs.github.com/enterprise/3.1/rest"
}

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

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

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

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

インストールとして認証を行うと、そのインストールの API でアクションを実行できます。 インストールとして認証を行う前に、インストールアクセストークンを作成する必要があります。 GitHub Appが少なくとも1つのリポジトリにインストールされていることを確認してく� さい。まったくインストールされていない� �合、インストールトークンを作成することは不可能です。 インストールアクセストークンは、認証を行うため GitHub Apps により使用されます。 詳しい情� �については「GitHub Appのインストール」を参照してく� さい。

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

認証されたアプリケーションのインストールを一覧表示するには、上記で生成した JWT を API リクエストの Authorization ヘッダに含めます。

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

レスポンスには、インストールのリストが含まれ、各インストールの id がインストールのアクセストークンを作成するために利用できます。 レスポンスのフォーマットに関する詳しい情� �については、「認証されたアプリケーションのインストールの一覧表示」を参照してく� さい。

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

$ 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 Apps の概要を取得するために利用できる REST API エンドポイントの一覧については、「利用可能なエンドポイント」を参照してく� さい。

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

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

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

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