Skip to main content

GitHub App による認証

In this article

GitHub Appとして、あるいはインストールとして認証を受けることができます。

server-to-server API 呼び出しには GitHub App としての認証が必要です。これにより、GitHub App で次のような操作を実行できます。

GitHub App について管理情報の概要を取得できます。

  • アプリのインストール用にアクセス トークンを要求します。これにより、サインイン済みのユーザーなしで API 呼び出しを行うことができます。
  • GitHub App として認証するには、PEM 形式で秘密キーを生成し、ローカル コンピューターにダウンロードします。

このキーを使用して JSON Web Token (JWT) に署名し、これを RS256 アルゴリズムを使用してエンコードします。 GitHub Enterprise Server では、アプリに保存されている公開鍵でトークンを検証して、アプリの ID が検証されます。 この JWT を、特定のインストールとしてアプリを認証するために使用されるインストール トークンと交換します。 アプリのインストールを一覧表示する

アプリのインストールを一覧表示するには、GET /app/installations への API 要求の Authorization ヘッダーに JWT を含めます。

JWT の生成について詳しくは、"JWT のペイロード" をご覧ください。 応答には、各インストールの id を使用してインストール アクセス トークンを作成できる、インストールの一覧が含まれます。

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

応答形式の詳細については、「認証済みアプリのインストールを一覧表示する」を参照してください。 インストールとして認証を行う

インストールとして認証すると、アプリは API を介してその Organization またはユーザーのほか、GitHub Enterprise Server 上のパブリック リソースにもアクセスできます。

インストールとして認証するには、インストール アクセス トークンを使用する必要があります。これは、JWT を GitHub Enterprise Server に送信してアプリの ID を証明すると取得できます。 GitHub App が少なくとも 1 つの Organization またはユーザー アカウントにインストールされていることを確認します。インストールされていない場合は、インストール トークンを作成できません。 詳細については、「GitHub アプリのインストール」を参照してください。 既定では、インストール トークンのスコープは、インストールがアクセスを許可されたすべてのリポジトリにアクセスできるよう設定されています。

repository_ids パラメーターを使用して、インストール アクセス トークンのスコープを特定のリポジトリにさらに制限できます。 インストール アクセス トークンには、GitHub App によって構成されたアクセス許可があり、リポジトリ アクセスと同様に、permissions パラメーターを使用してスコープを下げることもできます。 詳しくは、「アプリのエンドポイントのインストール アクセス トークンを作成する」を参照してください。 すべてのインストール トークンは、1 時間で有効期限が切れます。 インストール アクセス トークンを作成するには、JWT を API 要求の Authorization ヘッダーに含め、:installation_id をインストールの id に置き換えます。

JWT の生成について詳しくは、"JWT のペイロード" をご覧ください。 レスポンスには、インストールアクセストークン、有効期限、トークンの権限、およびトークンがアクセスできるリポジトリが含まれます。

$ 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 ヘッダーに含めます。

YOUR_INSTALLATION_ACCESS_TOKEN をインストール アクセス トークンに置き換えます。

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

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

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

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

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

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

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

インストールアクセストークンを HTTP パスワードとして使用してください。 JSON Web Token (JWT) を生成する

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

アプリケーションの認証に使用される JWT は、いくつかのクレームと、その信頼性の検証に使用される署名で構成されます。

これらのクレームは次のとおりです。 要求

意味詳細発行時刻
iatJWT が作成された時刻。クロック ドリフトから保護するために、過去にこの 60 秒を設定することをお勧めします。 有効期限が切れるタイミング
expJWT の有効期限。これを過ぎると、インストール トークンの要求に使うことができません。exp は、今後 10 分以内にする必要があります。 発行者
issJWT の署名を検証するための適切な公開キーの検索に使用される、お使いのアプリケーション ID。トークンは、RS256 アルゴリズムを使用して署名する必要があり、RS256alg クレームと一致する必要があります。

Ruby の使用

ここでは、JWT の生成に使用できる Ruby スクリプトを示します。

使用する前に gem install jwt を実行する必要があることに注意してください。 YOUR_PATH_TO_PEM および YOUR_APP_ID は、置換する必要がある値です。 値はダブルクオートで囲んでください。 Python の使用

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

Python で JWT を生成するための同様のスクリプトを次に示します。

