GitHub/JWT

JSON Web Tokens (JWTs)

"In order to authenticate as an app or generate an installation access token, you must generate a JSON Web Token (JWT). If a REST API endpoint requires a JWT, the documentation for that endpoint will indicate that you must use a JWT to access the endpoint."

Usage:

curl --request GET \
 --url "https://api.github.com/app" \
 --header "Accept: application/vnd.github+json" \
 --header "Authorization: Bearer [YOUR_JWT]" \
 --header "X-GitHub-Api-Version: 2022-11-28"

Install python jwt:

pip install jwt

make_jwt.py:

#!/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}"

ref: [1]

Notes

ref: [2]

Generating a user access token for a GitHub App - GitHub Docs
https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app

1. GitHub CLI api
2. https://cli.github.com/manual/gh_api

gh api \
 --method POST \
 -H "Accept: application/vnd.github+json" \
 -H "X-GitHub-Api-Version: 2022-11-28" \
 /orgs/ORG/actions/runners/registration-token

Permissions required for GitHub Apps - GitHub Docs
https://docs.github.com/en/rest/overview/permissions-required-for-github-apps?apiVersion=2022-11-28#organization-self-hosted-runners

fpe-devops/github-app-token: A private copy of tibdex/github-app-token
https://github.com/fpe-devops/github-app-token

tibdex/github-app-token: Impersonate a GitHub App in a GitHub Action
https://github.com/tibdex/github-app-token

Differences between GitHub Apps and OAuth apps - GitHub Docs - Machine vs. bot accounts
https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps#machine-vs-bot-accounts

Installation ID:

Where can we find GitHub Apps Installation ID? - Stack Overflow
https://stackoverflow.com/questions/74462420/where-can-we-find-github-apps-installation-id

For GitHub Apps created under Organizations:

Go to the Organization settings
Click on 'GitHub Apps' under 'Third-party Access'
If there are multiple GitHub apps, choose your App and click on 'Configure'
Once your GitHub App is selected check the URL for obtaining 'GitHub App Installation ID'

The URL looks like this:

https://github.com/organizations/<Organization-name>/settings/installations/<ID>

Pick the <ID> part and that's your GitHub App Installation ID.

For GitHub Apps created under Repository, you can find this under repository settings.

- name: Get Installation Token
        uses: tibdex/github-app-token@v1
        id: get_installation_token
        with: 
          app_id: 335706
          # installation_id not needed IF the app is installed on this current repo
          installation_id: 37655626
          private_key: ${{ secrets.PRIVATE_KEY }}

make-jwt.py 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}")
print(f"{encoded_jwt}")

Generate GitHub App Installation Token:

#! /bin/tcsh

set PRIVATE_KEY='create-repos.2023-05-26.private-key.pem'
set APP_ID='339112'
set INSTALLATION_ID='37930554' # In the URL when you configure the app
set JWT=`./make-jwt.py $PRIVATE_KEY $APP_ID`
set INSTALLATION_TOKEN=`curl -s --request POST --url "https://api.github.com/app/installations/$INSTALLATION_ID/access_tokens" --header "Accept: application/vnd.github+json" --header "Authorization: Bearer $JWT" --header "X-GitHub-Api-Version: 2022-11-28" | python -c "import sys, json; print(json.load(sys.stdin)['token'])"`
setenv GH_TOKEN $INSTALLATION_TOKEN
echo GH_TOKEN: $GH_TOKEN

---

JSON Web Tokens - jwt.io
https://jwt.io/
JSON Web Tokens are an open, industry standard RFC 7519 method for representing claims securely between two parties.

---

Generating a JSON Web Token (JWT) for a GitHub App - GitHub Docs
https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-json-web-token-jwt-for-a-github-app#about-json-web-tokens-jwts

curl --request GET \
--url "https://api.github.com/app" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR_JWT" \
--header "X-GitHub-Api-Version: 2022-11-28"

---

[6/2 3:15 PM] Khaled El Hussein

GitHub App documentation is here: https://docs.github.com/en/apps/overview

Creating an app (it requires Org Owner which I can help with): https://docs.github.com/en/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app

Permissions: https://docs.github.com/en/apps/creating-github-apps/setting-up-a-github-app/choosing-permissions-for-a-github-app

Authenticate your system/Jenkins/Tool to this github app, couple of options:     

Using SDK (in javascript) https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation#using-octokitjs-to-authenticate-with-an-installation-id

JWT Token for Rest APIs: https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation#using-an-installation-access-token-to-authenticate-as-an-app-installation

---

Self-hosted runners - GitHub Docs - Create a registration token for an organization
https://docs.github.com/en/rest/actions/self-hosted-runners?apiVersion=2022-11-28#create-a-registration-token-for-an-organization