diff --git a/src/site/apt/githubappappinsttokenauth.apt b/src/site/apt/githubappappinsttokenauth.apt new file mode 100644 index 0000000000..44885ddb73 --- /dev/null +++ b/src/site/apt/githubappappinsttokenauth.apt @@ -0,0 +1,28 @@ +Authenticating as an installation + + In order to authenticate to GitHub as an installation of your GitHub App, you must use the App Installation Token + authentication mechanism. This can be achieved with by creating a <<>> instance like this: + ++-----+ +GitHub githubAuthAsInst = new GitHubBuilder() + .withAppInstallationToken(appInstallationToken.getToken()) + .build(); ++-----+ + +How do I create an App Installation Token? + + Assuming that you followed the {{{/githubappjwtauth.html} GitHub App Authentication via JWT token guide}} then you + can create the App Installation Token like this: + ++-----+ +String jwtToken = createJWT("44435", 600000); //sdk-github-api-app-test +GitHub gitHubApp = new GitHubBuilder().withJwtToken(jwtToken).build(); +GHAppInstallation appInstallation = gitHubApp.getApp().getInstallationById(111111); // Installation Id + +Map permissions = new HashMap<>(); +permissions.put("pull_requests", GHPermissionType.WRITE); + +GHAppInstallationToken appInstallationToken = appInstallation + .createToken(permissions) + .create(); ++-----+ diff --git a/src/site/apt/githubappflow.apt b/src/site/apt/githubappflow.apt new file mode 100644 index 0000000000..fe786eaa62 --- /dev/null +++ b/src/site/apt/githubappflow.apt @@ -0,0 +1,41 @@ +GitHub App Auth Flow + + GitHub Apps are commonly mistaken for OAuth Apps due to their similarities but understanding the differences between + them will help you decide which kind of app you want to create. + + In a nutshell, an OAuth App acts as a GitHub user, whereas a GitHub App uses its own identity when installed on an + organization or on repositories within an organization. For a comprehensive comparision please refer to the official + GitHub {{{https://developer.github.com/apps/differences-between-apps/}documentation}}. + + For this guide, we are going assume that you are using a GitHub App. + +Overview + + Assuming that your GitHub app has already been installed on either a user or an organization, the programmatic flow + the developer must follow in order to be able to authenticate on their behalf is: + +[images/GitHub_App_Auth_Flow.jpg] GitHub_App_Auth_Flow + + Multiple <<>> instances will have to be created and each of them will be using a different authentication + mechanism. Some actions are only accessible if you are authenticated as a GitHub App while others will only be + possible if you are authenticated on behalf of a user or org. + +Prerequisites + + In order to follow this guide, you must have: + + * A GitHub App created as described {{{https://developer.github.com/apps/building-github-apps/creating-a-github-app/}here}} + + * A Private Key must be configured in your GitHub App as described {{{https://developer.github.com/apps/building-github-apps/authenticating-with-github-apps/#generating-a-private-key}here}} + + * A User or an organisation that has already installed your GitHub App as described {{{https://developer.github.com/apps/installing-github-apps/}here}} + + [] + +What next? + + * Authenticating as a GitHub App via the {{{/githubappjwtauth.html}JWT Authentication}} + + * Authenticating as an installation via the {{{/githubappappinsttokenauth.html}App Installation Token}} + + [] diff --git a/src/site/apt/githubappjwtauth.apt b/src/site/apt/githubappjwtauth.apt new file mode 100644 index 0000000000..2a600d4e19 --- /dev/null +++ b/src/site/apt/githubappjwtauth.apt @@ -0,0 +1,135 @@ +GitHub App Authentication via JWT token + + 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 <<>> instance like this: + ++-----+ +GitHub github = new GitHubBuilder().withJwtToken("my_jwt_token").build(); ++-----+ + + Authenticating as a GitHub App lets you do a couple of things: + + * You can retrieve high-level management information about your GitHub App. + + * You can request access tokens for an installation of the app. + + [] + +Where do I get the JWT token from? + + To generate the JWT token required to authenticate as a GitHub app you have to: + + * Sign the JWT token using the private key you configured on your GitHub app as described {{{https://developer.github.com/apps/building-github-apps/authenticating-with-github-apps/#generating-a-private-key}here}} + + * Encode it using the <<>> algorithm. + + [] + + GitHub checks that the request is authenticated by verifying the token with the app's stored public key. + +Converting the private key into a Java friendly format + + <> GitHub let's you download the GitHub App private key in the <<>> format which isn't natively supported + by the JVM unless you leverage a third-party library such as {{{https://www.bouncycastle.org/}BouncyCastle}}. In this + guide we will convert it to <<>> using the <<>> utility. + ++-----+ +openssl pkcs8 -topk8 -inform PEM -outform DER -in ~/github-api-app.private-key.pem -out ~/github-api-app.private-key.der -nocrypt ++-----+ + +How can I generate the JWT token? + + Once you have the private key converted to the <<>> format, you will need 2 more things before you are able to + generate JWT tokens: + + <> + + You can obtain the GitHub App Id from your app settings webpage as shown below: + +[images/Github_App_Id.png] Github_App_Id + + <> + + In order to generate the JWT, you will have to likely use a JWT library. + In this guide we will use {{{https://github.com/jwtk/jjwt}jjwt}} to that matter. + + Having said that, add on your <<>> the following dependencies: + ++-----+ + + io.jsonwebtoken + jjwt-api + 0.10.5 + + + io.jsonwebtoken + jjwt-impl + 0.10.5 + runtime + + + io.jsonwebtoken + jjwt-jackson + 0.10.5 + runtime + ++-----+ + + + Now we have everything we need so let's generate the JWT token: + ++-----+ +static PrivateKey get(String filename) throws Exception { + byte[] keyBytes = Files.toByteArray(new File(filename)); + + PKCS8EncodedKeySpec spec = new PKCS8EncodedKeySpec(keyBytes); + KeyFactory kf = KeyFactory.getInstance("RSA"); + 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("github-api-app.private-key.der"); + + //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 > 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("44435", 600000); //sdk-github-api-app-test + GitHub gitHubApp = new GitHubBuilder().withJwtToken(jwtToken).build(); +} ++-----+ + +How do I get a specific app installation? + ++-----+ +String jwtToken = createJWT("44435", 600000); //sdk-github-api-app-test +GitHub gitHubApp = new GitHubBuilder().withJwtToken(jwtToken).build(); +GHAppInstallation appInstallation = gitHubApp.getApp().getInstallationById(111111); // Installation Id ++-----+ + +What next? + + * Authenticating as an installation via the {{{/githubappappinsttokenauth.html}App Installation Token}} + + [] diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt index e76dd4710b..98073fd56e 100644 --- a/src/site/apt/index.apt +++ b/src/site/apt/index.apt @@ -93,10 +93,10 @@ jwt=my_jwt_token +-----+ // if you are using the default configuration file -GitHub github = new GitHubBuilder().fromPropertyFile().build(); +GitHub github = GitHubBuilder.fromPropertyFile().build(); // if you need to use a separate configuration file -GitHub github = new GitHubBuilder().fromPropertyFile("location/my_custom_github.properties").build(); +GitHub github = GitHubBuilder.fromPropertyFile("location/my_custom_github.properties").build(); +-----+ * Environmental variables @@ -132,7 +132,7 @@ export GITHUB_JWT=my_jwt_token Once exported, you can obtain a <<>> instance using: +-----+ -GitHub github = new GitHubBuilder().fromEnvironment().build(); +GitHub github = GitHubBuilder.fromEnvironment().build(); +-----+ @@ -148,7 +148,7 @@ Pluggable HTTP client +-----+ Cache cache = new Cache(cacheDirectory, 10 * 1024 * 1024); // 10MB cache -GitHub gitHub = GitHubBuilder.fromCredentials() +GitHub gitHub = GitHubBuilder.fromEnvironment() .withConnector(new OkHttpConnector(new OkUrlFactory(new OkHttpClient().setCache(cache)))) .build(); +-----+ diff --git a/src/site/resources/images/GitHub_App_Auth_Flow.jpg b/src/site/resources/images/GitHub_App_Auth_Flow.jpg new file mode 100644 index 0000000000..a2bb6f3d82 Binary files /dev/null and b/src/site/resources/images/GitHub_App_Auth_Flow.jpg differ diff --git a/src/site/resources/images/Github_App_Id.png b/src/site/resources/images/Github_App_Id.png new file mode 100644 index 0000000000..3e86ee04bb Binary files /dev/null and b/src/site/resources/images/Github_App_Id.png differ diff --git a/src/site/site.xml b/src/site/site.xml index 3553fd23bb..e8907107f1 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -10,15 +10,21 @@ 1.2 - - - + + + + + + + + +