このスクリプトを使うには、pip install jwt を使う必要があることに注意してください。 このスクリプトにより、PEM ファイルとお使いのアプリ ID の場所の入力を求めるダイアログが表示されます。または、スクリプトの実行時にインライン引数としてそれらを渡すこともできます。 JWT iss (発行者) 要求の値として、GitHub App の識別子 (YOUR_APP_ID) を使用します。

python
#!/usr/bin/env python3
import jwt
import time 
import sys

# Get PEM file path
if len(sys.argv) > 1:
    pem = sys.argv[1]
else:
    pem = input("Enter path of private PEM file: ")    

# Get the App ID
if len(sys.argv) > 2:
    app_id = sys.argv[2]
else:
    app_id = input("Enter your APP ID: ") 

# Open PEM
with open(pem, 'rb') as pem_file:
    signing_key = jwt.jwk_from_pem(pem_file.read())
    
payload = {
    # Issued at time
    'iat': int(time.time()),
    # JWT expiration time (10 minutes maximum)
    'exp': int(time.time()) + 600, 
    # GitHub App's identifier
    'iss': app_id 
}
    
# Create JWT
jwt_instance = jwt.JWT()
encoded_jwt = jwt_instance.encode(payload, signing_key, alg='RS256')
     
print(f"JWT:  ", encoded_jwt)

GitHub App 識別子は、アプリ作成後の最初の Webhook ping から、または GitHub.com UI のアプリ設定ページからいつでも取得できます。 JWT を作成したら、API 要求の Header に設定します。

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

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

上の例では、最大有効期限として 10 分間を使っており、それが過ぎると API は 401 エラーを返し始めます。

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

{
  "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.5/rest"
}

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

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

秘密鍵を生成する

GitHub App を作成した後、アプリケーション自体として GitHub Enterprise Server API に要求を行うために、1 つ以上の秘密キーを生成する必要があります。

秘密キーを使用して、インストール アクセス トークンの要求に使用される JWT に署名します。 鍵が危殆化したり、鍵を紛失した場合にダウンタイムを回避するため、複数の秘密鍵を作成してローテーションすることができます。

秘密キーが公開キーと一致することを確認するには、「秘密キーを検証する」を参照してください。 秘密鍵を生成するには、以下の手順に従います。

  1. 任意のページで、右上隅にあるプロファイルの画像をクリックし、次に[設定]をクリックします。

    ユーザバーの [Settings(設定)] アイコン

  2. 左側のサイドバーで、 [開発者向け設定] をクリックします。

  3. 左側のサイドバーで、 [GitHub アプリ] をクリックします。 [GitHub アプリ] セクション 1. 変更する GitHub App の右で [編集] をクリックします。 アプリの選択

[秘密キー] で、 [秘密キーの生成] をクリックします。 5. 秘密キーの生成 お手元のコンピュータにダウンロードされた PEM フォーマットの秘密鍵が表示されます。 6. このファイルは必ず保存してください。GitHub では公開鍵の部分しか保存しません。

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

秘密鍵を検証する

GitHub Enterprise Server は、SHA-256 ハッシュ関数を使用して、秘密キーと公開キーのペアごとにフィンガープリントを生成します。

秘密鍵のフィンガープリントを生成し、GitHub Enterprise Server で表示されているフィンガープリントと比較することにより、秘密鍵が GitHub Enterprise Server に保存宇されている公開鍵と適合することを検証できます。 秘密鍵を検証するには、以下の手順に従います。

GitHub App の開発者設定ページにある [Private keys] セクションで、検証する秘密鍵と公開鍵のペアを見つけます。

  1. 詳細については、「秘密キーを生成する」を参照してください。 秘密キーのフィンガープリント 次のコマンドを使用して、秘密鍵 (PEM) のフィンガープリントをローカルで生成します。
  2. ローカルで生成されたフィンガープリントの結果と、GitHub Enterprise Server に表示されているフィンガープリントを比較します。
    $ openssl rsa -in PATH_TO_PEM_FILE -pubout -outform DER | openssl sha256 -binary | openssl base64
  3. 秘密鍵を削除する

紛失した、またはセキュリティ侵害された秘密キーは消去すると削除できますが、GitHub App には、常に少なくとも 1 つの秘密キーを登録しておく必要があります。

お使いの GitHub App にキーが 1 つしかない場合は、以前のものを消去する前に新しいものを生成する必要があります。 直近の秘密キーを削除する </ph>Deleting last private key<ph id="ph2">