Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Provide easy alternative to create App JWT token #2937

Merged
merged 5 commits into from
Jun 24, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 37 additions & 1 deletion docs/github-apps.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,43 @@ That concludes the walkthrough!
### A Note on JWT Tokens
Octokit.net aims to have no external dependencies, therefore we do not currently have the ability to generate/sign JWT tokens for you, and instead expect that you will pass in the appropriately signed JWT token required to authenticate the `GitHubApp`.

Luckily one of our contributors [@adriangodong](https://github.com/adriangodong) has created a library `GitHubJwt` ( [GitHub](https://github.com/adriangodong/githubjwt) | [NuGet](https://www.nuget.org/packages/githubjwt) ) which you can use as per the following example.
In order to create the token, you can create it manually using the following snippet.

``` csharp
// Have these using statements in your file
// using System.IdentityModel.Tokens.Jwt
// using System.Security.Claims
// using System.Security.Cryptography

var rsaPrivateKey = "-----BEGIN R..."; // The RSA private key content itself, read from e.g. a file
var appId = 1; // The GitHub App Id

using var rsa = RSA.Create();
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What's the advantage of the using statement here?

Copy link
Contributor Author

@rasmus rasmus Jun 22, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since the RSA object implements the IDisposable interface, its usually required to invoke the .Dispose() when the object leaves scope and is no longer needed. There could be some resources not managed by the runtime that needs cleaning up. I haven't decompiled the code to see what's actually there. The syntax for declaring using without braces was made available in .NET 8.

rsa.ImportFromPem(rsaPrivateKey);
var signingCredentials = new SigningCredentials(new RsaSecurityKey(rsa), SecurityAlgorithms.RsaSha256)
{
CryptoProviderFactory = new CryptoProviderFactory
{
CacheSignatureProviders = false
}
};

var now = DateTime.UtcNow;
var expiresAt = now + TokenLifetime;
var jwt = new JwtSecurityToken(
notBefore: now,
expires: now + TimeSpan.FromMinutes(10),
signingCredentials: signingCredentials,
claims: new[]
{
new Claim("iat", new DateTimeOffset(now).ToUnixTimeSeconds().ToString(), ClaimValueTypes.Integer),
new Claim("iss", appId.ToString(), ClaimValueTypes.Integer),
}
);
var token = new JwtSecurityTokenHandler().WriteToken(jwt);
```

Alternatively, one of our contributors [@adriangodong](https://github.com/adriangodong) has created a library `GitHubJwt` ([GitHub](https://github.com/adriangodong/githubjwt) | [NuGet](https://www.nuget.org/packages/githubjwt)) which you can use as per the following example.

``` csharp
// Use GitHubJwt library to create the GitHubApp Jwt Token using our private certificate PEM file
Expand Down
Loading