GitHub App による認証

秘密鍵を生成する

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

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

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

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

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

秘密鍵を検証する

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

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

GitHub App の開発者設定ページにある [Private keys] セクションで、検証する秘密鍵と公開鍵のペアを見つけます。詳しい情報については、秘密鍵を生成するを参照してください。
次のコマンドを使用して、秘密鍵 (PEM) のフィンガープリントをローカルで生成します。
```
$ openssl rsa -in PATH_TO_PEM_FILE -pubout -outform DER | openssl sha1 -c
```
ローカルで生成されたフィンガープリントの結果と、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 の値は置き換えてください。 Make sure to enclose the values in double quotes.

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/2.22/rest"
}

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

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

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

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

インストールとして認証を行うと、そのインストールの API でアクションを実行できます。インストールとして認証を行う前に、インストールアクセストークンを作成する必要があります。 GitHub Appが少なくとも1つのリポジトリにインストールされていることを確認してください。まったくインストールされていない場合、インストールトークンを作成することは不可能です。 These installation access tokens are used by GitHub Apps to authenticate. For more information, see "Installing GitHub Apps."

デフォルトでは、インストールトークンのスコープは、インストールがアクセスできるすべてのリポジトリにアクセスできるよう設定されています。 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 エンドポイントにアクセスする

For a list of REST API endpoints that are available for use by GitHub Apps using an installation access token, see "Available Endpoints."

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

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

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

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

製品で調べる

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