GitHub App による認証

秘密鍵を生成する

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

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

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

任意のページで、右上隅にあるプロファイルの画像をクリックし、次に[設定]をクリックします。
左側のサイドバーで、 [開発者向け設定] をクリックします。 1. 左側のサイドバーで、 [GitHub アプリ] をクリックします。 1. 変更する GitHub App の右で [編集] をクリックします。
[秘密キー] で、 [秘密キーの生成] をクリックします。
お手元のコンピュータにダウンロードされた PEM フォーマットの秘密鍵が表示されます。このファイルは必ず保存してく� さい。GitHub では公開鍵の部分しか保存しません。

注: 特定のファイル形式を必要とするライブラリを使用している� �合、ダウンロードする PEM ファイルは PKCS#1 RSAPrivateKey 形式になります。

秘密鍵を検証する

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

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

GitHub App の開発者設定ページにある [Private keys] セクションで、検証する秘密鍵と公開鍵のペアを見つけます。詳細については、「秘密キーを生成する」を参照してく� さい。
次のコマンドを使用して、秘密鍵 (PEM) のフィンガープリントをローカルで生成します。
```
$ openssl rsa -in PATH_TO_PEM_FILE -pubout -outform DER | openssl sha256 -binary | openssl base64
```
ローカルで生成されたフィンガープリントの結果と、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 は、置換する必要がある値です。値はダブルクオートで囲んでく� さい。

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

JWT を作成したら、API 要求の Header に設定します。

$ curl -i -H "Authorization: Bearer YOUR_JWT" -H "Accept: application/vnd.github+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.3/rest"
}

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

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

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

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

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

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

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

$ curl -i -X GET \
-H "Authorization: Bearer YOUR_JWT" \
-H "Accept: application/vnd.github+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+json" \
http(s)://HOSTNAME/api/v3/app/installations/:installation_id/access_tokens

レスポンスには、インストールアクセストークン、有効期限、トークンの権限、およびトークンがアクセスできるリポジトリが含まれます。応答形式の詳細については、「アプリのエンドポイントにインストールアクセストークンを作成する」を参照してく� さい。

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

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

YOUR_INSTALLATION_ACCESS_TOKEN は、置換する必要がある値です。

注: ほとんどの� �合は、Authorization: Bearer または Authorization: token を使用してトークンを渡すことができます。た� し、JSON Web トークン (JWT) を渡す� �合は、Authorization: Bearer を使用する必要があります。

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

インストールアクセストークンを使用して GitHub Apps で使用できる REST API エンドポイントの一覧については、「使用可能なエンドポイント」を参照してく� さい。

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

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

リポジトリの contents に対するアクセス許可を持つインストールでは、そのインストールアクセストークンを使用して Git アクセスの認証を行うことができます。インストールアクセストークンを HTTP パスワードとして使用してく� さい。

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