iframe-proxy | Sunbelt Computer Software

262 lines (183 loc) · 9.11 KB
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
    <title>GitHub API for Java</title>
    <style type="text/css" media="all">
      @import url("./css/maven-base.css");
      @import url("./css/maven-theme.css");
      @import url("./css/1024px.css");
      @import url("./css/site.css");
    </style>
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
      </head>
    <div id="wrap2"><div id="wrap">
    <div id="header">
      <p id="toplinks">Skip to: <a href="#content">Content</a> | <a href="#sidebar">Navigation</a> | <a href="#footer">Footer</a></p>
            <h1 id="bannerLeft">
          <a href="./">
            GitHub API for Java
            </a>
        </h1>
      <p id="slogan">GitHub API for Java</p>
    <div id="breadcrumbs">
      <div class="xright">  </div>
      <div class="clear">
        <hr/>
      </div>
    <div id="sidebar">
      <div id="navcolumn">
          Git Hub API for Java
        </h2><ul>
    <li class="none">
              <a href="index.html">Introduction</a>
        </li>
    <li class="none">
              <a href="https://mvnrepository.com/artifact/org.kohsuke/github-api">Download</a>
        </li>
    <li class="none">
              <a href="https://github.com/hub4j/github-api">Source code</a>
        </li>
    <li class="none">
              <a href="https://groups.google.com/forum/#!forum/github-api">Mailing List</a>
        </li>
          </ul>
          Guides
        </h2><ul>
            <li class="expanded">
              <a href="githubappflow.html">GitHub App Auth Flow</a>
    <li class="none">
              <strong>JWT Authentication</strong>
        </li>
    <li class="none">
              <a href="githubappappinsttokenauth.html">App Installation Token</a>
        </li>
              </ul>
        </li>
    <li class="none">
              <a href="createorglevelresources.html">Working with organizations</a>
        </li>
          </ul>
          References
        </h2><ul>
    <li class="none">
              <a href="apidocs/index.html">Javadoc</a>
        </li>
          </ul>
          Project Documentation
        </h2><ul>
        <li class="collapsed">
              <a href="project-info.html">Project Information</a>
              </li>
        <li class="collapsed">
              <a href="project-reports.html">Project Reports</a>
              </li>
          </ul>
        </div>
    <div id="content">
      <div id="contentBox">
        <section><a id="GitHub_App_Authentication_via_JWT_token"></a>
<h1>GitHub App Authentication via JWT token</h1>
<p>In order to authenticate to GitHub as a GitHub App, you must use the JWT token authentication mechanism. This can be easily achieved with this library by obtaining a <code>GitHub</code> instance like this:</p>
<pre><code>GitHub github = new GitHubBuilder().withJwtToken(&quot;my_jwt_token&quot;).build();</code></pre>
<p>Authenticating as a GitHub App lets you do a couple of things:</p>
<li>You can retrieve high-level management information about your GitHub App.</li>
<li>You can request access tokens for an installation of the app.</li></ul></section><section><a id="Where_do_I_get_the_JWT_token_from.3F"></a>
<h1>Where do I get the JWT token from?</h1>
<p>To generate the JWT token required to authenticate as a GitHub app you have to:</p>
<li>Sign the JWT token using the private key you configured on your GitHub app as described <a class="externalLink" href="https://developer.github.com/apps/building-github-apps/authenticating-with-github-apps/#generating-a-private-key">here</a></li>
<li>Encode it using the <code>RS256</code> algorithm.</li></ul>
<p>GitHub checks that the request is authenticated by verifying the token with the app's stored public key.</p></section><section><a id="Converting_the_private_key_into_a_Java_friendly_format"></a>
<h1>Converting the private key into a Java friendly format</h1>
<p><b>Note:</b> GitHub let's you download the GitHub App private key in the <code>PEM</code> format which isn't natively supported by the JVM unless you leverage a third-party library such as <a class="externalLink" href="https://www.bouncycastle.org/">BouncyCastle</a>. In this guide we will convert it to <code>DER</code> using the <code>openssl</code> utility.</p>
<pre><code>openssl pkcs8 -topk8 -inform PEM -outform DER -in ~/github-api-app.private-key.pem -out ~/github-api-app.private-key.der -nocrypt</code></pre></section><section><a id="How_can_I_generate_the_JWT_token.3F"></a>
<h1>How can I generate the JWT token?</h1>
<p>Once you have the private key converted to the <code>DER</code> format, you will need 2 more things before you are able to generate JWT tokens:</p>
<p><b>GitHub App Id:</b></p>
<p>You can obtain the GitHub App Id from your app settings webpage as shown below:</p><figure><img src="images/Github_App_Id.png" /><figcaption>Github_App_Id</figcaption></figure>
<p><b>JWT library:</b></p>
<p>In order to generate the JWT, you will have to likely use a JWT library. In this guide we will use <a class="externalLink" href="https://github.com/jwtk/jjwt">jjwt</a> to that matter.</p>
<p>Having said that, add on your <code>pom.xml</code> the following dependencies:</p>
<pre><code>&lt;dependency&gt;
  &lt;groupId&gt;io.jsonwebtoken&lt;/groupId&gt;
  &lt;artifactId&gt;jjwt-api&lt;/artifactId&gt;
  &lt;version&gt;0.10.5&lt;/version&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
  &lt;groupId&gt;io.jsonwebtoken&lt;/groupId&gt;
  &lt;artifactId&gt;jjwt-impl&lt;/artifactId&gt;
  &lt;version&gt;0.10.5&lt;/version&gt;
  &lt;scope&gt;runtime&lt;/scope&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
  &lt;groupId&gt;io.jsonwebtoken&lt;/groupId&gt;
  &lt;artifactId&gt;jjwt-jackson&lt;/artifactId&gt;
  &lt;version&gt;0.10.5&lt;/version&gt;
  &lt;scope&gt;runtime&lt;/scope&gt;
