Skip to main content
설명서에 자주 업데이트를 게시하며 이 페이지의 번역이 계속 진행 중일 수 있습니다. 최신 정보는 영어 설명서를 참조하세요.

GitHub 앱으로 인증

GitHub App 또는 설치로 인증할 수 있습니다.

GitHub App으로 인증

GitHub App로 인증하려면 API 호출에 server-to-server 필요합니다. 그러면 GitHub App이(가) 몇 가지 작업을 수행할 수 있습니다.

  • GitHub App에 대한 높은 수준의 관리 정보를 검색합니다.
  • 앱 설치를 위한 액세스 토큰을 요청하여 로그인한 사용자 없이 API 호출을 수행할 수 있습니다.

GitHub App으로 인증하려면 PEM 형식의 프라이빗 키를 생성하고 로컬 컴퓨터에 다운로드합니다. 이 키를 사용하여 JWT(JSON Web Token)에 서명 하고 알고리즘을 RS256 사용하여 인코딩합니다. GitHub Enterprise Server은(는) 앱의 저장된 공개 키를 사용하여 토큰을 확인하여 앱 ID의 유효성을 검사합니다. 이 JWT를 특정 설치로 앱을 인증하는 데 사용되는 설치 토큰으로 교환합니다.

앱 설치 나열

앱의 설치를 나열하려면 에 대한 API 요청의 권한 부여 헤더에 JWT를 GET /app/installations포함합니다. JWT 생성에 대한 자세한 내용은 "JWT 페이로드"를 참조하세요.

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

응답에는 설치 액세스 토큰을 만드는 데 각 설치의 id를 사용할 수 있는 설치 목록이 포함됩니다. 응답 형식에 대한 자세한 내용은 “인증된 앱에 대한 설치 나열”을 참조하세요.

설치로 인증

설치로 인증하면 앱이 GitHub Enterprise Server의 공용 리소스뿐만 아니라 API를 통해 해당 조직 또는 사용자에 액세스할 수 있습니다. 설치로 인증하려면 JWT 를 GitHub Enterprise Server에 보내 앱의 ID를 증명하여 가져오는 설치 액세스 토큰을 사용해야 합니다. 하나 이상의 조직 또는 사용자 계정에 GitHub 앱을 이미 설치했는지 확인합니다. 설치 없이는 설치 토큰을 만들 수 없습니다. 자세한 내용은 “GitHub 앱 설치”를 참조하세요.

기본적으로 설치 액세스 토큰은 설치에 액세스 권한이 부여된 모든 리포지토리로 범위가 지정됩니다. 매개 변수를 사용하여 repository_ids 설치 액세스 토큰의 범위를 특정 리포지토리로 추가로 제한할 수 있습니다. 설치 액세스 토큰에는 GitHub App에서 구성한 권한이 있으며 리포지토리 액세스와 마찬가지로 매개 변수를 사용하여 permissions 범위를 축소할 수도 있습니다. 자세한 내용은 앱 엔드포인트에 대한 설치 액세스 토큰 만들기 설명서를 참조하세요. 모든 설치 토큰은 1시간 후에 만료됩니다.

설치 액세스 토큰을 만들려면 API 요청의 권한 부여 헤더에 JWT를 포함하고 를 설치의 id로 바꿉 :installation_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 요청의 권한 부여 헤더에 포함합니다. 를 설치 액세스 토큰으로 대체 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을 사용하여 전달할 수 있습니다. 그러나 JWT(JSON 웹 토큰)를 전달하는 경우 Authorization: Bearer를 사용해야 합니다.

설치로 API 엔드포인트 액세스

설치 액세스 토큰을 사용하여 GitHub Apps에서 사용할 수 있는 REST API 엔드포인트 목록은 "GitHub 앱에 사용할 수 있는 엔드포인트"를 참조하세요.

설치와 관련된 엔드포인트 목록은 "설치"를 참조하세요.

설치를 통한 HTTP 기반 Git 액세스

리포지토리의 contents에 대한 사용 권한이 있는 설치는 설치 액세스 토큰을 사용하여 Git 액세스를 인증할 수 있습니다. 설치 액세스 토큰을 HTTP 암호로 사용합니다.

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

JWT(JSON 웹 토큰) 생성

애플리케이션을 인증하는 데 사용되는 JWT 는 여러 클레임과 해당 신뢰성의 유효성을 검사하는 데 사용되는 서명으로 구성됩니다. 이러한 클레임은 다음과 같습니다.

클레임의미세부 정보
iat발급 시간JWT를 만든 시간입니다. 시계 드리프트로부터 보호하려면 과거에 이 60초를 설정하는 것이 좋습니다.
exp만료 날짜JWT의 만료 시간이며, 그 후에는 설치 토큰을 요청하는 데 사용할 수 없습니다. 는 exp 앞으로 10분 이내여야 합니다.
iss발급자JWT의 서명을 확인하는 데 적합한 공개 키를 찾는 데 사용되는 애플리케이션 ID입니다.

