GitHubAuth 1.0.2

GitHub Authentication .NET

The GitHub Authentication is a library that provides classes to facilitate the authentication process to the GitHub REST API.

It contains the fastest way to generate a JWT (JSON Web Token), which is a pre-requisite when authenticating to the GitHub REST API as an Application or an Application Installation.

This library has no dependencies. It is compatible with net6.0 and beyond.

Refer to the API Documentation to have a better understanding of each class and how to use it.

Generating a JWT (JSON Web Token)

In order to generate a JWT, the first thing necessary is a private key. You can generate the private key on GitHub. Check this document for more information.

The token will be in a file with the PEM extension. Store it in a location that your software can access.

For security reasons, never store the PEM file in the repository, even if it is a private repository. Also, never store it in a configuration file.

The simplest way to generate a token is:

// Assuming the application ID is 123456 (you can obtain your application ID in GitHub)
var jwt = new GitHubJwtWithRS256("path/to/pem_file.pem", "123456");
var token = jwt.Token;

The Token property returns the token to be used in the Request Header. Everytime you call the Token property, it will evaluate if the token needs renewal. If it does, then it will automatically renew it.

The JWT used for authenticate with the GitHub REST API needs a header and a payload, which is encrypted using the SHA256 hash algorithm, and signed using RS256.

The token is comprised of a header, a payload, and the signature. Both the header and payload are encoded with Base64Url.

The formula would then be Base64Url(header).Base64Url(payload).signature.

Header

The header should have the algorithm and the type of token.

{
  "typ": "JWT",
  "alg": "RS256"
}

The header is represented by the GitHubJwtHeader class.

Payload

The payload should contain the following claims:

{
  "iat": 1651363200,
  "exp": 1651363800,
  "iss": "123456"
}

The time is calculated using the number of seconds since January 1st 1970 (also known as Epoch).

The payload is represented by the GitHubJwtPayload class. The fields IssuedAt and ExpiresAt are stored as DateTime fields, however, when the JSON is generated, the system automatically converts the DateTime value into the proper numeric value, as expected by the API.

Authenticating with the AppAuthenticator

This library contains the class AppAuthenticator to facilitate the authentication process. It exposes methods to perform the authentication process and retrieve the necessary authentication data..

Users can retrieve the token any time by calling the GetToken<T>(T input) method. It automatically renews the token if necessary.

// Assuming the application ID is 123456 (you can obtain your application ID in GitHub)
var jwt = new GitHubJwtWithRS256("path/to/pem_file.pem", "123456");
var authenticator = new AppAuthenticator(jwt);

// Assuming the App Installation ID is 350000
var appInstallationId = 350000;
var authData = authenticator.GetToken(appInstallationId);

Console.WriteLine(authData.Token);  // this will print the token
Console.WriteLine(authData.Mode);   // this will print wether to use 'Token' or 'Bearer'

Benchmarks

The method to generate the JWT in this library is very simplified and optimized. Comparing it with another Nuget package yielded the following results:

The comparison was made using the BenchmarkDotNet library