<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Gerry Kovan on Medium]]></title>
        <description><![CDATA[Stories by Gerry Kovan on Medium]]></description>
        <link>https://medium.com/@gkovan?source=rss-b865c5454e69------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/0*6lp17Jw_VYeWsIfV.jpg</url>
            <title>Stories by Gerry Kovan on Medium</title>
            <link>https://medium.com/@gkovan?source=rss-b865c5454e69------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sat, 21 Nov 2026 14:13:34 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@gkovan/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[The Many Ways to Containerize a Spring Boot application]]></title>
            <link>https://gkovan.medium.com/the-many-ways-to-containerize-a-spring-boot-application-ff05abc3e32f?source=rss-b865c5454e69------2</link>
            <guid isPermaLink="false">https://medium.com/p/ff05abc3e32f</guid>
            <category><![CDATA[spring-boot]]></category>
            <category><![CDATA[docker]]></category>
            <category><![CDATA[jib]]></category>
            <category><![CDATA[containers]]></category>
            <category><![CDATA[java]]></category>
            <dc:creator><![CDATA[Gerry Kovan]]></dc:creator>
            <pubDate>Mon, 16 May 2022 11:53:52 GMT</pubDate>
            <atom:updated>2022-05-16T13:16:12.825Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*KcrjRwxckRvyJe4zLAk4ug.png" /></figure><p>As a Spring Boot Java developer, have you ever wondered about how your application gets containerized in order to be able to run on a Kubernetes cluster. As you would expect, there are numerous ways that this can be done. In this blog post, we will examine the different ways to achieve this.</p><p>The following table shows a summary of the different approaches that we examined. We identify several aspects of each approach/method such as:</p><ul><li>the number of layers in the OCI image</li><li>size of the image in MB</li><li>if a Dockerfile is needed to create the image</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*KwNWHrsIF571yk4nSj9doA.png" /></figure><p>You can clone the example git repo and try out each of the different approaches:</p><pre><a href="https://github.com/gkovan/spring-boot-cloud-native">https://github.com/gkovan/spring-boot-cloud-native</a></pre><h3>Buildpacks</h3><p>The easiest way to containerize a Spring Boot app is to use buildpacks. Since Spring Boot 2.3.0.M1, buildpack support is built directly into the framework. You do not need to create a Dockerfile. Make sure you have the docker daemon running locally.</p><p>Simply run the command:</p><pre>./mvnw spring-boot:build-image</pre><p>A container image gets created where the image name will be the application name from the pom.xml file and the image version will be the version from the pom.xml file.</p><p>Here is the snippet from the pom.xml file:</p><pre><br> &lt;parent&gt;<br>  &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;<br>  &lt;artifactId&gt;spring-boot-starter-parent&lt;/artifactId&gt;<br>  &lt;version&gt;2.6.0&lt;/version&gt;<br>  &lt;relativePath/&gt; &lt;!-- lookup parent from repository --&gt;<br> &lt;/parent&gt;<br> &lt;groupId&gt;com.example&lt;/groupId&gt;<br> &lt;artifactId&gt;rest-service&lt;/artifactId&gt;<br> &lt;version&gt;0.0.1-SNAPSHOT&lt;/version&gt;<br> &lt;name&gt;rest-service&lt;/name&gt;<br> &lt;description&gt;Demo project for Spring Boot&lt;/description&gt;</pre><p>We used spring-boot-starter-parent version 2.6.0 which is greater than 2.3.0 so Buildpack support is included.</p><p>To build the Docker image run the command:</p><pre>./mvnw spring-boot:build-image</pre><p>Command to run the image:</p><pre>docker run -it -p8080:8080 rest-service:0.0.1-SNAPSHOT</pre><p>The image created has 15 layers and its size is 261 MB.</p><h3>Jib</h3><p>Jib builds optimized Docker OCI images for Java applications. It is an open source project developed by Google. Similar to builldpacks, no Dockerfile needs to be created.</p><p>To use Jib, you need to add a maven plugin into your pom.xml file as follows:</p><pre>&lt;plugin&gt;<br>    &lt;groupId&gt;com.google.cloud.tools&lt;/groupId&gt;<br>    &lt;artifactId&gt;jib-maven-plugin&lt;/artifactId&gt;<br>    &lt;version&gt;2.6.0&lt;/version&gt;<br>&lt;/plugin&gt;</pre><p>To build the Docker image run the command:</p><pre>./mvnw compile jib:dockerBuild -Dimage=rest-server-jib:0.0.1</pre><p>Command to run the image:</p><pre>docker run -it -p8080:8080 rest-server-jib:0.0.1</pre><h3>Dockerfile — single stage jdk with fat jar</h3><p>This is the traditional approach where a fat uber jar containing the java artifacts (spring boot libraries, dependency libraries, class files) are packaged into a single jar file using the mvn package command. The developer needs to create the Dockerfile. Here is how this type of Dockerfile looks:</p><pre>FROM adoptopenjdk/openjdk11<br>EXPOSE 8080<br>ARG JAR_FILE=target/rest-service-0.0.1-SNAPSHOT.jar<br>ADD ${JAR_FILE} app.jar<br>ENTRYPOINT [&quot;java&quot;,&quot;-jar&quot;,&quot;/app.jar&quot;]</pre><p>The developer must first run the mvn package command to create the reference jar file target/rest-service-0.0.1-SNAPSHOT.jar that is the uber jar fille containing everything to run the microservice.</p><p>To build the Docker image run the command:</p><pre>docker build -t rest-server-dockerfile:0.0.1 .</pre><p>Command to run the image:</p><pre>docker run -it -p8080:8080 rest-server-dockerfile:0.0.1</pre><p>This approach is not the most efficient. The image size is relatively big at 455 MB. The reason why it is big is because it uses the adoptopenjdk/openjdk11 base image. A jre image as opposed to a jdk image will result in a smaller container image size. Another reason why this approach is not efficient is because the resulting Docker image has only 4 layers, where one of the layers consists of the uber jar. The line in the Dockerfile that adds the uber jar file layer to the Docker image is <strong><em>ADD ${JAR_FILE} app.jar</em></strong>. Therefore, when a single java file changes, the java application needs to be rebuilt (all spring boot libraries, dependencies, app source files), a new fat jar needs to be created and then a new image needs to be created with the new fat jar layer.</p><h3>Dockerfile — single stage jre with fat jar</h3><p>This approach improves the efficiency relative to the previous approach by using a JRE base image as opposed to a jdk base image. The Dockerfile now looks like this:</p><pre>FROM adoptopenjdk:11-jre-hotspot<br>EXPOSE 8080<br>ARG JAR_FILE=target/rest-service-0.0.1-SNAPSHOT.jar<br>ADD ${JAR_FILE} app.jar<br>ENTRYPOINT [&quot;java&quot;,&quot;-jar&quot;,&quot;/app.jar&quot;]</pre><p>The first line in the file specified the base image and we are now using the adoptopenjdk:11-jre-hotspot base image. The jre base image only includes the Java runtime components as opposed to all the utility programs included in the jdk which results in a smaller overall image size.</p><p>The developer must first run the mvn package command to create the reference jar file target/rest-service-0.0.1-SNAPSHOT.jar that is the uber jar fille containing everything to run the microservice.</p><p>To build the Docker image run the command:</p><pre>docker build -f Dockerfile.jre -t rest-server-dockerfile-jre:0.0.1 .</pre><p>Command to run the image:</p><pre>docker run -it -p8080:8080 rest-server-dockerfile-jre:0.0.1</pre><p>The image size is now 262 MB (193 MB smalller than the previous example).</p><p>This approach still uses the fat jar file so there is additional room to improve efficiency.</p><h3>Dockerfile — multistaged jre layered</h3><p>This approach introduces several new techniques. The first is a two staged Dockerfile, where the first stage is responsible for building the java artifact and creating the layers of the java appllication such as dependencies, spring-boot dependencies and application code. The second stage is responsible for creating the actual Docker image.</p><p>The Dockerfile for this approach looks like this:</p><pre># STAGE 1</pre><pre>FROM adoptopenjdk/maven-openjdk11 as builder<br>WORKDIR application</pre><pre>COPY mvnw .<br>COPY .mvn .mvn<br>COPY pom.xml .<br>COPY src src</pre><pre>RUN ./mvnw install -DskipTests<br>RUN java -Djarmode=layertools -jar target/rest-service-0.0.1-SNAPSHOT.jar extract</pre><pre># STAGE 2</pre><pre>FROM adoptopenjdk:11-jre-hotspot<br>WORKDIR application<br>COPY --from=builder application/dependencies/ ./<br>COPY --from=builder application/spring-boot-loader/ ./<br>COPY --from=builder application/snapshot-dependencies/ ./<br>COPY --from=builder application/application/ ./<br>ENTRYPOINT [&quot;java&quot;, &quot;org.springframework.boot.loader.JarLauncher&quot;]</pre><p>To build the Docker image, run the command:</p><pre>docker build -f Dockerfile.multistage-layered -t rest-server-dockerfile-multistage-layered:0.0.1 .</pre><p>Command to run the image:</p><pre>docker run -it -p8080:8080 rest-server-dockerfile-multistage-layered:0.0.1</pre><p>This approach uses a maven image in Stage 1. Therefore, you do not need to have maven installed on your machine to run the maven build commands.</p><p>This approach uses a jre base image in Stage 2. Furthermore it uses layers as opposed to a fat jar.</p><p>There are four layers consisting of the following:</p><ul><li>java dependencies</li><li>Spring Boot loader</li><li>snapshot dependencies</li><li>application code</li></ul><p>These four dependencies are organized in order of least likely to change. Naturally, the application code is ordered last since it changes the most often. Therefore, when application code changes, only the java files that have changed need to be compiled and added to the new image during a build. The docker build engine can use the cached layers created from previous build to reuse the other layers. The total number of layers for the resulting Docker image is 8 compared to 4 for the other approaches that used a fat jar approach. This speeds up build and image creation time. Since the base image is a jre image, the resulting image is still small at 262 MB.</p><h3>Summary</h3><p>In this blog post, we examined several ways to build a docker container image for a Spring Boot application. In a future blog posts, I will discuss the pros and cons of each approach and discuss when to use each approach. I will also compare build times for each approach. In yet another future blog post, I will discuss the many ways you can deploy and run a Spring Boot container image in a Kubernetes cluster.</p><p>The git repo for this example is: <a href="https://github.com/gkovan/spring-boot-cloud-native">https://github.com/gkovan/spring-boot-cloud-native</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=ff05abc3e32f" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[OpenShift Pod Scheduling for a Highly Available Architecture on AWS]]></title>
            <link>https://gkovan.medium.com/openshift-and-kubernetes-pod-scheduling-for-a-highly-available-architecture-1dd87270ed32?source=rss-b865c5454e69------2</link>
            <guid isPermaLink="false">https://medium.com/p/1dd87270ed32</guid>
            <dc:creator><![CDATA[Gerry Kovan]]></dc:creator>
            <pubDate>Tue, 02 Nov 2021 04:43:28 GMT</pubDate>
            <atom:updated>2021-11-02T21:53:14.092Z</atom:updated>
            <content:encoded><![CDATA[<p>The project I am currently working on requires an application to be deployed using a highly available architecture running on an OpenShift cluster deployed on the AWS cloud.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*l-IvAox6Bmv7BIUvJVZr3g.jpeg" /></figure><p>Our OpenShift cluster is deployed in the us-east-1 AWS region and the cluster has six worker nodes spread across three availability zones as shown in the diagram below.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*oz2niICKsjNeXbRYtaFHRg.png" /><figcaption>Six OpenShift worker nodes dedployed in the us-east-1 AWS region</figcaption></figure><p>There are many aspects to consider when designing a highly available application that runs in a OpenShift cluster. One of them involves pod scheduling. To achieve application high availability and resiliency, you want to have several pods running the application and the pods should be located in different availability zones. The application should be fully operational in the event of pod failure, node failure or even an availability zone failure.</p><p>We examined three pod schedulers available on OpenShift:</p><ul><li>default</li><li>pod anti-affinity preferred</li><li>pod anti-affinity required</li></ul><p>We scaled out our application from one to six pods and observed the pod placement.</p><h3><strong>Default Scheduler</strong></h3><p>The <strong>default</strong> pod placement algorithm produced the following pod placement:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*aX1gpyFHJ5GgUZJH76Rzvw.png" /><figcaption>Pod placement for six pods using default scheduler</figcaption></figure><p>Each pod is labeled according to the order the pod was created in. So “pod 1” was created first, “pod 2” was created second and so on. We observed that the default algorithm did a pretty good job of placing pods across the three availability zones but did not place pods in all the worker nodes. The first three pods were spread across the three AZ’s and the next three were also placed across the three AZ’s. However only three of the six nodes were used.</p><h3><strong>Pod Anti-Affinity Preferred Scheduler</strong></h3><p>The <strong>pod anti-affinity preffered</strong> scenario produced the following result:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*8xWpRjk9u6AWUHgfsAWMvA.png" /><figcaption>Pod placement for six pods using “pod anti-affinity preferred” scheduler</figcaption></figure><p>The pod anti-affinity preferred scheduler attemps to prevent a pod to be placed on the same node as pods with the same label.</p><p>As the diagram above shows, the first three pods were placed on three unique nodes across the three availability zones which is good. The fourth pod was placed on a fourth unique node however pods five and six were placed on a node that already had a running pod. Two of the nodes never got picked by the scheduler as other criteria are used such as resource availability (i.e. cpu, memory).</p><h3><strong>Pod Anti-Affinity Required Scheduler</strong></h3><p>The <strong>pod anti-affinity required</strong> scenario produced the following result:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*DUsd5Hafoyt4hnTW_pX8Eg.png" /><figcaption>Pod placement for six pods using ‘pod anti-affinity required” scheduler</figcaption></figure><p>This scheduling algorithm will only schedule a pod on a node that does not have a running pod. As the diagram above shows, pods one through six got scheduled across the six unique nodes. From a high availability perspective, it may appear that this is the best option however other important factors can come into play when scheduling a pod such as cpu and memory utilization. For example, using this scheduler a pod can be placed on a node that is experiencing very high cpu utilization just because it meets the anti-affinity scheduling rules.</p><h3><strong>Conclusion</strong></h3><p>We examined three different pod schedulers in order to understand the high availability properties of our application when deployed on an OpenShift cluster with six worker nodes across three availability zones. For our application, the default scheduler was determined to provide a sufficient level of high availability as the scheduler did a good job of locating the pods evenly across the three availaibility zones. The <strong>pod anti-affinity preferred </strong>scheduler was also a good choice as it was able to utilize more of the nodes relative to the default scheduler. The <strong>pod anti-affinity required</strong> scheduler seemed too strict for our purposes and it could end up lowering the high availability properties of the application with its narrow focus on scheduling only based on the anti affinity criteria.</p><h3>Appendix</h3><p><strong>Deployment manifest for the “pod anti-affinity preferred” scenario</strong></p><pre>apiVersion: apps/v1<br>kind: Deployment<br>metadata:<br>  name: httpd-gk-anti-affinity-preferred<br>  namespace: gktest<br>spec:<br>  selector:<br>    matchLabels:<br>      app: httpd-gk<br>  replicas: 1<br>  template:<br>    metadata:<br>      labels:<br>        app: httpd-gk<br>    spec:<br><strong>      affinity:<br>        podAntiAffinity:<br>          preferredDuringSchedulingIgnoredDuringExecution:<br>          - weight: 100<br>            podAffinityTerm:<br>              labelSelector:<br>                matchExpressions:<br>                - key: name<br>                  operator: In<br>                  values:<br>                  - httpd-gk</strong><br>              topologyKey: topology.kubernetes.io/region<br>      containers:<br>        - name: httpd-gk<br>          image: docker.io/gkovan/httpd-example@sha256:76b3a0<br>          ports:<br>            - containerPort: 8080</pre><p><strong>Deployment manifest for the “pod anti-affinity required” scenario</strong></p><pre>apiVersion: apps/v1<br>kind: Deployment<br>metadata:<br>  name: httpd-gk-anti-affinity-required<br>  namespace: gktest<br>spec:<br>  selector:<br>    matchLabels:<br>      app: httpd-gk<br>  replicas: 1<br>  template:<br>    metadata:<br>      labels:<br>        app: httpd-gk<br>    spec:<br>      <strong>affinity:<br>        podAntiAffinity:<br>          requiredDuringSchedulingIgnoredDuringExecution:<br>          - labelSelector:<br>              matchExpressions:<br>              - key: app<br>                operator: In<br>                values:<br>                - httpd-gk<br>            topologyKey: &quot;kubernetes.io/hostname&quot;</strong><br>      containers:<br>        - name: httpd-gk<br>          image: docker.io/gkovan/httpd-example@sha256:76b3a0<br>          ports:<br>            - containerPort: 8080</pre><h3><strong>References:</strong></h3><p><a href="https://docs.openshift.com/container-platform/4.7/nodes/scheduling/nodes-scheduler-pod-affinity.html#nodes-scheduler-pod-affinity-example-antiaffinity_nodes-scheduler-pod-affinity">https://docs.openshift.com/container-platform/4.7/nodes/scheduling/nodes-scheduler-pod-affinity.html#nodes-scheduler-pod-affinity-example-antiaffinity_nodes-scheduler-pod-affinity</a></p><p><a href="https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/">https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=1dd87270ed32" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[A Zero Trust Approach for Securing the Supply Chain of Microservices Packaged as Container Images]]></title>
            <link>https://gkovan.medium.com/a-zero-trust-approach-for-securing-the-supply-chain-of-microservices-packaged-as-container-images-89d2f5b7293b?source=rss-b865c5454e69------2</link>
            <guid isPermaLink="false">https://medium.com/p/89d2f5b7293b</guid>
            <category><![CDATA[zero-trust]]></category>
            <category><![CDATA[supply-chain]]></category>
            <category><![CDATA[microservices]]></category>
            <category><![CDATA[kubernetes]]></category>
            <category><![CDATA[security]]></category>
            <dc:creator><![CDATA[Gerry Kovan]]></dc:creator>
            <pubDate>Mon, 06 Sep 2021 18:51:44 GMT</pubDate>
            <atom:updated>2021-09-06T20:45:32.600Z</atom:updated>
            <content:encoded><![CDATA[<p>Securing the software supply chain has become a top priority for both open source as well as closed source projects. There are many sources in a software supply chain such operating systems and operating system packages/binaries, programming language frameworks and libraries, shell scripts, source code, container images and many others. Since container images are becoming so prevalent with the popularity of the Kubernetes platform, we will address securing container images in this blog.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*c_2lkMmPEQFYfgDdTUwLJQ.png" /></figure><p>A common pattern I have come across in projects that containerize microservices is one in which software development teams would create a “golden” base container image and any microservice created would be built using that golden base image as depicted in the diagram below.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/361/1*v-LGsHqK8AvQJCVQkni4Rg.png" /><figcaption>base image as a basis for microservices</figcaption></figure><p>One of the main reasons development teams adopt this approach is to speed up the build process for building microservice container images. For example:</p><ul><li>Base image has key components such as OS, language frameworks, key libraries, and common code</li><li>Base container image is stored in a secure private container registry close to the rest of the infrastructure therby lowering latency</li></ul><p>This blog will propose a solution on how to secure the supply chain for the pattern described above, specifically focusing on securing the container image supply chain.</p><p>In our scenario, we want to build a Quarkus java microservice called the <strong>quarkus-hello-service</strong> that runs on the <strong>OpenShift Container Platform</strong>. We first create a quarkus base image and then we build and run the quarkus-hello-service microservice.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/424/1*LYXZGvQauSPqicR35iwIzA.png" /><figcaption>quarkus-hello-service container image built from quarkus-base-image</figcaption></figure><p>The key supply chain security requirements that we will address are:</p><ul><li><strong>quarkus-base-image</strong> container image should be digitally signed so that it can be verified by consumers</li><li><strong>quarkus-hello-service</strong> container image is built from the secure and verified <strong>quarkus-base-image</strong></li><li><strong>qaurkus-hello-service</strong> container image should be digitally signed so that it can be verified by consumers</li><li><strong>quarkus-hello-service</strong> microservice should only run on the Kubernetes/OpenShift platform if its image has a valid digital signature.</li><li>Attestation or evidence of the build process</li></ul><h3>Description of the Solution</h3><p>The following diagram shows the key components of the overall solution. The solution leverages new open source tools that have been developed by the <a href="https://www.sigstore.dev/">Sigstore project</a> for digitally signing and verifying container images. The solution also leverages the <a href="https://kyverno.io/">Kyverno</a> policy engine which is a Kubernetes admission controller that has integration with the Sigstore tools to validate container images before allowing them to run on a cluster.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*JCYvVpePUYKDdQM5ehE_6w.png" /><figcaption>Zero trust supply chain security solution for container images</figcaption></figure><p>The <strong>quarkus-base-image Tekton pipeline</strong> fetches the source code from github containing the Dockerfile that has the instructions to build the base image. The instructions specify to use the minimul Red Hat Universal Base Image version 8.3 (ubi8/ubi-minimal:8.3) as well as the Java 11 runtime JDK.</p><pre>FROM registry.access.redhat.com/ubi8/ubi-minimal:8.3</pre><pre>ARG JAVA_PACKAGE=java-11-openjdk-headless</pre><pre>ARG RUN_JAVA_VERSION=1.3.8</pre><pre>ENV LANG=&#39;en_US.UTF-8&#39; LANGUAGE=&#39;en_US:en&#39;</pre><pre># Install java and the run-java script</pre><pre># Also set up permissions for user `1001`</pre><pre>RUN microdnf install curl ca-certificates ${JAVA_PACKAGE} \</pre><pre>&amp;&amp; microdnf update \</pre><pre>&amp;&amp; microdnf clean all \</pre><pre>&amp;&amp; mkdir /deployments \</pre><pre>&amp;&amp; chown 1001 /deployments \</pre><pre>&amp;&amp; chmod &quot;g+rwX&quot; /deployments \</pre><pre>&amp;&amp; chown 1001:root /deployments \</pre><pre>&amp;&amp; curl <a href="https://repo1.maven.org/maven2/io/fabric8/run-java-sh/$%7BRUN_JAVA_VERSION%7D/run-java-sh-$%7BRUN_JAVA_VERSION%7D-sh.sh">https://repo1.maven.org/maven2/io/fabric8/run-java-sh/${RUN_JAVA_VERSION}/run-java-sh-${RUN_JAVA_VERSION}-sh.sh</a> -o /deployments/run-java.sh \</pre><pre>&amp;&amp; chown 1001 /deployments/run-java.sh \</pre><pre>&amp;&amp; chmod 540 /deployments/run-java.sh \</pre><pre>&amp;&amp; echo &quot;securerandom.source=file:/dev/urandom&quot; &gt;&gt; /etc/alternatives/jre/conf/security/java.security</pre><p>The pipeline invokes Tekton tasks that build the docker image and push the image (docker.io/gkovan/quarkus-base-image:1.0) to the specified container repository. <strong>Tekton Chains</strong> is installed in the cluster. <strong>Tekton Chains</strong> observes the Tekton TaskRuns and digitally signs any derived images as well as the TaskRun itself. By signing the TaskRun, undeniable evidence exists on the build details itself such as input parameters, output parameters, and the builld logic. <strong>Tekton Chains</strong> has integration with <strong>Sigstore cosign</strong> tool to sign the container images as well as all the TaskRuns executed. At this point, the signed quarkus-base-image exists in our container registry ready to be used. This base image has a secure mimimal operating system (linux) as well as a JDK 11 runtime.</p><p>The hello service implements a single REST endpoint called “/hello”. The <strong>quarkus-hello-service Tekton pipeline</strong> fetches the source code from github which contains the java Quarkus code as well as the Dockerfile with instructions on how to build the <strong>quarkus-hello-service</strong> image. The pipeline first builds the java code using maven in the <strong>“build source code”</strong> task. The pipeline then proceeds to build the image using the Dockerfile in the repo. The Dockerfile references the <strong>quarkus-base-image</strong> and then copies the Quarkus libraries and application code into the image.</p><pre>FROM docker.io/gkovan/quarkus-base-image:1.0</pre><pre>LABEL base.image=&quot;docker.io/gkovan/quarkus-base-image:1.0&quot;</pre><pre>ENV JAVA_OPTIONS=&quot;-Dquarkus.http.host=0.0.0.0 -Djava.util.logging.manager=org.jboss.logmanager.LogManager&quot;</pre><pre>COPY --chown=1001 target/quarkus-app/lib/ /deployments/lib/</pre><pre>COPY --chown=1001 target/quarkus-app/*.jar /deployments/</pre><pre>COPY --chown=1001 target/quarkus-app/app/ /deployments/app/</pre><pre>COPY --chown=1001 target/quarkus-app/quarkus/ /deployments/quarkus/</pre><pre>EXPOSE 8080</pre><pre>USER 1001</pre><pre>ENTRYPOINT [ &quot;/deployments/run-java.sh&quot; ]</pre><p>The <strong>“build/push docker image”</strong> task then pushes the resulting image (docker.io/gkovan/quarkus-hello-service:1.0) to the image repository. <strong>Tekton chains</strong>, digitally signs the image as well as all the TaskRuns executed in the pipeline. The <strong>“verify base image”</strong> task, validates that the base image <strong>“docker.io/gkovan/quarkus-base-image:1.0”</strong> is signed. The task uses the cosign tool that is part of the Sigstore project to do this validation. The cosign tool has access to the public key (configured as a kubernetes secret) corresponding to the private key that was used to sign the image, to do the validation. Since the base image is part of the supply chain, it is critical that we validate the signature to ensure that it has not been tampered with. The <strong>“deploy”</strong> task in the pipeline deploys the microservice to the OpenShift cluster by applying the appropriate Kubernetes manifest files. All requests to apply kubernetes manifest files go through the kube-apiserver component. The kube-apiserver first checks with all the admission controllers installed in the cluster to see if the request is valid. The Kyverno admission controller has a check-image policy that has been configured to only allow valid images. The policy includes a pattern matching rule for images as well as the public key to validate the images as follows:</p><pre>apiVersion: kyverno.io/v1</pre><pre>kind: ClusterPolicy</pre><pre>metadata:</pre><pre>name: check-image</pre><pre>spec:</pre><pre>  validationFailureAction: enforce</pre><pre>  background: false</pre><pre>  rules:</pre><pre>    - name: check-image</pre><pre>      match:</pre><pre>        resources:</pre><pre>          kinds:</pre><pre>            - Pod</pre><pre>      verifyImages:</pre><pre>      - image: &quot;docker.io/gkovan/*&quot;</pre><pre>        key: |-</pre><pre>        -----BEGIN PUBLIC KEY-----</pre><pre>    MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEtwDUUcAVE4dJj623tCNy9WrYfgJn</pre><pre>gPqTAl4hkXdXMG1jk36OGxzwefjQO7XV37i0kJrWssfggVGxa0GoXryWVw==</pre><pre>        -----END PUBLIC KEY-----</pre><p>If the <strong>quarkus-hello-service</strong> image is not signed or cannot be validated with the specified public key, then the <strong>Kyverno admission controller</strong> will tell the <strong>kube-apiserver</strong> that the request is not valid and the deployment will fail. This ensures that only trusted container images are allowed to run on the cluster providing the runtime security.</p><p><strong>Summary</strong></p><p>This blog discussed a solution for securing the supply chain of a typical microservices project focusing on zero trust for container images. The solution discussed how the container images that are built are signed and verified during the build process. Furthermore, the solution discussed how to ensure only valid and signed container images are allowed to run on the OpenShift/Kubernetes cluster. Another important aspect is to be able to provide attestation and evidence of the build process such as the inputs, outputs and logic to produce and run the software artifacts. The overall solution leveraged tools from the Sigstore project for digitally signing the software container images as well as the Kyverno admission controller for only allowing valid signed images to run on the OpenShift cluster.</p><p>All source code can be found in the following github repos:</p><p>quarkus-base-image: <a href="https://github.com/ztsc/quarkus-base-image">https://github.com/ztsc/quarkus-base-image</a></p><p>quarkus-hello-service: <a href="https://github.com/ztsc/quarkus-hello-service">https://github.com/ztsc/quarkus-hello-service</a></p><p>OpenShift Pipeline/Tekton resources: <a href="https://github.com/ztsc/tekton">https://github.com/ztsc/tekton</a></p><p>Kyverno check-image policy: <a href="https://github.com/ztsc/admission-controller/blob/master/kyverno/check-image-cluster-policy.yaml">https://github.com/ztsc/admission-controller/blob/master/kyverno/check-image-cluster-policy.yaml</a></p><p><strong>Key References</strong>:</p><p><strong>Project Sigstore</strong>, <a href="https://www.sigstore.dev/">https://www.sigstore.dev/</a></p><p><strong>Sigstore cosign tool</strong>, <a href="https://github.com/sigstore/cosign">https://github.com/sigstore/cosign</a></p><p><strong>OpenShift Pipelines/Tekton</strong>, <a href="https://docs.openshift.com/container-platform/4.7/cicd/pipelines/understanding-openshift-pipelines.html">https://docs.openshift.com/container-platform/4.7/cicd/pipelines/understanding-openshift-pipelines.html</a></p><p><strong>Tekton Chains</strong>, <a href="https://github.com/tektoncd/chains">https://github.com/tektoncd/chains</a></p><p><strong>Kyverno</strong>, <a href="https://kyverno.io/">https://kyverno.io/</a></p><p><strong>OpenShift Container Platform</strong>, <a href="https://docs.openshift.com/container-platform/4.7/welcome/index.html">https://docs.openshift.com/container-platform/4.7/welcome/index.html</a></p><p><strong>Quarkus</strong>, <a href="https://quarkus.io/">https://quarkus.io/</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=89d2f5b7293b" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Secure your Spring Boot App using Single Sign On with IBM Security Verify]]></title>
            <link>https://gkovan.medium.com/secure-your-spring-boot-app-using-single-sign-on-with-ibm-security-verify-d89264e4c6e4?source=rss-b865c5454e69------2</link>
            <guid isPermaLink="false">https://medium.com/p/d89264e4c6e4</guid>
            <category><![CDATA[spring-security]]></category>
            <category><![CDATA[ibm-security-verify]]></category>
            <category><![CDATA[jwt]]></category>
            <category><![CDATA[oauth2]]></category>
            <category><![CDATA[spring-boot]]></category>
            <dc:creator><![CDATA[Gerry Kovan]]></dc:creator>
            <pubDate>Thu, 25 Mar 2021 14:59:42 GMT</pubDate>
            <atom:updated>2021-03-31T12:26:03.985Z</atom:updated>
            <content:encoded><![CDATA[<h3>Introduction</h3><p>Security is a critical aspect for both new or existing application. In this blog we will focus on securing a Spring Boot application using Single Sign On with <a href="https://www.ibm.com/products/verify-for-workforce-iam">IBM Security Verify</a> as the Identity Provider.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/924/1*OrIabBRGh-0D5ZkRfOFTvw.png" /></figure><p>For this example, we will use a sample application called My Favorite Foods. The application allows a user to log in and manage (view, add) their favorite foods. Since a users favorite foods is highly private data, only the authenticated and authorized user should be able to see their own favorite foods and nobody else’s. The architecture of the application is as follows:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/836/1*s71mVh_iOfKoaPFLYVxXfQ.png" /></figure><h3><strong>Description of the components</strong></h3><p><strong>IBM Security Verify (ISV)</strong>: Identity provider responsible for authenticating the user, minting tokens and validating tokens. Acts as the OpenID Provider for authentication as well as the Oauth2 Authorization Server. This is a Sotware as a Service product hosted on the IBM cloud.</p><p><strong>Web Client application</strong>: Client application that is configured for users (Resource Owner) to log in via the Identity Provider (ISV). In OpenID Connect and OAuth2 terminology, this component is the Relying Party. Makes requests to the Resource Server to retrieve the favorite foods of the logged in user (Resource Owner). This is a Spring Boot microservice and also serves up the UI web pages using the Spring Thymeleaf framework.</p><p><strong>Favorite Food Resource server</strong>: Application hosting the resources (favorite foods) on behalf of users (Resource Owners). In OpenID Connct and Oauth2 terminology, this component is called the Resource Server. This service is protected and only valid logged in users should be able to access and see their favorite foods.</p><p><strong>Relational DB</strong>: Relational database that stores the favorite foods for users (Resource Owners). For convenience, we are using an H2 database which is embedded inside the resource server microservice.</p><h3>Register the Spring Boot app in IBM Security Verify</h3><p>To setup and run this sample application we need to register an application in IBM Security Verify. The application in Security Verify represents our Spring Boot app. The steps below describe how to set this up:</p><p><strong>Step 1:</strong> Register for a free trial tenant here: <a href="https://www.ibm.com/account/reg/us-en/signup?formid=urx-30041">https://www.ibm.com/account/reg/us-en/signup?formid=urx-30041</a></p><p>Here is a link to the IBM Security getting started guide: <a href="https://docs.verify.ibm.com/verify/docs/guides">https://docs.verify.ibm.com/verify/docs/guides</a></p><p><strong>Step2:</strong> Login to your IBM Security Verify tenant</p><p><strong>Step 3: </strong>Create a custom application</p><p>From hamburger menu (top left corner), select Applications -&gt; click on Add application and select Custom Application.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*cRBXTNCBn0-BvjMoEabP9g.png" /><figcaption>Click on “Add Application” to define a new app in IBM Security Verify</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/592/1*RR5g_IgMQ-47Pk1b7ROGOA.png" /><figcaption>Select “Custom Application” and Click the “Add application” button</figcaption></figure><p>In the “<strong>General”</strong> tab, specify any company name (required field).</p><p>In the <strong>“Sign on”</strong> tab:</p><ul><li>Provide a name for the custom application</li><li>Specify the sign on method to be <strong>“Open ID Connect 1.0”</strong></li><li>Enter the Application URL: <a href="http://localhost:8082/ui/home/"><strong>http://localhost:8082/ui</strong></a></li><li>Specify Grant type of “<strong>Authorization code</strong>”</li><li>Set User consent to “<strong>Do not ask for consent</strong>”</li><li>Specify the value for the redirect URI: <strong>http://localhost:8082/ui/login/oauth2/code/custom</strong></li><li><strong>Uncheck</strong> the “Require proof key for code change (PKCE) verification”</li></ul><p>Note, the Client id and Client secret will be auto generated when the Save button is eventually clicked.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*aeZLvkfdWMN350ObLDRSww.png" /></figure><p>In the <strong>“Sign on”</strong> tab <strong>token settings</strong>, specify JWT as the access token format.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*zD_jyYrNwUQ16PbZ15-OzA.png" /><figcaption>SIgn on token settings configuration</figcaption></figure><p>Note, specifying JWT as the format tells IBM Security Verify to return a JWT token when requesting an access token. Otherwise it will return an Opaque token. A JWT token is required in order to protect the resource servers. The resource servers use the JWT token and validate it. We will discuss more about this a bit later.</p><p>In the <strong>“Sign on”</strong> tab <strong>Scope and Entitlements</strong> section:</p><p>- uncheck “Restrict custom scope”.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/505/1*8FK-AixfZVyt1JBoVq_w3g.png" /><figcaption>Uncheck this checkbox to allow app code to specify custom scopes</figcaption></figure><h3>The Spring Boot Favorite Foods application</h3><p>This section will describe the key components of our Spring Boot application.</p><p><strong>Web Client Application</strong></p><p>Here we list the key spring dependencies required to build and secure the application plus integrate it with IBM Security Verify.</p><pre>&lt;dependency&gt;</pre><pre>  &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;</pre><pre>  &lt;artifactId&gt;<strong>spring-boot-starter-web</strong>&lt;/artifactId&gt;</pre><pre>&lt;/dependency&gt;</pre><pre>&lt;dependency&gt;</pre><pre>  &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;</pre><pre>  &lt;artifactId&gt;<strong>spring-boot-starter-thymeleaf</strong>&lt;/artifactId&gt;</pre><pre>&lt;/dependency&gt;</pre><pre>&lt;dependency&gt;</pre><pre>  &lt;groupId&gt;org.springframework&lt;/groupId&gt;</pre><pre>  &lt;artifactId&gt;<strong>spring-webflux</strong>&lt;/artifactId&gt;</pre><pre>&lt;/dependency&gt;</pre><pre>&lt;dependency&gt;</pre><pre>  &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;</pre><pre>  &lt;artifactId&gt;<strong>spring-boot-starter-oauth2-client</strong>&lt;/artifactId&gt;</pre><pre>&lt;/dependency&gt;</pre><pre>&lt;dependency&gt;</pre><pre>  &lt;groupId&gt;org.thymeleaf.extras&lt;/groupId&gt;</pre><pre>  &lt;artifactId&gt;<strong>thymeleaf-extras-springsecurity5</strong>&lt;/artifactId&gt;</pre><pre>&lt;/dependency&gt;</pre><p>We include the standard <strong>spring-boot-starter-web </strong>and<strong> spring-boot-starter-thymeleaf </strong>dependencies<strong> </strong>for your basic web app to support the UI and REST<strong> </strong>functionality<strong> </strong>within the<strong> </strong>application<strong>. </strong>Since we are using the new WebClient api (instead of traditional RestTemplate) we included<strong> </strong>the<strong> spring-webflux</strong> dependency.</p><p>We add the <strong>spring-boot-starter-oauth2-client </strong>dependency to provide the Spring magic that will integrate with IBM Security Verify (Oauth2 and OIDC Identity provider) in order to perform the authentication and mint the access tokens.</p><p>Once you add the <strong>spring-boot-starter-oauth2-client </strong>dependencies you will need to configure a few things. We create a class called <strong>UISecurityConfig</strong> and override the <strong>configure(HttpSecurity http)</strong> method to configure the filter chain. Here we configure the “/” and “/login” endpoints of the web client app to be open and permitted to all users. This is so all users can get to the main page and the login page of the application without authenticating. The oauth2Login() statement specifies that we want to login using an Oauth2 identity provider, in our case IBM Security Verify (ISV)(we will see shortly how we configure that). Note, that for ISV, we had to specify the <strong>tokenEndpoint().accessTokenResponseClient</strong>(…). If you drill down futher into this code, you will see that we had to create a <strong>CustomAccessTokenResponseConverter</strong> class to convert the token response from ISV as the Spring Security default implementation did not work with ISV.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/c69a0d95d6a7604f238747ee82ac4195/href">https://medium.com/media/c69a0d95d6a7604f238747ee82ac4195/href</a></iframe><p>In order to integrate with IBM Security Verify (ISV), we had to specify <strong>tokenEndpoint().accessTokenResponseClient</strong>(…). If you drill down futher into this code, you will see that we had to create and use a new class <strong>CustomAccessTokenResponseConverter</strong> to convert the token response as the Spring Security default implementation did not work with ISV. The method authorizationCodeTokenResponseClient on line 17 is responsible for calling the token endpoint on the Authorization Server (IBM Security Verify) and returning the token response which contains the JWT access token among other things.</p><p>Here is an example of a token response from IBM Security Verify. The access_token is a JWT token which contains the claims of the logged in user.</p><pre>{</pre><pre>   <strong>&quot;access_token&quot;</strong>: &quot;eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InNlcnZlciJ9.eyJ1bmlxdWVTZWN1cml0eU5hbWUiOiI2NTIwMDE4SFFUIiwiY2xpZW50X2lkIjoiZjNlOTg4OTktNzU4NC00YTM0LWE4NTUtOTEyNjRiOGRlOTdhIiwicmVhbG1OYW1lIjoiY2xvdWRJZGVudGl0eVJlYWxtIiwicHJlZmVycmVkX3VzZXJuYW1lIjoiZ2tvdmFuQGhvdG1haWwuY29tIiwiYXVkIjoiZjNlOTg4OTktNzU4NC00YTM0LWE4NTUtOTEyNjRiOGRlOTdhIiwiZ3JhbnRfdHlwZSI6ImF1dGhvcml6YXRpb25fY29kZSIsImFjciI6InVybjppYm06c2VjdXJpdHk6cG9saWN5OmlkOjEiLCJncmFudF9pZCI6ImVmMjFjNThjLWRiYzktNDgwOC1hODI0LTk2N2RkZjM1YTdhNyIsInVzZXJUeXBlIjoicmVndWxhciIsImF1dGhfdGltZSI6MTYxNjE4NjI3OCwic2NvcGUiOiJyZWFkIGdrIG9wZW5pZCB3cml0ZSIsImp0aSI6InNDQmQ2TDFZaUNlbkJodjJzOHd6NUt4N2lPWEQzVSIsImlzcyI6Imh0dHBzOi8vZ2tvdmFuLnZlcmlmeS5pYm0uY29tL29pZGMvZW5kcG9pbnQvZGVmYXVsdCIsInN1YiI6IjY1MjAwMThIUVQiLCJpYXQiOjE2MTYxODY1NTAsImV4cCI6MTYxNjE5Mzc1MH0.PWJDgTTff5lBrpt7ExOhs5emF8pG1t_3DGihG7k54D7AsxU7otv3QCHm3JlyQ8i9y81LhyurQoKkgAioYr8jK0ET8Wc8mr6k3Dhi502PVAhtLPhIGyy2yI0e_O_HzeWRaWGrdw9gAXx-Al1YX5I6cWVshgfZUCuxOP15XSdXvl28vEP8tHDps7ET4UjVAz_IrM4H6sLIudhIn0JEd3psHRrNdmcWV4Exs_Qk2MLq8T9l0AxG-WZIhuRzba-R-1wlQfLOmgtgBfagtW9124FBxoQGT-FOxBan5un4Nf1Nv1BZjOwJlMJ59owWA4_iV_y-NB_QcBmXpDVbO-Bp068xVg&quot;,</pre><pre><strong>&quot;expires_in&quot;</strong>: 7199,</pre><pre><strong>&quot;grant_id&quot;</strong>: &quot;ef21c58c-dbc9-4808-a824-967ddf35a7a7&quot;,</pre><pre><strong>&quot;id_token&quot;</strong>: &quot;eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InNlcnZlciJ9.eyJhY3IiOiJ1cm46aWJtOnNlY3VyaXR5OnBvbGljeTppZDoxIiwidXNlclR5cGUiOiJyZWd1bGFyIiwic19oYXNoIjoiRWs0TGNnR3dPSTE4Ql9ReGxMbGtYUSIsInVuaXF1ZVNlY3VyaXR5TmFtZSI6IjY1MjAwMThIUVQiLCJkaXNwbGF5TmFtZSI6IkdlcnJ5IEtvdmFuIiwianRpIjoiSll1Z3ZWY3NBelVZd2tGWDN4S2VKQkdTdHhxdnd3IiwicmVhbG1OYW1lIjoiY2xvdWRJZGVudGl0eVJlYWxtIiwibmFtZSI6IkdlcnJ5IEtvdmFuIiwicHJlZmVycmVkX3VzZXJuYW1lIjoiZ2tvdmFuQGhvdG1haWwuY29tIiwibm9uY2UiOiJjeGttY3A2ZmllIiwiZXh0Ijp7InRlbmFudElkIjoiZ2tvdmFuLnZlcmlmeS5pYm0uY29tIn0sImlzcyI6Imh0dHBzOi8vZ2tvdmFuLnZlcmlmeS5pYm0uY29tL29pZGMvZW5kcG9pbnQvZGVmYXVsdCIsImF1ZCI6ImYzZTk4ODk5LTc1ODQtNGEzNC1hODU1LTkxMjY0YjhkZTk3YSIsInN1YiI6IjY1MjAwMThIUVQiLCJpYXQiOjE2MTYxODY1NTAsImV4cCI6MTYxNjE5Mzc1MCwiYXRfaGFzaCI6IjZFOFlCTm9GOHF5SkNPblhpYS15RXcifQ.Ouu1Tt-U0kEzDR8asoMAUQiTqaQL_Vjtn04pICqyCM7rBB3jmOTuAsLIeDsWA7QkKisWTJr5ux4L7unCLf0cRKFuWlEbk-e_XP4QM9boojm9B-GFQue3oDSY4NXTo3dsjnL_IDUhcEWwSwpexpDgrW3wT9vIlvURnj-kqKqaAvX-y3bF89z4nRwBN0R-IzYuw3WuqFdGZLByEVpPl6WdbvXDbQcZWvqoC4tB-n5cN-RZePo2XKbwLZMlpg5fYzOnx6GHinFlrtyXBWcaV7bp5yo_2Y7_ypvnzxAb4_OTUzvLMfXMb_tICLt9dBKllbhruIJIOGz7C6FtbLF-ZlDKMQ&quot;,</pre><pre><strong>&quot;scope&quot;</strong>: &quot;read openid write&quot;,</pre><pre><strong>&quot;token_type&quot;</strong>: &quot;jwt&quot;</pre><pre>}</pre><p>Notice that the value for the token_type field is “jwt”. The default implementation in the Spring Security token response converter expects this field to have the value of “Bearer” and that is why we needed to create our custom implementation.</p><p>Below is the implementation of the <strong>CustomAccessTokenResponseConverter</strong>.</p><p>You will notice that this code does not check/validate the value of the token_type parameter. Instead on line 14, we just hard code the token type to <strong>Bearer</strong> set the other other fields accordingly and return the token response object.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/585fe09fd475594669ed07f2e702f022/href">https://medium.com/media/585fe09fd475594669ed07f2e702f022/href</a></iframe><p>Finally, we need to configure the appropriate Spring Security oauth2 parameters in the application.yml file as shown below:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/024b96dbbeac8c50c34bb7a91a81bd06/href">https://medium.com/media/024b96dbbeac8c50c34bb7a91a81bd06/href</a></iframe><p>In the <strong>spring.security.oauth2.client.registration.custom</strong> namespace, we configure the following properties:</p><p>The client-id and client-secret represent the credentials for the client application to get a token from the authorization server which is IBM Security Verify. We pass in the values from the environment when we start the spring boot client web app. More on this later.</p><p><strong>client-id</strong>: Auto generated by the Application you defined in IBM Security Verify. Value injected from environment when spring boot web app starts.</p><p><strong>client-secret</strong>: Auto generated by the Application you defined in IBM Security Verify. Value injected from environment when spring boot web app starts.</p><p><strong>authorization-grant-type</strong>: Specify <strong>authorization_code</strong> as that is the most secure oauth2 flow for web apps.</p><p><strong>redirect_uri</strong>: This is also known as the callback URI, In the authorization_code flow. During the login process, assuming the user authenticated successfully, the The authorization server (ISV) creates a short lived auth code and responds with an http redirect that the users browser executes in order to exchange the short lived auth code with an access token. The redirect_uri must be registered with the application defined in ISV during the app registration process as described above for security purposes. The redirect uri invokes the web client app (relying party) with the short lived auth code. The web client app, then makes a call to IBM Security Verify tenant token endpoint with the short lived auth code and the full credentials that includes the client id, client secret and several other parameters to get a valid token. The key idea here is that because the web client app is a server component, it can store the sensitive credential (client secret) securely in order to exchange the auth code with a valid access token.</p><p>In the <strong>spring.security.oauth2.client.provider.custom </strong>namespace we configure the following properties:</p><p><strong>authorization-url</strong>: url of the authorization server</p><p><strong>token-uri</strong>: Uri of the token endpoint on the authorization server</p><p><strong>user-info-uri</strong>: Uri of the userinfo endpoint on the authorization server</p><p><strong>issuer-uri</strong>: Defines the base uri of the authorization server.</p><p><strong>jwk-set-uri</strong>: Uri of the JWKS (JSON Web Key Set) endpoint on the authorization server. This endpoint contains the public key counterparts of the private keys which were used to sign the tokens during token minting/creation.</p><p>Note: You will need to replace <a href="https://gkovan.verify.ibm.com/">https://gkovan.verify.ibm.com</a> with your specific IBM Security Verify tenant. You can get a <a href="https://www.ibm.com/account/reg/us-en/signup?formid=urx-30041">trial tenant for free</a>.</p><p><strong>WebClient Configuration</strong></p><p>The web client application is using the Spring Webflux WebClient class to make REST calls to the resource server to get the logged in users favorite foods. The code below shows how the WebClient is configured. Line 4 configures the WebClient to autamically inject the http <strong>Authorization</strong> header containing the <strong>Bearer access token</strong>. Without a valid Bearer access token, the resource server will not execute the request and instead return an HTTP 401 error.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/df7da067675aa1f5df3a987fa363cda2/href">https://medium.com/media/df7da067675aa1f5df3a987fa363cda2/href</a></iframe><p>Below you can see the logs from the web client application showing the http GET request to the resource server. The logs show both the URL and the header which containers the Authorization Bearer token.</p><pre>### WebClient REQUEST: ### GET <a href="http://localhost:8081/sso-resource-server/api/favorite-food">http://localhost:8081/sso-resource-server/api/favorite-food</a></pre><pre>### WebClient HEADER ### Authorization=Bearer eyJhbGciOiJSUzI1...</pre><p><strong>Favorite food resource server</strong></p><p>Now we will see how the resource server that processes the request from the web client application to return the favorite foods of the logged in user.</p><p>The key dependencies in the maven pom file are:</p><pre><strong>&lt;!-- web --&gt;</strong></pre><pre>&lt;dependency&gt;</pre><pre>  &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;</pre><pre>  &lt;artifactId&gt;<strong>spring-boot-starter-web</strong>&lt;/artifactId&gt;</pre><pre>&lt;/dependency&gt;</pre><pre><strong>&lt;!-- security --&gt;</strong></pre><pre>&lt;dependency&gt;</pre><pre>  &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;</pre><pre>  &lt;artifactId&gt;<strong>spring-boot-starter-oauth2-resource-server</strong>&lt;/artifactId&gt;</pre><pre>&lt;/dependency&gt;</pre><pre><strong>&lt;!-- persistence --&gt;</strong></pre><pre>&lt;dependency&gt;</pre><pre>  &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;</pre><pre>  &lt;artifactId&gt;<strong>spring-boot-starter-data-jpa</strong>&lt;/artifactId&gt;</pre><pre>&lt;/dependency&gt;</pre><pre>&lt;dependency&gt;</pre><pre>  &lt;groupId&gt;com.h2database&lt;/groupId&gt;</pre><pre>  &lt;artifactId&gt;<strong>h2</strong>&lt;/artifactId&gt;</pre><pre>&lt;/dependency&gt;</pre><p>We include the standard <strong>spring-boot-starter-web </strong>dependency to support the web REST<strong> </strong>functionality<strong> </strong>within the<strong> </strong>application<strong>.</strong></p><p>We add the <strong>spring-boot-starter-oauth2-resource-server </strong>dependency to provide the Spring magic that will secure the microservice endpoints.</p><p>We also have two persistence dependencies, <strong>spring-boot-starter-data-jpa and h2 </strong>to support the persistence capabilities of the microservice app since it needs to connect to a relational database.</p><p>To configure the resource we extend the Spring Security <strong>WebSecurityConfigurerAdapter</strong> class as follows:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/c211c5f94e42a89a0b99938901c90a78/href">https://medium.com/media/c211c5f94e42a89a0b99938901c90a78/href</a></iframe><p>The code above leverages the Spring Security DSL to configure various security settings like which api routes are open/unprotected, which routes are protected and what scopes or permissions are required plus the authentication mechanism, in our case jwt.</p><p>Line 13, specifies the unprotected api routes that don’t need an Authentication bearer token header to be present.</p><p>Line 14 and 15, specifies that the “/favorite-foods” route needs to be authenticated and have a “read” scope present in the authentication token. Line 19 specifies that the routes listed on lines 14 and 16 need to be authenticated.</p><p>Line 21 and 22, specify the types of tokens supported, in our case it is JWT.</p><p>The application.yml for the resource server configuration is as follows:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/8c46b82f8d9ecd5e2020e49967fbefe0/href">https://medium.com/media/8c46b82f8d9ecd5e2020e49967fbefe0/href</a></iframe><p>Line 7 specifies the uri location of the Identity provider that issues/mints the JWT tokens. In our example, this is the IBM Security Verify tenant.</p><p>Line 8 specifies the jwk uri, which is a public open endpoint that contains the public key data that the resource server uses to validate the jwt token. Not, when a JWT token is created, the token gets signed using a private key. This public key is the corresponding key to that private key.</p><p>The controller endpoint for “/api/favorite-foods” is as follows:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/8bd914d0d3e7a1c3ed0b710dc326c491/href">https://medium.com/media/8bd914d0d3e7a1c3ed0b710dc326c491/href</a></iframe><p>On line 2, The <strong>“@AuthenticationPrincipal Jwt principal”</strong> argument is auto injected into the controller by Spring from the security context. The principal object essentially contains the claims that were unpacked from the jwt access token. From here, we can retrieve the logged in user information. On line 4, we populate the “loggedInUser” variable from the principal. Line 8 to 10 filter the results so it only has the favorite foods of the logged in user. Lines 12 to 14 populated the data trasfer object for the response.</p><p>The Spring magic occurs via filters. Before execution reaches the Controller, the spring filters will ensure that the security policies configured in the SecurityConfig class and application.yml are enforced and that a valid jwt token exists with the proper scope and any other claims.</p><h3>Running the application</h3><p>All the source code can be found in this git repo: <a href="https://github.com/gkovan/IBM-Security-Verify-Spring-Boot-SSO">https://github.com/gkovan/IBM-Security-Verify-Spring-Boot-SSO</a></p><p>You will need to create a IBM Security Verify tenant and register an application as we described above.</p><p>Then you need to start the two microservices found in the git repo.</p><p>To start the client web app:</p><pre>mvn spring-boot:run -Dspring-boot.run.arguments=&quot;--CLIENT_ID=&lt;your client id&gt; --CLIENT_SECRET=&lt;your client secret&gt;&quot;</pre><p>The client id and client secret is auto generated by IBM Security Verify when you register your application.</p><p>To start the resource server:</p><pre>mvn spring-boot:run</pre><p>Open a browser and to to the url: <a href="http://localhost:8082/ui">http://localhost:8082/ui</a></p><p>Click the Login button to login as a user. You will be redirected to the login screen. Once you login, click on the <strong>“My favorite foods”</strong> link. This will show the my favorite foods for the currently logged in user:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*OAW9kmfdc1McCmo1onhO3Q.png" /></figure><p>Before you log into the application, you will first need to create a user in IBM Security Verify. Login to the ISV tenant that you created and click on the hamburger menu (top left corner) and click on <strong>Users and Groups</strong>. Then click on the <strong>Add User</strong> button. For the identity source, select <strong>Cloud Directory </strong>and fill in the rest of the details such as your name, email etc. and follow the guided process.</p><p>Note: To populate the database manually, edit the file <a href="https://github.com/gkovan/IBM-Security-Verify-Spring-Boot-SSO/blob/main/sso-resource-server/src/main/resources/data.sql">https://github.com/gkovan/IBM-Security-Verify-Spring-Boot-SSO/blob/main/sso-resource-server/src/main/resources/data.sql</a>. Update the name field and replace it with the email address for the user that you just created above.</p><p>When the resource server starts up, the H2 database gets populated automatically from the data in this file.</p><p>References:</p><ul><li><a href="https://docs.verify.ibm.com/verify">IBM Security Verify Documentation Hub</a></li><li><a href="https://docs.spring.io/spring-security/site/docs/current/reference/html5/">Spring Security Reference</a></li><li><a href="https://www.baeldung.com/sso-spring-security-oauth2">Simple Single Sign-On with Spring Security OAuth2 | Baeldung</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d89264e4c6e4" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Build To Manage: Proper Exception Handling Makes Your Applications Easier to Build and Manage]]></title>
            <link>https://gkovan.medium.com/build-to-manage-proper-exception-handling-makes-your-applications-easier-to-build-and-manage-9105dbaf2862?source=rss-b865c5454e69------2</link>
            <guid isPermaLink="false">https://medium.com/p/9105dbaf2862</guid>
            <dc:creator><![CDATA[Gerry Kovan]]></dc:creator>
            <pubDate>Thu, 09 Jul 2020 13:33:40 GMT</pubDate>
            <atom:updated>2020-07-21T13:01:37.976Z</atom:updated>
            <content:encoded><![CDATA[<p>Exception handling continues to be one of the more challenging aspects when designing and writing code. Poor exception handling leads to many problems such as:</p><p>· poorly designed code that is difficult to understand, test and refactor</p><p>· difficult to diagnose the root cause of errors</p><p>· poor logging</p><p>· poor monitoring</p><p>These problems not only make working with the code difficult from a perspective of refactoring and adding new features, but it also makes managing the application in production environments extremely difficult.</p><p>The antidote to these problems involves applying the following best practices:</p><p>· apply the single responsibility design principles to exception handling</p><p>· proper exception handling and logging of exceptions</p><p>· provide meaningful error codes and error messages</p><p>· enable distributed tracing</p><p>· apply best practice API design for returning HTTP status codes</p><p>In this blog, we will explain how each of these best practices can avoid the pitfalls of poor exception handling and allow you to build apps that are easier to manage. A sample mortgage calculator microservice application written using the Java Spring Boot framework is used to demonstrate the concepts however the techniques can be applied to any language.</p><h3>Description of Mortgage Calculator</h3><p>There are two microservices in the mortgage calculator sample application: 1) mortgage-calculator 2) interest-rate.</p><p>The mortgage-calculator microservice has the business logic to calculate the monthly mortgage payments (either fixed-rate or interest only). If the request payload does not include an interestRate field in it, then the interest-rate microservice is invoked to get the latest real-time rate.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/147/1*4A7gOAaVvoZt-BNG_UGl1w.png" /><figcaption>Topology architecture of a mortgage-calculator application</figcaption></figure><h3>Apply Single Responsibility Principle for Exception Handling</h3><p>The single responsibility principle states that each class in your codebase should have only a single responsibility. This applies to exception handling as well. Typically, in a software system that implements a REST API, there are several layers in the code base such as:</p><p>· controllers — defines the REST API</p><p>· tasks — business logic where the logic is bounded to the process</p><p>· services — makes calls to external systems</p><p>Exceptions can potentially occur at any of these layers in the code. For example, you may have some logic in the controller to validate the request and throw an exception when the request is not valid. The task layer can have some exception handling logic for business logic scenarios and the service layer typically would throw exceptions if any problems occur when calling an external service, either client-side problems such as bad credentials or server errors on the dependent service.</p><p>A best practice approach to handle these errors is to introduce a single class to handle these exceptions. In the case of our sample mortgage application, we introduced the ‘MortgageCalculatorExceptionHandler’.</p><p>This class is annotated with the @ControllerAdvice Spring annotation which declares that the class is a spring bean specifically designed to handle exceptions.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/fb985baf98a5e7a82b254c8e043e8090/href">https://medium.com/media/fb985baf98a5e7a82b254c8e043e8090/href</a></iframe><p>This class can be thought of as an extension to the controller. Essentially, the controller contains the behavior for the happy path of the API, while the ControllerAdvice class contains the API behavior for the exception cases. You will notice that the logic for handling the exceptions also includes the HTTP status codes that are returned by the API. The nice thing about separating exception handling into its own class is it makes the code design cleaner and better resulting in code that is easier to understand and refactor.</p><p>The controller code that handles the happy path is kept very clean and simple.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/443e9fd0102b06072d5f760cc65a8ebf/href">https://medium.com/media/443e9fd0102b06072d5f760cc65a8ebf/href</a></iframe><p>Testing the code also becomes simpler as well. Below is the code to test the API behavior. Notice that we test for all the different types of HTTP status codes that can be returned from the /calculate API.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/4844031610dc9dceb6aba26d6cbb05d3/href">https://medium.com/media/4844031610dc9dceb6aba26d6cbb05d3/href</a></iframe><p>Note, other layers of the microservice need appropriate tests as well. In this blog, we are just focusing on the API behavior tests to capture API behavior.</p><h3>Proper Exception Handling and Logging of Exceptions</h3><p>Every application will encounter exceptions. Exceptions let the development team know when something went wrong. It is important to make it as easy as possible for the development team to diagnose the root cause of the problem.</p><h4>Either log an exception or throw an exception, but not both.</h4><p>The code below shows how we invoke our Interest Rate service via a REST API call and our exception handling. For the exception handling, we wrap the original exception in an application-specific exception class that we define called InterestRateServiceException so that we can pass it some custom properties such as error status code and an appropriate error message. It is also very important to pass in the original exception as well which we call origException. This is so that when we eventually log the exception, the original exception/cause will get logged as well which is critical for diagnosing the problem. Notice that we did not log the exception yet as we only want to log it one time.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/c7220d056f7b40872a49017c1688c0d6/href">https://medium.com/media/c7220d056f7b40872a49017c1688c0d6/href</a></iframe><h4>Log an exception only once</h4><p>In our application, the exceptions eventually bubble up to the ControllerAdvice layer (extension to the Controller) and that is where they are handled and logged. The log.error statements (line 8 and 19) is where we log the error. Each exception that occurs only gets logged once to make it easier for the developers to navigate the application logs and identify the root cause of the problem. The exception e is is passed in as a parameter to the log.error statement so that the exception stack trace gets printed out.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/14bd6b3a344fac7f748a6f31396fd64d/href">https://medium.com/media/14bd6b3a344fac7f748a6f31396fd64d/href</a></iframe><p>As an example, when we call the mortgage calculator /calculate endpoint with the following request body…</p><pre>{</pre><pre>&quot;principal&quot;: &quot;100000&quot;,</pre><pre>&quot;term&quot;: &quot;30&quot;,</pre><pre>&quot;type&quot;: &quot;interest&quot;</pre><pre>}</pre><p>We expect the mortgage calculator to invoke the interest-rate service to get the latest interest rate. In the case when the interest rate service is down or not working, the following exception would be logged by the mortgage calculator…</p><pre><strong>[2m2020-07-05 23:29:32.828[0;39m [31mERROR [-,5f029a9c2397110f1f4f33672cd54079,1f4f33672cd54079,false][0;39m [35m3391[0;39m [2m---[0;39m [2m[nio-8110-exec-9][0;39m [36mm.c.c.MortgageCalculatorExceptionHandler[0;39m [2m:[0;39m Error invoking interest rate service : com.gk.mortgage.calculator.exceptions.InterestRateServiceException: MC0003:Error invoking the interest rate service.</strong></pre><pre>at com.gk.mortgage.calculator.service.InterestRateServiceImpl.getRates(InterestRateServiceImpl.java:64) ~[classes/:na]</pre><pre>at com.gk.mortgage.calculator.task.MortgageProcessorTaskImpl.process(MortgageProcessorTaskImpl.java:31) ~[classes/:na]</pre><pre>at com.gk.mortgage.calculator.controller.MortgageCalculatorController.calculateMonthlyPayment(MortgageCalculatorController.java:34) ~[classes/:na]</pre><pre>......</pre><pre>at java.lang.Thread.run(Thread.java:748) [na:1.8.0_144]</pre><pre><strong>Caused by:</strong> <strong>org.springframework.web.client.HttpServerErrorException:</strong> <strong>503 Service Unavailable</strong><br>at org.springframework.web.client.DefaultResponseErrorHandler.handleError(DefaultResponseErrorHandler.java:111) ~[spring-web-4.3.25.RELEASE.jar:4.3.25.RELEASE]</pre><pre>at org.springframework.web.client.RestTemplate.handleResponse(RestTemplate.java:709) ~[spring-web-4.3.25.RELEASE.jar:4.3.25.RELEASE]</pre><pre>at org.springframework.web.client.RestTemplate.doExecute(RestTemplate.java:662) ~[spring-web-4.3.25.RELEASE.jar:4.3.25.RELEASE]</pre><pre>at org.springframework.web.client.RestTemplate.execute(RestTemplate.java:622) ~[spring-web-4.3.25.RELEASE.jar:4.3.25.RELEASE]</pre><pre>at org.springframework.web.client.RestTemplate.exchange(RestTemplate.java:540) ~[spring-web-4.3.25.RELEASE.jar:4.3.25.RELEASE]</pre><pre>at com.gk.mortgage.calculator.service.InterestRateServiceImpl.getRates(InterestRateServiceImpl.java:58) ~[classes/:na]</pre><pre>... 118 common frames omitted</pre><p>Notice, that we log only once, the error code (MC0003), the error message as well as the original exception which is the cause and referred to as <strong>Caused by </strong>in the log output above.</p><p>This technique makes it easier for developers to diagnose problems by looking at the logs.</p><h3>Provide Meaningful Error Codes and Error Messages</h3><p>In the mortgage calculator microservice application, we defined the error codes and error messages in a file called messages.yml.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/f91c94e63e376f66fff42a9de20c4ebf/href">https://medium.com/media/f91c94e63e376f66fff42a9de20c4ebf/href</a></iframe><p>This file gets read in by the application as a configuration and when an exception occurs, we populate the exception with the appropriate error code and exception. The source code below shows the validation code where we check to make sure that the input request has a valid request object that contains a principal amount and a term amount. If the request is not valid we throw a BadRequestInputExcpeption and pass as parameters the error code and the error message that we read from the messages.yml file.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/1155c2a45ef083109caef7bd3746b933/href">https://medium.com/media/1155c2a45ef083109caef7bd3746b933/href</a></iframe><p>Doing this makes the application easier to manage as it enables:</p><ul><li>Searching of logs by error code</li><li>Automated alerts by error code</li><li>Analytics to identify the number of occurrences of specific error codes</li></ul><p>Note, log aggregation systems such as LogDNA, Splunk, and others provide powerful tools for searching and alerting. By having meaningful and well-defined error codes be spit out by your application code, you can enable sophisticated log analytics using those tools mentioned.</p><h3>Enable Distributed Tracing</h3><p>A well-designed software application typically consists of several software modules/components that interact with each other to perform a business function. In modern-day microservice architectures, the number of microservice interactions has increased substantially. There needs to be a way to observe the runtime behavior of the application. Distributed tracing makes this possible by attaching a trace id to every request and having the trace id propagate through the entire interaction within a running microservice process as well as across distinct microservice processes.</p><p>In our mortgage calculator example, when we submit the following request that does not contain and interest rate value, then the application invokes the interest-rate service to get the latest interest rate:</p><pre>{</pre><pre>&quot;principal&quot;: &quot;100000&quot;,</pre><pre>&quot;term&quot;: &quot;30&quot;,</pre><pre>&quot;type&quot;: &quot;interest&quot;</pre><pre>}</pre><p>The logs that get generated for the mortgage calculator microservice are as follow:</p><pre>2020-07-06 11:05:49.161[0;39m [32m INFO [-,<strong>5f033dcd88a9c8a95399b8e4793a0ea6,5399b8e4793a0ea6</strong>,false][0;39m [35m7626[0;39m [2m---[0;39m [2m[nio-8110-exec-8][0;39m [36mc.g.m.c.c.MortgageCalculatorController  [0;39m [2m:[0;39m Calculating morthly mortgage payment.</pre><pre>[2m2020-07-06 11:05:49.173[0;39m [32m INFO [-,<strong>5f033dcd88a9c8a95399b8e4793a0ea6,5399b8e4793a0ea6</strong>,false][0;39m [35m7626[0;39m [2m---[0;39m [2m[nio-8110-exec-8][0;39m [36mt.InterestOnlyMortgageCalculatorTaskImpl[0;39m [2m:[0;39m In calculate method of InterestOnly</pre><p>The logs that get generated for interest rate service are:</p><pre>2020-07-06 11:05:49.170[0;39m [32m INFO [-,<strong>5f033dcd88a9c8a95399b8e4793a0ea6,b7f80d68be7fb243</strong>,false][0;39m [35m7625[0;39m [2m---[0;39m [2m[nio-8111-exec-7][0;39m [36mc.g.i.r.c.InterestRateController        [0;39m [2m:[0;39m In controller of /interest-rates</pre><pre>[2m2020-07-06 11:05:49.170[0;39m [32m INFO [-,<strong>5f033dcd88a9c8a95399b8e4793a0ea6,b7f80d68be7fb243</strong>,false][0;39m [35m7625[0;39m [2m---[0;39m [2m[nio-8111-exec-7][0;39m [36mc.g.i.rate.task.InterestRateTaskImpl    [0;39m [2m:[0;39m Getting latest interest rates</pre><pre>[2m2020-07-06 11:05:49.170[0;39m [32m INFO [-,<strong>5f033dcd88a9c8a95399b8e4793a0ea6,b7f80d68be7fb243</strong>,false][0;39m [35m7625[0;39m [2m---[0;39m [2m[nio-8111-exec-7][0;39m [36mc.g.i.rate.task.InterestRateTaskImpl    [0;39m [2m:[0;39m The interest rates are: InterestRatesResponse(interestRates=[InterestRate(type=30, rate=5.0), InterestRate(type=15, rate=3.5)])</pre><p>The bolded text in the logs above represents the trace id and span id (separated by comma). Notice how the trace id and span id are identical across the two microservices. This enables observability of the runtime behavior of the application, with all microservice interactions. Furthermore, with the trace id, you can search the logs by the trace id or the span id and see all the logs across all components for that particular request which is very powerful in understanding system behavior. This example demonstrated distributed tracing for the happy working path, however, the same principle applies when exceptions occur.</p><h3>Apply Best Practice API design for Returning HTTP Status Codes</h3><p>The mortgage application microservice provides the /calculate REST API endpoint. The API supports the following HTTP error codes:</p><p>200 request executed successfully</p><p>400 request is missing or request does not contain all required values</p><p>401 unauthorized when incorrect security credentials are provided</p><p>500 server error when a call to a dependent service (interest rate service) fails</p><p>These HTTP status codes follow best practice usage and are clear for a developer who wants to understand how your API behaves.</p><p>The following blog can help you choose the appropriate HTTP status codes for your APIs: <a href="https://medium.com/@gkovan/http-status-code-resources-for-building-rest-apis-c01df798b446">https://medium.com/@gkovan/http-status-code-resources-for-building-rest-apis-c01df798b446</a>.</p><p>By having well-defined APIs that use the status codes appropriately, makes the application easier to manage. For example, you can use APM (application performance monitoring) tools such as New Relic or Dynatrace for monitoring and alerts based on rules applied to status codes. As an example, you can set up an alert that notifies the development team whenever HTTP 500 status code occurs more than 3 times in a time window of 300 seconds. This would indicate there is a problem with the interest rate service. You can set up another alert whenever more than five HTTP 401 error codes occur within a time window of 60 seconds. This may indicate that someone is trying to hack your APIs by cracking the security authentication codes. These are just two examples of alerts that can be applied to help the development team manage the application. Many other scenarios can be monitored as well.</p><h3>Summary</h3><p>This blog discusses how to make your application easier to manage. We first discussed the problems with poor exception handling such as:</p><p>· poorly designed code that is difficult to understand and test</p><p>· difficult to diagnose the root cause of errors</p><p>· poor logging</p><p>· poor monitoring</p><p>The blog then discussed in detail the following techniques to make your application easier to manage:</p><p>· apply the single responsibility design principles to exception handling</p><p>· proper exception handling and logging of exceptions</p><p>· provide meaningful error codes and error messages</p><p>· enable distributed tracing</p><p>· apply best practice API design for returning HTTP status codes</p><p>By following these best practices, you will enable your development team to be more productive. Refactoring the code and adding new features because easier because your code has a clean design with appropriate tests that capture exception cases. Equally as important, the development team can more efficiently manage the application by quickly finding the root cause of problems and fixing them quickly.</p><p>The source code to this example can be found in the git repo: <a href="https://github.com/gkovan/mortgage-calculator">https://github.com/gkovan/mortgage-calculator</a> and <a href="https://github.com/gkovan/interest-rate">https://github.com/gkovan/interest-rate</a></p><p><a href="https://www.ibm.com/garage/method/practices/code/build-to-manage">https://www.ibm.com/garage/method/practices/code/build-to-manage</a></p><p>IBM Garage is built for moving faster, working smarter, and innovating in a way that lets you disrupt disruption.</p><p>Learn more at <a href="http://www.ibm.com/garage">www.ibm.com/garage</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=9105dbaf2862" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Effective Kanban and Standup Tips To Improve Team Communication and Alignment]]></title>
            <link>https://gkovan.medium.com/effective-kanban-and-standup-tips-to-improve-team-communication-and-alignment-5ab89c465112?source=rss-b865c5454e69------2</link>
            <guid isPermaLink="false">https://medium.com/p/5ab89c465112</guid>
            <category><![CDATA[agile]]></category>
            <category><![CDATA[sandup]]></category>
            <category><![CDATA[kanban]]></category>
            <dc:creator><![CDATA[Gerry Kovan]]></dc:creator>
            <pubDate>Mon, 16 Mar 2020 14:58:43 GMT</pubDate>
            <atom:updated>2020-03-16T18:08:06.923Z</atom:updated>
            <content:encoded><![CDATA[<p>This short blog describes some techniques to keep development squads productive focusing on the daily Standup ritual and the Kanban workflow. The advice given is applicable to both co-located and remote squads. However, for remote squads where communication and alignment are more challenging, it is even more imperative.</p><p>One of the key rituals for teams building products is the <a href="https://www.ibm.com/garage/method/practices/culture/practice_daily_standup/">Standup</a>. The standup is the ritual that occurs most often and on a daily basis. The Standup typically lasts no more than 15 minutes. It gives each contributor to the team (developer, designer, architect, product owner, etc.) the opportunity to discuss what they are working on and any blockers they may have.</p><p>The <a href="https://www.ibm.com/garage/method/practices/culture/practice-kanban-method">Kanban method</a> is what agile teams use to manage the workflow of the team. Essentially the Kanban workflow manages the process of getting user stories prioritized all the way to being accepted by the product owner.</p><p>An effective Kanban workflow will lead to effective standups and keep the team aligned on the common goal which is to build the <a href="https://www.ibm.com/garage/method/practices/think/practice_minimum_viable_product">MVP</a>.</p><p>Based on my experiences, some best practices for managing the Kanban workflow are:</p><ul><li>Keep the workflow as simple as possible</li><li>Represent all stages needed to get stories accepted including any manual steps</li><li>Keep the state of the user stories up to date</li><li>Continuously optimize by automating any manual stages</li></ul><p>The ‘In Progress’ column should represent stories that are currently being worked on. If there are 4 developer pairs on the squad there should be only 4 stories in the ‘In Progress’ column.</p><p>User stories that are blocked should be clearly marked as such and put back into the ‘Todo’ column.</p><p>Each role on the squad should know and understand which column represents work that they are responsible for. For example, if your product involves manually testing user stories or any manual deployment steps, there should be a stage in the kanban workflow for this. Note, I recommend to automate as much as possible, however in most projects I have been on there are still some manual processes and over time an effort should be made to improve the process and automate.</p><p>During the daily standup ritual, the squad members (devs, qa, architects, PO) discuss user stories that they are currently working on, recently completed and blocked. The Kanban board should make identifying and discussing these user stories very simple. When the standup ritual is performed remotely, it is important to display the board (physical screen when co-located or web conference for remote) for the entire team to see and understand what others are working on. Very often, unless attention is placed to keep the Kanban board organized and up to date, things becomes chaotic and the squad loses control of the state of each user story. The velocity of the team can potentially grind to a halt when this happens. When the team is remote, where communication and alignment become more challenging, it becomes even more important to keep the Kanban board as organized as possible.</p><p>An effective Kanban process will lead to effective Standups. The simple tips discussed in this blog will help improve overall team communication and alignment. This translates to happy developers, good team morale, high velocity and successfully completing the MVP. Good luck.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=5ab89c465112" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[PCI and PII Compliance When Logging Data In Digital Transformation Projects]]></title>
            <link>https://gkovan.medium.com/pci-and-pii-compliance-when-logging-data-in-digital-transformation-projects-7739bab159a6?source=rss-b865c5454e69------2</link>
            <guid isPermaLink="false">https://medium.com/p/7739bab159a6</guid>
            <category><![CDATA[spring]]></category>
            <category><![CDATA[logging]]></category>
            <category><![CDATA[pii]]></category>
            <category><![CDATA[pci]]></category>
            <category><![CDATA[java]]></category>
            <dc:creator><![CDATA[Gerry Kovan]]></dc:creator>
            <pubDate>Wed, 03 Jul 2019 04:26:19 GMT</pubDate>
            <atom:updated>2019-08-21T21:32:52.828Z</atom:updated>
            <content:encoded><![CDATA[<p>Authored by <a href="https://medium.com/u/b865c5454e69">Gerry Kovan</a> and <a href="https://medium.com/u/97eaf5bbd82d">Ramesh krishnamaneni</a></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*-np98zCqFxaI94Ky_lDokQ.jpeg" /></figure><p>When working on digital transformation projects, payment card industry (PCI) and personally identifiable information (PII) compliance is one of the top requirements that must be addressed. Organizations that violate PCI and PII compliance can pay fines into the millions of dollars as well as incur other significant costs to remedy the data breach[1]. Digital transformation projects typically involve developing new modern business applications using microservices architectures. Logging data and events is an essential part of the application in order to allow developers to diagnose and understand runtime behavior of the applications. When logging the data of the microservices process, the data typically has many occurrences of both PCI and PII data, so it is imperative that it be handled in an appropriate and compliant manner.</p><p>This article will address how we handled it on several digital enterprise transformation projects. We will use a sample mortgage calculator application to demonstrate the key concepts to ensure your digital transformation project meets PCI and PII requirements. We developed our sample app microservices using Spring Boot, a java based microservices framework; however the concepts can be applied to any programming language and framework.</p><h3>What is PCI?</h3><p>Payment card industry (PCI) compliance refers to the technical and operational standards that businesses must follow to ensure that credit card data provided by cardholders is protected [2]. Examples of PCI data is:</p><p>· Credit card number</p><p>· Credit card expiration data</p><p>· Credit card verification code</p><p>· Card holder name</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/276/1*xqxyXK0S4EJz-8XbCgQ0nw.jpeg" /></figure><h3>What is PII?</h3><p>Personally Identifiable Information (PII) is any information about an individual maintained by an agency that can be used to distinguish or trace an individual’s identity [3].</p><p>Examples of PII data is:</p><p>· Full name</p><p>· Home address</p><p>· Email address</p><p>· Passport number</p><p>· Data of birth</p><p>· Driver’s license number</p><p>· Social security number</p><p>· Telephone number</p><p>· Biometric data</p><p>· And many other types</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/229/1*dogtads6hrastJ9JNkM_mQ.jpeg" /></figure><h3>Description of the mortgage calculator application</h3><p>The application is a REST api that allows users to make requests to get monthly mortgage payment information. The request contains both PCI (i.e. credit card number, expiry data) and PII data (i.e. name, property address, social security number).</p><p>The following image shows a sample json request body. The request body includes information such as name, property address, credit card number and expiry date, social security number as well as the required info to calculate a monthly mortgage payment such as principal, interest rate, term and mortgage type.</p><p>Sample request body json:</p><pre>{<br>    &quot;name&quot; : &quot;Gerry Kovan&quot;,<br>    &quot;propertyAddress&quot;: &quot;99-31 64th Avenue, Rego Park, NY, 11581&quot;,<br>    &quot;creditCard&quot;: &quot;4111111111111111&quot;,<br>    &quot;creditCardExpiry&quot;: &quot;05/26&quot;,<br>    &quot;socialSecurityNumber&quot;: &quot;123-45-6789&quot;,<br>    &quot;principal&quot;: &quot;100000&quot;,<br>    &quot;interestRate&quot;: &quot;5.0&quot;,<br>    &quot;term&quot;: &quot;30&quot;,<br>    &quot;type&quot;: &quot;fixed&quot;<br>}</pre><p>Sample response body json showing the calculated monthly payment amount:</p><pre>{<br>    &quot;name&quot;: &quot;Gerry Kovan&quot;,<br>    &quot;propertyAddress&quot;: &quot;99-31 64th Avenue, Rego Park, NY, 11581&quot;,<br>    &quot;creditCard&quot;: &quot;4111111111111111&quot;,<br>    &quot;creditCardExpiry&quot;: &quot;05/26&quot;,<br>    &quot;socialSecurityNumber&quot;: &quot;123-45-6789&quot;,<br>    &quot;principal&quot;: 100000,<br>    &quot;interestRate&quot;: 5,<br>    &quot;term&quot;: 30,<br>    &quot;type&quot;: &quot;fixed&quot;,<br>    &quot;monthlyPayment&quot;: 536.82<br>}</pre><h3><strong>Logging</strong></h3><p>Application logs provide visibility into the runtime behavior of the application. It is critical for the developers to view and analyze the log data in order to diagnose and fix application defects. According to the 12 factor app standard, logs are treated as streams and are typically sent to a service such as splunk (<a href="http://www.splunk.com/">www.splunk.com</a>) or a Hadoop data warehousing system for indexing and analysis [4]. In our application, we log the entire request and response objects. Both the request and response contain PCI and PII information. We used <a href="https://docs.spring.io/spring/docs/2.5.x/reference/aop.html">Spring AOP</a> (Aspect Oriented Programming) to achieve this.</p><p>The figure below shows the controller code for the /calculate REST endpoint. The request body is a java object called MortgageCalculatorRequest. When the controller executes successfully, it responds with the data encapsulated in the java object called MortgageCalculatorResponse.</p><p>The request and response objects map directly to the sample json discussed above.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*vcD0y_VT1xwCx87iFDD3fQ.png" /><figcaption><em>Figure 1: Controller code showing request and response objects for the /calculate REST endpoint.</em></figcaption></figure><p>In order for developers to debug the code and understand the runtime behavior of the application, we need to log the relevant data. It is typical to log events such as when the controller begins execution and when it ends execution. It is also typical to log the data in the request and response objects.</p><p>To achieve this, we leveraged Spring AOP (aspect oriented programming). AOP is a programming paradigm that increases code modularity by allowing separation of cross cutting concerns. Logging is an excellent example of a cross cutting concern. You will notice that the controller code in the figure above does not have any logging code in it which keeps the code clean and easy to follow and read for a developer.</p><h3>Spring AOP Logging Aspect</h3><p>The figure below shows the code for the Spring AOP logging aspect. This code gets invoked whenever the REST call to the ‘/calculate’ gets made which invokes the controller. The method ‘controllerStart’ gets invoked before the controller begins processing and this method is responsible for logging the request data. The method ‘controllerEnd’ gets invoked once the controller finishes executing and is responsible for logging the response data.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*JhTf5TpbQI5R0qKzOUeFHw.png" /><figcaption>Figure 2: Spring AOP logging aspect which logs the request and response data</figcaption></figure><h3>Log messages without addressing PCI and PII compliance</h3><p>Below are the logs that the aspect prints out before addressing the PCI and PII requirements. Notice that for the request we log the ClientId, RequestURI, RequestURL and request body data. For the response logs, we log the response body data. Notice that the sensitive information in the request and response body is clearly visible to anyone who can gain access to the logs. PII information like name, property address, social security number is clearly visible. PCI information such as credit card number and expiry date are also clearly visible.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*jbLUkEvGVLt7wxxnFiRZfQ.png" /><figcaption>Figure 3: Request Body log without masking — all sensitive data is visible in clear text</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*rSPg_lfyJhtDgPDwxbAhAg.png" /><figcaption>Figure 4: Response Body log without masking — all sensitive data is visibile in clear text</figcaption></figure><h3>Log messages after addressing PCI and PII compliance</h3><p>The request and response logs below address the PCI and PII requirements by masking or encrypting the relevant data. The sensitive data is no longer visible to anyone including developers who can gain access to the logs. The logs are still valuable to developers to help diagnose application issues which is really the end goal from a logging perspective however the users data is protected.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*sP_QNYRNM1s5zm7JBXLnQg.png" /><figcaption>Figure 5: Request body log with masking — sensitive data is not visible in clear text</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*LFgdr_Sn6EwINhhp9-mFGw.png" /><figcaption>Figure 6: Response body log with masking — sensitive data is not visible in clear text</figcaption></figure><h3>PCI and PII Compliance for Log Data</h3><p>For logging PCI data fields, we replace all the characters with a ‘*’ and we optionally allow the programmer to specify how many characters to show or keep without masking. For example, when we log the credit card number, we do show the last four digits.</p><p>For logging PII data fields, we replace all the characters with a hash of the original value keeping the length of the string the same. We also allow the programmer to specify how many characters to show or keep without masking. For example, when we log the social security number, we do show the last 4 digits.</p><h3>How we implemented the PCI and PII logging compliance?</h3><p>We created Java annotations for PCI, PII, and Mask as follows…</p><pre>@Retention(RetentionPolicy.RUNTIME)<br>@Target({ElementType.FIELD, ElementType.PARAMETER})<br>public @interface <strong>PCI</strong> {<br>   public int keepLastDigits() default 0;<br>}</pre><pre><a href="http://twitter.com/Retention">@Retention</a>(RetentionPolicy.RUNTIME)<br><a href="http://twitter.com/Target">@Target</a>({ElementType.FIELD, ElementType.PARAMETER})<br>public <a href="http://twitter.com/interface">@interface</a> <strong>PII</strong> {<br>   public int keepLastDigits() default 0;<br>}</pre><pre><a href="http://twitter.com/Retention">@Retention</a>(RetentionPolicy.RUNTIME)<br><a href="http://twitter.com/Target">@Target</a>(ElementType.TYPE)<br>public <a href="http://twitter.com/interface">@interface</a> <strong>Mask</strong> {<br>}</pre><p>We then annotate the request and response java model objects. We annotate the class with @Mask to indicate that the Java object has PCI and/or PII data fields in it. We then annotate the appropriate data fields with PII or PCI as shown below.</p><pre><br><strong>@Mask</strong><br>public class MortgageCalculatorRequest {<br> <br><strong> @PII</strong><br> String name;</pre><pre> <strong>@PII</strong><br> String propertyAddress;</pre><pre> <strong>@PCI(keepLastDigits=4)</strong><br> String creditCard;<br> <strong>@PCI</strong><br> String creditCardExpiry;</pre><pre><strong> @PII(keepLastDigits=4)<br> String socialSecurityNumber;</strong></pre><pre> Double principal;<br> Double interestRate;<br> Integer term;<br> String type;<br>}</pre><pre><strong>@Mask</strong><br>public class MortgageCalculatorResponse {<br> <br><strong> @PII</strong><br> String name;</pre><pre><strong> @PII</strong><br> String propertyAddress;</pre><pre> <strong>@PCI(keepLastDigits=4)</strong><br> String creditCard;</pre><pre><strong> @PCI</strong><br> String creditCardExpiry;</pre><pre><strong> @PII(keepLastDigits=4)</strong><br> String socialSecurityNumber;<br> <br> Double principal;<br> Double interestRate;<br> Integer term;<br> String type;<br> Double monthlyPayment;<br>}</pre><p>We created a custom serializer that converts the data in the request and response Java objects into a string representation masking the appropriate data fields. The basic logic is as follows:</p><ul><li>Check if java object has the ‘@Mask’ annotation.</li><li>If yes, then we iterate through all the fields in the object</li><li>If a field is annoted with ‘@PCI’ then we replace all characters with a ‘*’ and except for the last characters as specified by ‘keepLastDigits’ annotation parameter.</li><li>If a field is annotated with ‘@PII’ then we replace all characters with a hexadecimal format of the hash value (one way encryption). We optionally show in plain text the trailing characters in the field as specified by the ‘keepLastDigits’ annotation parameter.</li></ul><p>The code snippet below shows the custom serializer that masks the sensitive data when converting the java object to a string for logging.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*5DO02spw5-Qlat698n10aA.png" /><figcaption>Figure 7: Custom serializer that masks sensistive PCI and PII data fields for logging</figcaption></figure><h3>Summary</h3><p>Logging data is a critical aspect of any application including and especially applications designed using a microservice architecture. Developers must be careful to mask any and all sensitive PCI and PII data in order to protect and prevent any data breaches. This blog demonstrated an approach to do this using the Spring Boot Java framework and core Java concepts.</p><h3>References</h3><p>[1] <a href="https://www.securitymetrics.com/blog/how-much-does-data-breach-cost-your-organization">https://www.securitymetrics.com/blog/how-much-does-data-breach-cost-your-organization</a></p><p>[2] <a href="https://www.investopedia.com/terms/p/pci-compliance.asp">https://www.investopedia.com/terms/p/pci-compliance.asp</a></p><p>[3] <a href="https://piwik.pro/blog/what-is-pii-personal-data/">https://piwik.pro/blog/what-is-pii-personal-data/</a></p><p>[4] <a href="https://12factor.net/logs">https://12factor.net/logs</a></p><p><strong>Bring your plan to the IBM Garage.<br></strong>Are you ready to learn more about working with the IBM Garage? We’re here to help. Contact us today to schedule time to speak with a Garage expert about your next big idea. Learn about our IBM Garage Method, the design, development and startup communities we work in, and the deep expertise and capabilities we bring to the table.</p><p><a href="https://www.ibm.com/account/reg/us-en/signup?formid=urx-38887"><em>Schedule a no-charge visit</em></a><em> with the IBM Garage.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=7739bab159a6" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[HTTP Status Code Resources For Building REST API’s]]></title>
            <link>https://gkovan.medium.com/http-status-code-resources-for-building-rest-apis-c01df798b446?source=rss-b865c5454e69------2</link>
            <guid isPermaLink="false">https://medium.com/p/c01df798b446</guid>
            <category><![CDATA[api]]></category>
            <dc:creator><![CDATA[Gerry Kovan]]></dc:creator>
            <pubDate>Sun, 12 May 2019 21:14:00 GMT</pubDate>
            <atom:updated>2019-07-03T04:38:29.699Z</atom:updated>
            <content:encoded><![CDATA[<p>One of the frustrating things when creating API’s is choosing appropriate HTTP status codes that follow best practices and is consistent with the way it was intended to be used. There always seems to be a lot of debate about what HTTP status code to use for particular situations. There are obviously guiding principles from the HTTP specification, however there is enough ambiguity in the standard for the debates and usage to vary quite a bit. That is why questions and discussions about this topic on sites such as stackoverflow and others have many different opinions and thoughts which can be confusing to developers.</p><p>This article provides some good resources that I found useful in order to choose the most appropriate HTTP status codes while building API’s.</p><p><strong>HTTP Status Code Flow Chart</strong></p><p>The following blog uses an interesting and very useful flow chart approach to help decide on the most appropriate HTTP status code:</p><p><a href="https://www.codetinkerer.com/2015/12/04/choosing-an-http-status-code.html">Choosing an HTTP Status Code - Stop Making It Hard</a></p><p>An excerpt from the blog:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*25azijsm93FhNHzD.png" /><figcaption>Choosing a 2xx/3xx/4xx/5xx/1xx response class</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*o0cN3GtM5ggMDD_1.png" /><figcaption>Choosing a 2xx/3xx status code</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*BE1ZCp2Rr98B6Gth.png" /><figcaption>Choosing a 4xx status code</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/906/0*Zb40Url-QWtvmbam.png" /><figcaption>Choosing a 5xx status code</figcaption></figure><p><strong>HTTP Status Codes Used By Famous Sites</strong></p><p>It is always useful to understand how world famous sites such as google, twitter, github design their api’s. You might as well learn from the best in the business.</p><p>The link below provides info for many of the popular APIs on the internet today.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/ae52f8fc3978951751a83182d549daea/href">https://medium.com/media/ae52f8fc3978951751a83182d549daea/href</a></iframe><p><strong>Subway Map Representation of HTTP Status Codes</strong></p><p>A subway map representation of HTTP status codes is quite interesting as well. As you navigate the map and select a particular HTTP status code to find out more information, it takes you to the original specification document which I found quite useful.</p><p><a href="https://restlet.com/http-status-map/">HTTP Status Map</a></p><p><strong>Conclusion</strong></p><p>I created this blog for my own purposes to help me create API’s and maintain consistency while adhering to the standards as best as I can. Although, I have not added anything new to this topic, I believe this blog at least helps to consolidate useful information on this topic in a single spot. I hope others find this information useful as well.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=c01df798b446" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[SOLID design principles make test-driven development (TDD) faster and easier]]></title>
            <link>https://gkovan.medium.com/solid-design-principles-makes-test-driven-development-faster-and-easier-35c9eec22ff1?source=rss-b865c5454e69------2</link>
            <guid isPermaLink="false">https://medium.com/p/35c9eec22ff1</guid>
            <category><![CDATA[solid-principles]]></category>
            <category><![CDATA[tdd]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[test-driven-development]]></category>
            <category><![CDATA[oop]]></category>
            <dc:creator><![CDATA[Gerry Kovan]]></dc:creator>
            <pubDate>Sun, 17 Mar 2019 18:01:13 GMT</pubDate>
            <atom:updated>2020-01-02T14:43:50.192Z</atom:updated>
            <content:encoded><![CDATA[<h3><strong>Introduction</strong></h3><p>Delivering cloud native apps to users with speed and quality requires a fully automated solution including a comprehensive test suite providing confidence that the application behaves as expected under all known conditions.</p><p>TDD (test-driven development) has become a popular method to design and develop software to ensure that the code base is sufficiently tested and its behavior is captured in tests.</p><p>A common complaint I keep hearing from developers who are on projects where TDD is practiced is that maintaining code (e.g. adding new features, fixing bugs, refactoring) becomes difficult because there are too many tests and most of their time is consumed fixing tests.</p><p>Sometimes this can happen because tests attempt to capture more behavior than they should, or perhaps, the application design needs to be optimized to better demarcate boundaries of responsibility that can easily be tested.<br>The ideal state to achieve is one where your tests capture the complete behavior of the application without sacrificing the maintainability of the code to enable development teams to go fast.</p><p>I have found that while developing software using a TDD approach, designing the application using the SOLID design principles results in fewer overall tests that better capture the behavior of the application.</p><p>In this paper, we will discuss the five SOLID design principles in the context of a mortgage calculator application and demonstrate how it promotes a well-designed application and enables simpler and fewer tests that are easier to maintain without sacrificing capturing the expected behavior of the entire application.</p><p>TDD is an acronym that stands for test-driven development, which means that tests are written first, and then followed by the code to make the test pass.<br>TDD is one of the main tenets of XP (Extreme Programming), which has gained a lot of traction in the industry.</p><p>SOLID is an acronym for five design principles that make code easier to understand, easier to test, easier to maintain and more flexible. Robert C. Martin, one of the key authors of the Agile Manifesto is a big proponent of both TDD and SOLID design principles. The SOLID principles were first conceptualized by Robert C. Martin in his 2000 paper.</p><h3><strong>SOLID Principles Explained</strong></h3><p>The five principles are</p><p>1. Single Responsibility Principle<br>2. Open / Closed Principle<br>3. Liskov Substitution Principle<br>4. Interface Segregation Principle<br>5. Dependency Injection Principle</p><p>We will discuss the SOLID principles and how they were used in the context of designing and building a mortgage calculator application. The mortgage calculator is an API application that calculates monthly mortgage payments for various types of mortgages such as fixed rate (e.g. 30 year, 15 year) or interest only mortgages.</p><h3>1. Single Responsibility Principle</h3><p>This principle states:</p><ul><li><em>A class should have only a single responsibility.</em></li></ul><p>If you look at the structure of the code in figure 1, each class (yellow rectangles) only has a single responsibility. This makes each class very easy to test. From a TDD perspective, it makes it very easy to describe the behavior of each class using tests.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/767/1*I_WUH6NGwu8ecoMfEujTTw.png" /><figcaption>Figure 1: Code structure of the Mortgage Calculator application demonstrating the Simple principle</figcaption></figure><p>The goal is to create tests that capture the unique behavior each class implements and no more. You want to minimize testing redundant behavior<br>across different parts or layers of the application. For example, the controller tests should not be responsible for testing that the monthly mortgage<br>calculations are correct. Those behaviors are tested and captured by the tests for the two mortgage calculator tasks. Table 1 below describes the responsibility of each class as well as a description of the tests for each class.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*0XxyMq4OtNRvHkPiOpHSWw.png" /><figcaption><em>Table 1. Description of classes and tests for each class</em></figcaption></figure><h3>2. Open / Closed Principle</h3><p>This principle states:</p><ul><li><em>Software entities should be open for extension, but closed for modification.</em></li><li><em>Be able to add new functionality without changing existing code.</em></li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/546/1*JbpCUxfToWs6OEWpwphnRA.png" /><figcaption><em>Figure 2. Code structure of MortgageCalculatorTask and its sub-types demonstrating the open/closed principle</em></figcaption></figure><p>The figure above describes the MortgageCalculatorTask interface with a single method called calculateMonthlyPayment(…​). This interface represents the contract that is closed for modification. This interface has two implementations — FixedRateMortgageCalculatorImpl and InterestOnlyMortgageCalculatorImpl. The design is also open for extension. To extend the functionality of the app to support adjustable rate mortgages, we can create a third implementation class called AdjustableRateMortgageCalculatorTask. See the figure below.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/842/1*BWNdCLiuRnXrFCSWiTfv5g.png" /><figcaption><em>Figure 3. Extending the app by adding a new sub-type</em></figcaption></figure><p>Line 45 of the class in figure 4 below uses the Spring application context ‘getBean(…)’ method to get an instance of a spring managed bean of type MortgageCalculatorTask during runtime execution.<br>The ‘getBean(…)’ method will either return an instance of ‘FixedRateMortgageCalculatorImpl’ or ‘InterestOnlyMortgageCalculatorImpl’.<br>Therefore, if we add the new feature to calculate monthly payments for AdjustableRateMortgages, we do not have to change a single line of code in MortgageProcessorTaskImpl. This meets the requirement of ‘add functionality without changing existing code’.</p><p>From a TDD perspective, we only need to create unit tests to test and capture the behavior of the new feature (i.e. the AdjustableRateMortgageCalculatorImpl class).</p><p>We do not need to add any new tests to test the MortgageProcessorTaskImpl as the behavior of this class is not changed.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*YtdQ3z9Vxdkgp332gH0d3Q.png" /><figcaption>Figure 4: Code snippet demonstrating adding new functionality without changing existing code (line 45 in code)</figcaption></figure><h3><strong>3. Liskov Substitution Principle</strong></h3><p>The principle states:</p><ul><li><em>Objects in a program should be replaceable with instances of their subtypes without altering the correctness of that program.</em></li></ul><p>This principle is closely related to the Open/Closed principal and defines that objects of a superclass shall be replaceable with objects of its subclasses without breaking the application. This requires the objects of your subclasses to behave in the same way as the objects of your superclass.</p><p>In our example ‘FixedRateMortgageCalculatorTaskImpl’ and ‘InterestOnlyMortgageCalculatorTaskImpl’ implement the MortgageCalculatorTask interface so they are a type or sub-class of MortgageCalculatorTask.</p><p>The code in MortgageProcessorTaskImpl.process(…) invokes the calculate method on whatever bean implementation gets injected into it (i.e. FixedRate or InterestOnly) at runtime.</p><p>We can easily add new types of mortgage calculators and the MortgageProcessorTaskImpl class would not have to change at all. The application does not break by doing this.</p><p>The implication from a unit test perspective is that unit tests need to be written for only the new feature (i.e a new mortgage calculator type) as there is no risk of breaking other parts of the application.</p><h3><strong>Interface Segregation Principle</strong></h3><p>This principle states:</p><ul><li><em>Many client-specific interfaces are better than one general-purpose interface</em></li></ul><p>In our mortgage application app, the ‘MortgageCalculatorTask’ interface has a single method called ‘calculateMonthlyPayment’. This interface is implemented by two classes. If we were to add additional capability to the app, for example, showing amortization schedule, the principle states to segregate the interface by defining a new interface instead of adding a new method to the existing ‘MortgageCalculatorTask’ interface.</p><h3><strong>Dependency Injection Principle</strong></h3><p>This principle states:</p><ul><li><em>High-level modules should not depend on low-level modules. Both should depend on abstractions.</em></li><li><em>Abstractions should not depend on details. Details should depend on abstractions.</em></li></ul><p>To explain the first statement, lets look at figure 1 in the ‘Simple Principle’ section; we can see that the MortgageCalculatorController class which is the higher level module, and its lower level module, which is the MortgageProcessorTaskImpl, do not depend on each other. They both depend on the abstraction which is the MortgageProcessorTask interface.<br>MortgageCalculatorController is only aware of the interface and is not aware of any concrete implementation classes.</p><p>Similarly, MortgageProcessorTaskImpl depends on the MortgageProcessorTask interface via the implementation relationship. It is not aware of who uses it. Furthermore, you can see from the design of the MortgageCalculatorController class, the dependencies are injected by the constructor. See figure 5 below.</p><p>The Spring <a href="http://twitter.com/Autowired">@Autowired</a> annotation is added to the constructor which does the actual injection of the dependent java objects which are Spring beans.<br>This concept is known as inversion of control where the framework (i.e. Spring) instantiates and manages the classes as opposed to the developer having to do so explicitly.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*YtRg4ZmH58566GNx3dE-RQ.png" /><figcaption>Figure 5:Dependencies are injected in the constructor using Spring <a href="http://twitter.com/Autowired">@Autowired</a> annotation (line 21 in the code)</figcaption></figure><p>The significance of this is that it makes testing easier. For example, to test the higher level module, MortgageCalculatorController, I want to mock all its dependencies.</p><p>From a test perspective, I can simply inject the mock dependent objects in order to ensure that the class under test is behaving as expected.<br>Furthermore in this case, since we are testing the behavior of the controller, the tests only need to cover expected response type, exceptions thrown, http api behavior, etc. that are not covered by other parts of the code.<br>There is no need for controller tests to test the behavior of the mortgage calculation formulas or any other part of the system. This would be redundant and would make any future code maintenance more costly as more time would need to be spent fixing broken tests.</p><p>If we had instantiated the dependencies directly in the code (line 20 and 21) as shown in the figure 6 below, then we would not be able to mock the dependencies complicating the testing effort.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Dg7ooxLK5NA7hZ7uT-Y6Ng.png" /><figcaption>Figure 6: Dependencies are instantiated directly in the code (line 20 and 21 in the code) making testing of the controller more difficult</figcaption></figure><p>To explain the second statement, let’s further analyze the MortgageCalculatorTask interface and its two implementations,<br>‘FixedRateMortgageCalculatorTaskImpl’ and InterestOnlyMortgageCalculatorTaskImpl as shown in Figure 2.</p><p>The interface is the ‘abstraction’ and the two implementations are the details. The principle basically states that I should be able to change the implementation without affecting the behavior of the application. So If I change the implementation of the<br>‘FixedRateMortgageCalculatorTaskImpl -&gt; calculateMonthlyPayment(…)’ method, it will not affect the behavior of the app as a whole. There could be multiple reasons why you would want to change the implementation, for example to introduce a more efficient algorithm.</p><p>From a TDD and test perspective, I only need to ensure that the new implementation is properly tested and the monthly mortgage payment calculations behave correctly. All other layers in the code from both a test and implementation perspective should not be affected. Therefore, you should not expect any broken tests due to refactoring the implementation.</p><h3><strong>Conclusion</strong></h3><p>In this paper, we analyzed how adopting the SOLID design principles while doing test-driven development (TDD), makes the application easier to maintain, easier to test and enables development teams to deliver quality code with speed over a long period of time.</p><p>One of the key detriments to going fast is having an overly large test suite and a non-optimized application design.</p><p>The SOLID principles, helps you to build a well designed application. From a TDD perspective, you can design your tests in a way where the complete behavior of the app is captured and tested, while minimizing the number of tests including redundant tests.</p><p>The github repo containing the source code for the application can be found at: <a href="https://github.com/gkovan/mortgage-calculator">https://github.com/gkovan/mortgage-calculator</a></p><p>References</p><ol><li>Design Principles and Design Patterns, Robert C. Martin, <a href="https://fi.ort.edu.uy/innovaportal/file/2032/1/design_principles.pdf">https://fi.ort.edu.uy/innovaportal/file/2032/1/design_principles.pdf</a></li><li>The Agile Manifesto, <a href="https://agilemanifesto.org/principles.html">https://agilemanifesto.org/principles.html</a></li><li>Mortgage application source code repo: <a href="https://github.com/gkovan/mortgage-calculator">https://github.com/gkovan/mortgage-calculator</a></li></ol><p><strong>Bring your plan to the IBM Garage.<br></strong>Are you ready to learn more about working with the IBM Garage? We’re here to help. Contact us today to schedule time to speak with a Garage expert about your next big idea. Learn about our IBM Garage Method, the design, development and startup communities we work in, and the deep expertise and capabilities we bring to the table.</p><p><a href="https://www.ibm.com/account/reg/us-en/signup?formid=urx-38887"><em>Schedule a no-charge visit</em></a><em> with the IBM Garage.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=35c9eec22ff1" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>