秘密鍵を生成する
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