improve documentation and error handling of KeyFlow and Configuration

Author: marceljk

core/src/main/java/cloud/stackit/sdk/core/KeyFlowAuthenticator.java

@@ -1,32 +1,42 @@
 package cloud.stackit.sdk.core;
 
+import cloud.stackit.sdk.core.config.Configuration;
 import cloud.stackit.sdk.core.model.ServiceAccountKey;
 import com.auth0.jwt.JWT;
 import com.auth0.jwt.algorithms.Algorithm;
 import com.google.gson.Gson;
+import com.google.gson.JsonSyntaxException;
 import com.google.gson.annotations.SerializedName;
 import okhttp3.*;
 
 import java.io.IOException;
 import java.io.InputStreamReader;
 import java.net.HttpURLConnection;
 import java.nio.charset.StandardCharsets;
+import java.security.NoSuchAlgorithmException;
 import java.security.interfaces.RSAPrivateKey;
+import java.security.spec.InvalidKeySpecException;
 import java.util.Date;
 import java.util.HashMap;
 import java.util.Map;
 import java.util.UUID;
 import java.util.concurrent.TimeUnit;
 
+/**
+ * KeyFlowAuthenticator handles the Key Flow Authentication based on the Service Account Key.
+ */
 public class KeyFlowAuthenticator {
     private final String REFRESH_TOKEN = "refresh_token";
     private final String ASSERTION = "assertion";
+    private final String DEFAULT_TOKEN_ENDPOINT = "https://service-account.api.stackit.cloud/token";
+    private final long DEFAULT_TOKEN_LEEWAY = 60;
 
     private final OkHttpClient httpClient;
     private final ServiceAccountKey saKey;
     private KeyFlowTokenResponse token;
     private final Gson gson;
     private final String tokenUrl;
+    private long tokenLeewayInSeconds = DEFAULT_TOKEN_LEEWAY;
 
     private static class KeyFlowTokenResponse {
         @SerializedName("access_token")
@@ -41,23 +51,38 @@ private static class KeyFlowTokenResponse {
         private String tokenType;
 
         public boolean isExpired() {
-            return expiresIn < new Date().toInstant().minusSeconds(60).getEpochSecond();
+            return expiresIn < new Date().toInstant().getEpochSecond();
         }
 
         public String getAccessToken() {
             return accessToken;
         }
     }
 
-    public KeyFlowAuthenticator(ServiceAccountKey saKey) {
+    /**
+     * Creates the initial service account and refreshes expired access token.
+     * @param cfg Configuration to set a custom token endpoint and the token expiration leeway.
+     * @param saKey Service Account Key, which should be used for the authentication
+     * @throws InvalidKeySpecException Throws, when the private key in the service account can not be parsed
+     * @throws IOException Throws, when on unexpected responses from the key flow
+     */
+    public KeyFlowAuthenticator(Configuration cfg, ServiceAccountKey saKey) throws InvalidKeySpecException, IOException {
         this.saKey = saKey;
         this.gson = new Gson();
         this.httpClient = new OkHttpClient.Builder()
                 .connectTimeout(10, TimeUnit.SECONDS)
                 .writeTimeout(10, TimeUnit.SECONDS)
                 .readTimeout(30, TimeUnit.SECONDS)
                 .build();
-        this.tokenUrl = "https://service-account.api.stackit.cloud/token";
+        if (cfg.getTokenCustomUrl() != null && !cfg.getTokenCustomUrl().trim().isEmpty()) {
+            this.tokenUrl = cfg.getTokenCustomUrl();
+        } else {
+            this.tokenUrl = DEFAULT_TOKEN_ENDPOINT;
+        }
+        if (cfg.getTokenExpirationLeeway() != null && cfg.getTokenExpirationLeeway() > 0) {
+            this.tokenLeewayInSeconds = cfg.getTokenExpirationLeeway();
+        }
+
         createAccessToken();
     }
 
@@ -68,26 +93,46 @@ public synchronized String getAccessToken() throws IOException {
         return token.getAccessToken();
     }
 
-    private void createAccessToken() {
+    /**
+     * Creates the inital accessToken and stores it in `this.token`
+     * @throws InvalidKeySpecException can not parse private key
+     * @throws IOException request for access token failed
+     * @throws JsonSyntaxException parsing of the created access token failed
+     */
+    private void createAccessToken() throws InvalidKeySpecException, IOException, JsonSyntaxException {
         String grant = "urn:ietf:params:oauth:grant-type:jwt-bearer";
-        String assertion = generateSelfSignedJWT();
+        String assertion;
+        try {
+            assertion = generateSelfSignedJWT();
+        } catch (NoSuchAlgorithmException e) {
+            throw new RuntimeException("could not find required algorithm for jwt signing. This should not happen and should be reported on https://github.com/stackitcloud/stackit-sdk-java/issues", e);
+        }
         try(Response response = requestToken(grant, assertion).execute()) {
             parseTokenResponse(response);
         } catch (IOException | ApiException e) {
-            e.printStackTrace();
+            throw new IOException("request for access token failed", e);
+        } catch (JsonSyntaxException e) {
+            throw new JsonSyntaxException("parsing access token failed", e);
         }
     }
 
-    private synchronized void createAccessTokenWithRefreshToken() throws IOException {
+    /**
+     * Creates a new access token with the existing refresh token
+     * @throws IOException request for new access token failed
+     * @throws JsonSyntaxException can not parse new access token
+     */
+    private synchronized void createAccessTokenWithRefreshToken() throws IOException, JsonSyntaxException {
         String refreshToken = token.refreshToken;
         try (Response response = requestToken(REFRESH_TOKEN, refreshToken).execute()) {
             parseTokenResponse(response);
-        } catch (ApiException e) {
-            e.printStackTrace();
+        } catch (IOException | ApiException e) {
+            throw new IOException("request for new access token failed", e);
+        } catch (JsonSyntaxException e) {
+            throw new JsonSyntaxException("parsing refreshed access token failed", e);
         }
     }
 
-    private synchronized void parseTokenResponse(Response response) throws ApiException {
+    private synchronized void parseTokenResponse(Response response) throws ApiException, JsonSyntaxException {
         if (response.code() != HttpURLConnection.HTTP_OK) {
             String body = null;
             if (response.body() != null) {
@@ -97,22 +142,23 @@ private synchronized void parseTokenResponse(Response response) throws ApiExcept
             throw new ApiException(response.message(), response.code(), response.headers().toMultimap(), body);
         }
         if (response.body() == null) {
-            throw new ApiException("body from token creation is null");
+            throw new JsonSyntaxException("body from token creation is null");
         }
 
-        token = gson.fromJson(new InputStreamReader(response.body().byteStream(), StandardCharsets.UTF_8), KeyFlowTokenResponse.class);
-        token.expiresIn = JWT.decode(token.accessToken).getExpiresAt().toInstant().getEpochSecond();
-        response.body().close();
+        try {
+            token = gson.fromJson(new InputStreamReader(response.body().byteStream(), StandardCharsets.UTF_8), KeyFlowTokenResponse.class);
+            token.expiresIn = JWT.decode(token.accessToken).getExpiresAt().toInstant().minusSeconds(tokenLeewayInSeconds).getEpochSecond();
+            response.body().close();
+        } catch (JsonSyntaxException e) {
+            throw new JsonSyntaxException("could not parse response of created token", e);
+        }
     }
 
-    private Call requestToken(String grant, String assertion) throws IOException {
+    private Call requestToken(String grant, String assertionValue) throws IOException {
         FormBody.Builder bodyBuilder = new FormBody.Builder();
         bodyBuilder.addEncoded("grant_type", grant);
-        if (grant.equals(REFRESH_TOKEN)) {
-            bodyBuilder.addEncoded(REFRESH_TOKEN, assertion);
-        } else {
-            bodyBuilder.addEncoded(ASSERTION, assertion);
-        }
+        String assertionKey = grant.equals(REFRESH_TOKEN) ? REFRESH_TOKEN : ASSERTION;
+        bodyBuilder.addEncoded(assertionKey, assertionValue);
         FormBody body = bodyBuilder.build();
 
         Request request = new Request.Builder()
@@ -123,14 +169,14 @@ private Call requestToken(String grant, String assertion) throws IOException {
         return httpClient.newCall(request);
     }
 
-    private String generateSelfSignedJWT() {
-        RSAPrivateKey prvKey = saKey.getCredentials().getPrivateKeyParsed();
-        Algorithm algorithm = null;
+    private String generateSelfSignedJWT() throws InvalidKeySpecException, NoSuchAlgorithmException {
+        RSAPrivateKey prvKey;
         try {
-            algorithm  = Algorithm.RSA512(prvKey);
-        } catch (Exception e) {
-            e.printStackTrace();
+            prvKey = saKey.getCredentials().getPrivateKeyParsed();
+        } catch (InvalidKeySpecException e) {
+            throw new InvalidKeySpecException("could not parse private key", e);
         }
+        Algorithm algorithm  = Algorithm.RSA512(prvKey);
 
         Map<String, Object> jwtHeader = new HashMap<>();
         jwtHeader.put("kid", saKey.getCredentials().getKid());