jprdonnelly/docs
1
0
Fork 0
mirror of synced 2025-12-19 09:57:42 -05:00
Code Issues Projects Releases Wiki Activity

Add conditional for client ID to GHES 3.18 (#58606)

Browse Source 
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: mc <42146119+mchammer01@users.noreply.github.com>
This commit is contained in:
MikaelaMcGrath
2025-11-25 21:49:57 +10:00
committed by GitHub
parent 2a375575d6
commit 8cc07ca28b
2 changed files with 36 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
content/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-json-web-token-jwt-for-a-github-app.md
View File

@@ -20,7 +20,7 @@ Your JWT must be signed using the `RS256` algorithm and must contain the followi
|---|---|---| |---|---|---|
|`iat`| Issued At | The time that the JWT was created. To protect against clock drift, we recommend that you set this 60 seconds in the past and ensure that your server's date and time is set accurately (for example, by using the Network Time Protocol). | |`iat`| Issued At | The time that the JWT was created. To protect against clock drift, we recommend that you set this 60 seconds in the past and ensure that your server's date and time is set accurately (for example, by using the Network Time Protocol). |
|`exp`| Expires At | The expiration time of the JWT, after which it can't be used to request an installation token. The time must be no more than 10 minutes into the future. | |`exp`| Expires At | The expiration time of the JWT, after which it can't be used to request an installation token. The time must be no more than 10 minutes into the future. |
|`iss`| Issuer | The client ID or application ID of your {% data variables.product.prodname_github_app %}. This value is used to find the right public key to verify the signature of the JWT. You can find your app's IDs on the settings page for your {% data variables.product.prodname_github_app %}. Use of the client ID is recommended. For more information about navigating to the settings page for your {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app-registration#navigating-to-your-github-app-settings).| |`iss`| Issuer | The {% ifversion client-id-for-app %}client ID or {% endif %}application ID of your {% data variables.product.prodname_github_app %}. This value is used to find the right public key to verify the signature of the JWT. You can find your app's ID{% ifversion client-id-for-app %}s{% endif %} on the settings page for your {% data variables.product.prodname_github_app %}.{% ifversion client-id-for-app %} Use of the client ID is recommended.{% endif %} For more information about navigating to the settings page for your {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app-registration#navigating-to-your-github-app-settings).|
|`alg`| Message authentication code algorithm | This should be `RS256` since your JWT must be signed using the `RS256` algorithm. | |`alg`| Message authentication code algorithm | This should be `RS256` since your JWT must be signed using the `RS256` algorithm. |
To use a JWT, pass it in the `Authorization` header of an API request. For example: To use a JWT, pass it in the `Authorization` header of an API request. For example:
@@ -47,7 +47,7 @@ Most programming languages have a package that can generate a JWT. In all cases,
> [!NOTE] > [!NOTE]
> You must run `gem install jwt` to install the `jwt` package in order to use this script. > You must run `gem install jwt` to install the `jwt` package in order to use this script.
In the following example, replace `YOUR_PATH_TO_PEM` with the file path where your private key is stored. Replace `YOUR_CLIENT_ID` with the ID of your app. Make sure to enclose the values for `YOUR_PATH_TO_PEM` and `YOUR_CLIENT_ID` in double quotes. In the following example, replace `YOUR_PATH_TO_PEM` with the file path where your private key is stored. Replace {% ifversion client-id-for-app %}`YOUR_CLIENT_ID`{% else %}`YOUR_APP_ID`{% endif %} with the ID of your app. Make sure to enclose the values for `YOUR_PATH_TO_PEM` and {% ifversion client-id-for-app %}`YOUR_CLIENT_ID`{% else %}`YOUR_APP_ID`{% endif %} in double quotes.
```ruby ```ruby
require 'openssl' require 'openssl'
@@ -63,10 +63,11 @@ payload = {
iat: Time.now.to_i - 60, iat: Time.now.to_i - 60,
# JWT expiration time (10 minute maximum) # JWT expiration time (10 minute maximum)
exp: Time.now.to_i + (10 * 60), exp: Time.now.to_i + (10 * 60),
{% ifversion client-id-for-app %}
# {% data variables.product.prodname_github_app %}'s client ID # {% data variables.product.prodname_github_app %}'s client ID
iss: "YOUR_CLIENT_ID" iss: "YOUR_CLIENT_ID"{% else %}
# {% data variables.product.prodname_github_app %}'s app ID
iss: "YOUR_APP_ID"{% endif %}
} }
jwt = JWT.encode(payload, private_key, "RS256") jwt = JWT.encode(payload, private_key, "RS256")
@@ -92,12 +93,19 @@ if len(sys.argv) > 1:
else: else:
pem = input("Enter path of private PEM file: ") pem = input("Enter path of private PEM file: ")
{% ifversion client-id-for-app %}
# Get the Client ID # Get the Client ID
if len(sys.argv) > 2: if len(sys.argv) > 2:
client_id = sys.argv[2] client_id = sys.argv[2]
else: else:
client_id = input("Enter your Client ID: ") client_id = input("Enter your Client ID: ")
{% else %}
# Get the App ID
if len(sys.argv) > 2:
app_id = sys.argv[2]
else:
app_id = input("Enter your APP ID: ")
{% endif %}
# Open PEM # Open PEM
with open(pem, 'rb') as pem_file: with open(pem, 'rb') as pem_file:
@@ -108,9 +116,11 @@ payload = {
'iat': int(time.time()), 'iat': int(time.time()),
# JWT expiration time (10 minutes maximum) # JWT expiration time (10 minutes maximum)
'exp': int(time.time()) + 600, 'exp': int(time.time()) + 600,
{% ifversion client-id-for-app %}
# {% data variables.product.prodname_github_app %}'s client ID # {% data variables.product.prodname_github_app %}'s client ID
'iss': client_id 'iss': client_id{% else %}
# {% data variables.product.prodname_github_app %}'s app ID
'iss': app_id{% endif %}
} }
@@ -125,14 +135,16 @@ This script will prompt you for the file path where your private key is stored a
### Example: Using Bash to generate a JWT ### Example: Using Bash to generate a JWT
> [!NOTE] > [!NOTE]
> You must pass your Client ID and the file path where your private key is stored as arguments when running this script. > You must pass your {% ifversion client-id-for-app %}Client ID{% else %}App ID{% endif %} and the file path where your private key is stored as arguments when running this script.
```bash copy ```bash copy
#!/usr/bin/env bash #!/usr/bin/env bash
set -o pipefail {% ifversion client-id-for-app %}
client_id=$1 # Client ID as first argument client_id=$1 # Client ID as first argument
{% else %}
app_id=$1 # App ID as first argument
{% endif %}
pem=$( cat $2 ) # file path of the private key as second argument pem=$( cat $2 ) # file path of the private key as second argument
now=$(date +%s) now=$(date +%s)
@@ -151,7 +163,7 @@ header=$( echo -n "${header_json}" | b64enc )
payload_json="{ payload_json="{
\"iat\":${iat}, \"iat\":${iat},
\"exp\":${exp}, \"exp\":${exp},
\"iss\":\"${client_id}\" {% ifversion client-id-for-app %}\"iss\":\"${client_id}\"{% else %}\"iss\":\"${app_id}\"{% endif %}
}" }"
# Payload encode # Payload encode
payload=$( echo -n "${payload_json}" | b64enc ) payload=$( echo -n "${payload_json}" | b64enc )
@@ -170,13 +182,16 @@ printf '%s\n' "JWT: $JWT"
### Example: Using PowerShell to generate a JWT ### Example: Using PowerShell to generate a JWT
In the following example, replace `YOUR_PATH_TO_PEM` with the file path where your private key is stored. Replace `YOUR_CLIENT_ID` with the ID of your app. Make sure to enclose the values for `YOUR_PATH_TO_PEM` in double quotes. In the following example, replace `YOUR_PATH_TO_PEM` with the file path where your private key is stored. Replace {% ifversion client-id-for-app %}`YOUR_CLIENT_ID`{% else %}`YOUR_APP_ID`{% endif %} with the ID of your app. Make sure to enclose the values for `YOUR_PATH_TO_PEM` in double quotes.
```powershell copy ```powershell copy
#!/usr/bin/env pwsh #!/usr/bin/env pwsh
{% ifversion client-id-for-app %}
$client_id = YOUR_CLIENT_ID $client_id = YOUR_CLIENT_ID
{% else %}
$app_id = YOUR_APP_ID
{% endif %}
$private_key_path = "YOUR_PATH_TO_PEM" $private_key_path = "YOUR_PATH_TO_PEM"
$header = [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes((ConvertTo-Json -InputObject @{ $header = [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes((ConvertTo-Json -InputObject @{
@@ -187,7 +202,7 @@ $header = [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes((Conve
$payload = [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes((ConvertTo-Json -InputObject @{ $payload = [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes((ConvertTo-Json -InputObject @{
iat = [System.DateTimeOffset]::UtcNow.AddSeconds(-10).ToUnixTimeSeconds() iat = [System.DateTimeOffset]::UtcNow.AddSeconds(-10).ToUnixTimeSeconds()
exp = [System.DateTimeOffset]::UtcNow.AddMinutes(10).ToUnixTimeSeconds() exp = [System.DateTimeOffset]::UtcNow.AddMinutes(10).ToUnixTimeSeconds()
iss = $client_id {% ifversion client-id-for-app %}iss = $client_id{% else %}iss = $app_id{% endif %}
}))).TrimEnd('=').Replace('+', '-').Replace('/', '_'); }))).TrimEnd('=').Replace('+', '-').Replace('/', '_');
$rsa = [System.Security.Cryptography.RSA]::Create() $rsa = [System.Security.Cryptography.RSA]::Create()

6
data/features/client-id-for-app.yml Normal file
View File

@@ -0,0 +1,6 @@
# Reference: #14091
versions:
fpt: '*'
ghec: '*'
ghes: '>=3.18'