일치하는 클레임RS256이 있는 알고리즘을 RS256 사용하여 토큰에 alg 서명해야 합니다.

Ruby 사용

다음은 JWT를 생성하는 데 사용할 수 있는 Ruby 스크립트입니다. 사용하기 전에 실행 gem install jwt를 실행해야 합니다. YOUR_PATH_TO_PEMYOUR_APP_ID는 바꿔야 하는 값입니다. 값을 큰따옴표로 묶어야 합니다.

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 사용

다음은 Python에서 JWT를 생성하기 위한 유사한 스크립트입니다. 이 스크립트를 사용하려면 를 사용해야 pip install jwt 합니다. 이 스크립트는 PEM 파일의 위치와 앱의 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의 식별자(YOUR_APP_ID)를 JWT iss(발급자) 클레임의 값으로 사용합니다. 앱을 만든 후 초기 웹후크 ping을 통해 또는 언제든지 GitHub.com UI의 앱 설정 페이지에서 GitHub App 식별자를 가져올 수 있습니다.

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

시간이 만료된 후 새 JWT를 만들어야 합니다.

GitHub App(으)로 API 엔드포인트 액세스

GitHub App에 대한 상위 수준 정보를 가져오는 데 사용할 수 있는 REST API 엔드포인트 목록은 “GitHub 앱”을 참조하세요.

프라이빗 키 생성

GitHub App을(를) 만든 후에는 GitHub Enterprise Server API를 애플리케이션 자체로 요청하기 위해 하나 이상의 프라이빗 키를 생성해야 합니다. 프라이빗 키를 사용하여 설치 액세스 토큰을 요청하는 데 사용되는 JWT에 서명합니다.

여러 프라이빗 키를 만들고 회전하여 키가 손상되거나 손실되는 경우 가동 중지 시간을 방지할 수 있습니다. 프라이빗 키가 퍼블릭 키와 일치하는지 확인하려면 프라이빗 키 확인을 참조하세요.

프라이빗 키를 생성하려면 다음을 수행합니다.

  1. 페이지의 오른쪽 위 모서리에서 프로필 사진을 클릭한 다음 설정 클릭합니다.

    사용자 표시줄의 설정 아이콘

  2. 왼쪽 사이드바에서 개발자 설정을 클릭합니다.

  3. 왼쪽 사이드바에서 GitHub 앱을 클릭합니다. GitHub 앱 섹션 1. 수정하려는 GitHub App의 오른쪽에서 Edit(편집)을 클릭합니다. 앱 선택

  4. “Private keys”(프라이빗 키)에서 Generate a private key(프라이빗 키 생성)를 클릭합니다. Generate private key(프라이빗 키 생성)

  5. 컴퓨터에 다운로드된 PEM 형식의 프라이빗 키가 표시됩니다. GitHub는 키의 공용 부분만 저장하므로 이 파일을 저장해야 합니다.

참고: 특정 파일 형식이 필요한 라이브러리를 사용하는 경우 다운로드한 PEM 파일은 PKCS#1 RSAPrivateKey 형식이 됩니다.

프라이빗 키 확인

GitHub Enterprise Server는 SHA-256 해시 함수를 사용하여 각 프라이빗 키 및 퍼블릭 키 쌍에 대한 지문을 생성합니다. 프라이빗 키의 지문을 생성하고 GitHub Enterprise Server에 표시된 지문과 비교하여 프라이빗 키가 GitHub Enterprise Server에 저장된 퍼블릭 키와 일치하는지 확인할 수 있습니다.

프라이빗 키를 확인하려면 다음을 수행합니다.

  1. GitHub App의 개발자 설정 페이지의 “프라이빗 키” 섹션에서 확인하려는 프라이빗 키 및 퍼블릭 키 쌍의 지문을 찾습니다. 자세한 내용은 프라이빗 키 생성을 참조하세요. 프라이빗 키 지문
  2. 다음 명령을 사용하여 프라이빗 키 지문(PEM)을 로컬로 생성합니다.
    $ openssl rsa -in PATH_TO_PEM_FILE -pubout -outform DER | openssl sha256 -binary | openssl base64
  3. 로컬로 생성된 지문의 결과를 GitHub Enterprise Server에 표시되는 지문과 비교합니다.

프라이빗 키 삭제

삭제하여 손실되거나 손상된 프라이빗 키를 제거할 수 있지만 항상 GitHub App에 대해 하나 이상의 프라이빗 키가 등록되어 있어야 합니다. GitHub App에 하나의 키만 있는 경우 이전 키를 삭제하기 전에 새 키를 생성해야 합니다. 마지막 프라이빗 키 삭제