&lt;/dependency&gt;</code></pre>
<p>Now we have everything we need so let's generate the JWT token:</p>
<pre><code>static PrivateKey get(String filename) throws Exception {
  byte[] keyBytes = Files.toByteArray(new File(filename));
  PKCS8EncodedKeySpec spec = new PKCS8EncodedKeySpec(keyBytes);
  KeyFactory kf = KeyFactory.getInstance(&quot;RSA&quot;);
  return kf.generatePrivate(spec);
static String createJWT(String githubAppId, long ttlMillis) throws Exception {
  //The JWT signature algorithm we will be using to sign the token
  SignatureAlgorithm signatureAlgorithm = SignatureAlgorithm.RS256;
  long nowMillis = System.currentTimeMillis();
  Date now = new Date(nowMillis);
  //We will sign our JWT with our private key
  Key signingKey = get(&quot;github-api-app.private-key.der&quot;);
  //Let's set the JWT Claims
  JwtBuilder builder = Jwts.builder()
          .setIssuedAt(now)
          .setIssuer(githubAppId)
          .signWith(signingKey, signatureAlgorithm);
  //if it has been specified, let's add the expiration
  if (ttlMillis &gt; 0) {
    long expMillis = nowMillis + ttlMillis;
    Date exp = new Date(expMillis);
    builder.setExpiration(exp);
  //Builds the JWT and serializes it to a compact, URL-safe string
  return builder.compact();
public static void main(String[] args) throws Exception {
  String jwtToken = createJWT(&quot;44435&quot;, 600000); //sdk-github-api-app-test
  GitHub gitHubApp = new GitHubBuilder().withJwtToken(jwtToken).build();
}</code></pre></section><section><a id="How_do_I_get_a_specific_app_installation.3F"></a>
<h1>How do I get a specific app installation?</h1>
<pre><code>String jwtToken = createJWT(&quot;44435&quot;, 600000); //sdk-github-api-app-test
GitHub gitHubApp = new GitHubBuilder().withJwtToken(jwtToken).build();
GHAppInstallation appInstallation = gitHubApp.getApp().getInstallationById(111111); // Installation Id</code></pre></section><section><a id="What_next.3F"></a>
<h1>What next?</h1>
<li>Authenticating as an installation via the <a href="/githubappappinsttokenauth.html">App Installation Token</a></li></ul></section>
      </div>
    <div id="footer">
      <div class="xright">&#169;  
          ${currentYear}
          <a href="http://kohsuke.org/">Kohsuke Kawaguchi</a> and other contributors
  $dateFormat.applyPattern( $format )
  &nbsp;| $i18n.getString( "site-renderer", $locale, "template.lastpublished" ): $dateToday
  &nbsp;| $i18n.getString( "site-renderer", $locale, "template.version" ): 2.0-rc.6
      <div class="clear">
        <hr/>
      </div>
    </div></div>
Sunbelt Computer Software

PL/B Language Development and Support

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Sunbelt Computer Software

PL/B Language Development and Support

Uh oh!

FilesExpand file tree

githubappjwtauth.html

Latest commit

History

githubappjwtauth.html

File metadata and controls
