Forem: Andrew Hughes

Build a Simple CRUD App with Spring Boot and Vue.js

Andrew Hughes — Thu, 09 Feb 2023 21:15:41 +0000

You will use Vue and Spring Boot to build a todo list web application. The application will include CRUD abilities, meaning that you can create, read, update, and delete the todo items on the Spring Boot API via the client. The Vue frontend client will use the Quasar framework for the presentation. OAuth 2.0 and OpenID Connect (OIDC) will secure the Spring Boot API and the Vue client, initially by using Okta as the security provider. Then, at the end of the tutorial, you will also see how to use Auth0 as the security provider.

This project has two major parts:

Spring Boot API
Vue client

The Spring Boot app will include an H2 in-memory database and will use Spring Data JPA to map our todo data model to a database table for persistence. As you'll see, the server will leverage Spring Boot's ability to quickly expose data via a REST API with minimal configuration.

The client will use Vue 3 and the Quasar framework. The Quasar framework provides components and layout tools to help build Vue applications quickly with a consistent, high-quality user interface.

Before you dig into the tutorial, I want to quickly introduce the technologies for those that might be unfamiliar. Feel free to skip down to the prerequisites section if you're already familiar with Vue and Spring Boot.

If you're more of a visual learner, this tutorial is also available as a screencast.

What is Vue.js?
Introducing the Quasar Framework
About Spring Boot
Create an OpenID Connect app
Bootstrap a Spring Boot app using Spring Initializr
Configure Spring Security
Test your Vue and Spring Boot app
Secure your Spring Boot API
Create a Vue JavaScript client
Confirm your Spring Boot and Vue todo app works
Use Auth0 to secure the API
Update the Vue client to use Auth0
Do more with Spring Boot, Vue, and Okta

What is Vue.js?

Vue is a JavaScript view library, like React and Angular. It's designed to be incrementally adoptable, and the core library focuses solely on the view layer.

In my experience, Vue.js is a great alternative to React. I learned React first and came to use Vue later. Like React, Vue uses a virtual DOM, provides reactive and composable view components, and enforces a strict one-way parent-child relationship when defining properties and state. This means that it is performant and avoids many confusing state relationships that can occur without one-way data binding.

However, unlike React, Vue uses templates instead of JSX (a potentially welcome and more immediately accessible option). Vue gives you component-scoped CSS using style tags in single-file components. In practice, this difference is pretty significant because, in React, the JSX and CSS-like syntax are close enough to HTML and CSS to be confusing but not the same, which creates problems initially. (Ever gone from a language that doesn't require semicolons back to one that does? It's something like that.)

I find Vue to be a simpler, cleaner implementation. React requires a deep dive. You gotta take the red pill and go all the way. It's a super powerful system, but you have to be all in. Vue is a little friendlier and a little easier to get started.

Introducing the Quasar Framework

The Quasar Framework builds on top of Vue to add a cross-platform component library and grid layout system. It also provides many tools for deploying Vue-based applications to basically any platform you can think of, from web single-page and progressive web apps to mobile apps and Electron-based desktop apps. In this tutorial, you'll only be using the layout and component library features. Still, Quasar's big push is to allow developers to write a single web application and deploy it to any platform with a consistent look with minimal changes.

About Spring Boot

The server technology you're going to use is Spring Boot. Pure, unadulterated Spring (pre-Spring Boot) is a bit of a behemoth: super powerful but potentially time-sucking and frustrating. I'm pretty sure the whole computer conference phenomena came about so that people could learn and understand old-school Spring XML files. It certainly drove large sections of the computer publishing empires.

Spring Boot was Spring's answer to this complexity (and to frameworks like Ruby on Rails and Grails). They did a great job of distilling down all the power of Spring into a simple, quick, easy-to-use web framework. You can have a fully functioning resource server with a ridiculously small number of lines of code and a few annotations.

Plus, when you're ready, you have all the power of Spring under the hood, just waiting.

Prerequisites:

Before you start, please make sure you have the following prerequisites installed (or install them now).

Java 17: or use SDKMAN! to manage and install multiple versions
Okta CLI: the Okta command-line interface
HTTPie: a simple tool for making HTTP requests from a Bash shell
Node 16+
Vue CLI: you'll use this to bootstrap the Vue client

You will need a free Okta Developer account if you don't already have one. But you can wait until later in the tutorial and use the Okta CLI to log in or register for a new account.

Instead of building the project, you can also clone the repo and follow the instructions there to configure it.

Create an OpenID Connect app

Open a Bash shell. Create a parent directory for the project. Eventually, this will include both the resource server and client projects.

mkdir spring-boot-vue-crud
cd spring-boot-vue-crud

Before you begin, you’ll need a free Okta developer account. Install the Okta CLI and run okta register to sign up for a new account. If you already have an account, run okta login. Then, run okta apps create. Select the default app name, or change it as you see fit. Choose Single-Page App and press Enter.

Use http://localhost:8080/callback for the Redirect URI and accept the default Logout Redirect URI of http://localhost:8080.

What does the Okta CLI do?

The Okta CLI will create an OIDC Single-Page App in your Okta Org. It will add the redirect URIs you specified and grant access to the Everyone group. It will also add a trusted origin for http://localhost:8080. You will see output like the following when it’s finished:

Okta application configuration:
Issuer:    https://dev-133337.okta.com/oauth2/default
Client ID: 0oab8eb55Kb9jdMIr5d6

NOTE: You can also use the Okta Admin Console to create your app. See Create a Vue App for more information.

Copy the client ID and issuer URI somewhere safe. You'll need them for both the client and resource server applications.

TIP: You can also use Auth0 to secure Spring Boot and the Vue client.

Bootstrap a Spring Boot app using Spring Initializr

You're going to use the Spring Initializr to create a starter project for the resource server. You can look at the project website if you want, but here you'll use the REST API to download a pre-configured starter.

The following command will download the starter project and un-tar it to a new directory named resource-server.

curl https://start.spring.io/starter.tgz \
  -d bootVersion=3.0.2 \
  -d javaVersion=17 \
  -d dependencies=web,data-rest,lombok,data-jpa,h2,okta \
  -d type=gradle-project \
  -d baseDir=resource-server \
| tar -xzvf - && cd resource-server

The dependencies you're including are:

web: Spring Web MVC, adds basic HTTP REST functionality
data-jpa: Spring Data JPA, makes it easy to create JPA-based repositories
data-rest: Spring Data REST, exposes Spring Data repositories as resource servers
h2: the H2 in-memory database used for demonstration purposes
lombok: Project Lombok, adds some helpful annotations that eliminate the need to write a lot of getters and setters
okta: Okta Spring Boot Starter that helps OAuth 2.0 and OIDC configuration

Project Lombok saves a lot of clutter and ceremony code. However, if you're using an IDE, you'll need to install a plugin for Lombok. See the project's installation docs for more information.

Configure Spring Security

Open the application properties file and update it. You're changing the server port so it doesn't conflict with the default Vue local server (which also defaults 8080).

src/main/resources/application.properties

server.port=9000
okta.oauth2.issuer=<your-issuer-uri>
okta.oauth2.clientId=<your-client-id>

You need to replace the two bracketed values with the values you generated above for the OIDC app using the Okta CLI.

You can run the bootstrapped project right now and see if it starts. It should start but won't do much.

./gradlew bootRun

Create a SecurityConfiguration class to configure Spring Security. The class below configures web security to allow all requests, effectively bypassing security. This is just so you can test the resource server initially. You'll enable security shortly.

src/main/java/com/example/demo/SecurityConfiguration.java

package com.example.demo;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
public class SecurityConfiguration {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http.authorizeHttpRequests()
            .anyRequest().permitAll();
        return http.build();
    }

}

Replace the DemoApplication.java file with the following.

src/main/java/com/example/demo/DemoApplication.java

package com.example.demo;

import org.springframework.boot.ApplicationRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.web.servlet.FilterRegistrationBean;
import org.springframework.context.annotation.Bean;
import org.springframework.core.Ordered;
import org.springframework.data.rest.core.config.RepositoryRestConfiguration;
import org.springframework.data.rest.webmvc.config.RepositoryRestConfigurer;
import org.springframework.stereotype.Component;
import org.springframework.web.cors.CorsConfiguration;
import org.springframework.web.cors.UrlBasedCorsConfigurationSource;
import org.springframework.web.filter.CorsFilter;
import org.springframework.web.servlet.config.annotation.CorsRegistry;

import java.util.Collections;
import java.util.Random;
import java.util.stream.Stream;

@SpringBootApplication
public class DemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }

    // Bootstrap some test data into the in-memory database
    @Bean
    ApplicationRunner init(TodoRepository repository) {
        return args -> {
            Random rd = new Random();
            Stream.of("Buy milk", "Eat pizza", "Update tutorial", "Study Vue", "Go kayaking").forEach(name -> {
                Todo todo = new Todo();
                todo.setTitle(name);
                todo.setCompleted(rd.nextBoolean());
                repository.save(todo);
            });
            repository.findAll().forEach(System.out::println);
        };
    }

    // Fix the CORS errors
    @Bean
    public FilterRegistrationBean simpleCorsFilter() {
        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        CorsConfiguration config = new CorsConfiguration();
        config.setAllowCredentials(true);
        // *** URL below needs to match the Vue client URL and port ***
        config.setAllowedOrigins(Collections.singletonList("http://localhost:8080"));
        config.setAllowedMethods(Collections.singletonList("*"));
        config.setAllowedHeaders(Collections.singletonList("*"));
        source.registerCorsConfiguration("/**", config);
        FilterRegistrationBean bean = new FilterRegistrationBean<>(new CorsFilter(source));
        bean.setOrder(Ordered.HIGHEST_PRECEDENCE);
        return bean;
    }

    // Expose IDs of Todo items
    @Component
    class RestRepositoryConfigurator implements RepositoryRestConfigurer {
        public void configureRepositoryRestConfiguration(RepositoryRestConfiguration config, CorsRegistry cors) {
            config.exposeIdsFor(Todo.class);
        }
    }

}

This demo application does three things that are helpful for demonstration purposes. First, it loads some test todo items into the repository.

Second, it configures the REST repository to expose IDs for the todo items.

Third, it defines a filter to allow cross-origin requests from http://localhost:8080. This is necessary so that the Vue application, which is loaded from http://localhost:9000 via the local test server, can load data from the Spring Boot resource server at http://localhost:8080.

For more info on CORS (cross-origin resource sharing), take a look at the Mozilla docs.

Now, create the data model for the todo items.

src/main/java/com/example/demo/Todo.java

package com.example.demo;

import lombok.*;

import jakarta.persistence.Id;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.Entity;

@Entity
@Data
@NoArgsConstructor
public class Todo {

    @Id 
    @GeneratedValue
    private Long id;

    @NonNull
    private String title;

    private Boolean completed = false;

}

Notice the use of the Lombok annotations (@Entity, @Data, and @NoArgsConstructor) to keep the code simple and clean.

The todo items have two fields: a title string and a completed boolean. The fields are annotated with Spring Data JPA annotations that allow the Java class to be mapped to a database table for persistence.

Create a repository to persist the data model.

src/main/java/com/example/demo/TodoRepository.java

package com.example.demo;

import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.rest.core.annotation.RepositoryRestResource;

@RepositoryRestResource
interface TodoRepository extends JpaRepository<Todo, Long> {}

This is a Spring Data JpaRepository that can persist the data model you just defined. Because it is annotated with @RepositoryRestResource (and because the data-rest dependency was included), this repository will be automatically exposed as a web resource.

Test your Vue and Spring Boot app

Run the app using the following command from the resource-server subdirectory.

./gradlew bootRun

Open a new Bash shell and use HTTPie to test the resource server.

http :9000/todos

You should see a response like the following:

HTTP/1.1 200 
...

{
  "_embedded": {
    "todos": [
      {
        "_links": {
          "self": {
            "href": "http://localhost:9000/todos/1"
          },
          "todo": {
            "href": "http://localhost:9000/todos/1"
          }
        },
        "completed": false,
        "id": 1,
        "title": "Buy milk"
      },
      {
        "_links": {
          "self": {
            "href": "http://localhost:9000/todos/2"
          },
          "todo": {
            "href": "http://localhost:9000/todos/2"
          }
        },
        "completed": true,
        "id": 2,
        "title": "Eat pizza"
      },
      ...
    ]
  },
  ...
}

Stop the resource server using CTRL + C.

Secure your Spring Boot API

Edit the SecurityConfiguration.java file and change the filter chain's bean definition to enable a resource server.

src/main/java/com/example/demo/OAuth2ResourceServerSecurityConfiguration.java

@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http.authorizeHttpRequests()
        .anyRequest().authenticated()
        .and()
        .oauth2ResourceServer().jwt();
    return http.build();
}

This configuration requires JWT auth on all requests.

Restart the server. Use CTRL + C to stop it if it's running.

./gradlew bootRun

Use HTTPie again to try and request the todo items.

http :9000/todos

You will get an error.

HTTP/1.1 401 
...

401 Unauthorized

The resource server is finished. The next step is to create the Vue client.

Create a Vue JavaScript client

Use the Vue CLI to create a new application from the project's root directory and navigate into the newly created client directory. Install the Vue CLI if you don't have it installed with npm i -g @vue/cli@5.

vue create client

Pick Default ([Vue 3] babel, eslint) when prompted. Wait for it to finish.

cd client

Add the Quasar framework.

vue add quasar

You can just accept the defaults. For me, they were the following.

Allow Quasar to replace App.vue, About.vue, Home.vue and (if available) router.js? Yes
Pick your favorite CSS preprocessor: Sass with indented syntax
Choose Quasar Icon Set: Material Icons (recommended)
Default Quasar language pack: en-US
Use RTL support? No
Select features: Enter to select none

Add additional dependencies for HTTP requests, logging, routing, and authentication.

npm i axios@1.2.3 vuejs3-logger@1.0.0 vue-router@4.1.6 @okta/okta-vue@5.5.0

axios: an HTTP client request library
vuejs3-logger: a logging library
vue-router: the standard for routing between pages in Vue
okta/okta-vue: the Okta helper for Vue

To learn more about how Okta integrates with Vue, look at the GitHub page for the okta/okta-vue project. More resources and example applications are listed in the Okta docs for Vue.

Replace main.js with the following. Look at the OktaAuth configuration object. Notice the client ID and issuer URI are pulled from a .env file.

src/main.js

import { createApp } from 'vue'
import App from './App.vue'
import { Quasar } from 'quasar'
import quasarUserOptions from './quasar-user-options'
import VueLogger from 'vuejs3-logger'
import router from './router'
import createApi from './Api'

import { OktaAuth } from '@okta/okta-auth-js'
import OktaVue from '@okta/okta-vue'

if (process.env.VUE_APP_ISSUER_URI == null || process.env.VUE_APP_CLIENT_ID == null || process.env.VUE_APP_SERVER_URI == null) {
  throw 'Please define VUE_APP_ISSUER_URI, VUE_APP_CLIENT_ID, and VUE_APP_SERVER_URI in .env file'
}

const oktaAuth = new OktaAuth({
  issuer: process.env.VUE_APP_ISSUER_URI,  // pulled from .env file
  clientId: process.env.VUE_APP_CLIENT_ID,  // pulled from .env file
  redirectUri: window.location.origin + '/callback',
  scopes: ['openid', 'profile', 'email']
})

const options = {
  isEnabled: true,
  logLevel: 'debug',
  stringifyArguments: false,
  showLogLevel: true,
  showMethodName: false,
  separator: '|',
  showConsoleColors: true
};

const app = createApp(App)
  .use(Quasar, quasarUserOptions)
  .use(VueLogger, options)
  .use(OktaVue, {oktaAuth})
  .use(router)

app.config.globalProperties.$api = createApi(app.config.globalProperties.$auth)

app.mount('#app')

Stated very briefly, the file above creates the main Vue app and configures it to use the dependencies you added: Quasar, VueLogger, OktaVue, and the router. It also creates the API class that handles the requests to the resource server and passes it the $auth object it needs to get the JWT.

Create a .env file in the client project root directory. The Client ID and Issuer URI are the values you used above in the Spring Boot application.properties file. The Server URI is the local URI for the Spring Boot API. You can leave this unless you made a change (this gets used in the Api.js file).

.env

VUE_APP_CLIENT_ID=<your-client-id>
VUE_APP_ISSUER_URI=<your-issuer-uri>
VUE_APP_SERVER_URI=http://localhost:9000

It's important to note that putting values like this in a .env file in a client application does not make them secure. It helps by keeping them out of a repository. However, they are still public because they are necessarily visible in the JavaScript code sent to the browser. In this use case, it's more of a configuration and organizational tool than a security tool.

If you want to keep the .env file out of the repository, you need to update the .gitignore file. There's no particular need to do this for the Client ID as it will be publicly available anyway.

Replace App.vue with the following.

src/App.vue

<template>
  <q-layout view="hHh lpR fFf">

    <q-header elevated class="bg-primary text-white">
      <q-toolbar>
        <q-toolbar-title>
          <q-avatar>
            <q-icon name="kayaking" size="30px"></q-icon>
          </q-avatar>
          Todo App
        </q-toolbar-title>
        {{ this.claims && this.claims.email ? claims.email : '' }}
        <q-btn flat round dense icon="logout" v-if='authState && authState.isAuthenticated' @click="logout"/>
        <q-btn flat round dense icon="account_circle" v-else @click="login"/>
      </q-toolbar>
    </q-header>

    <q-page-container>
      <router-view></router-view>
    </q-page-container>

  </q-layout>
</template>

<script>
export default {
  name: 'LayoutDefault',
  data: function () {
    return {
      claims: null
    }
  },
  watch: {
    'authState.isAuthenticated'() {
      this.$log.debug(('watch triggered!'))
      this.updateClaims()
    }
  },
  created() {
    this.updateClaims()
  },
  methods: {
    async updateClaims() {
      if (this.authState && this.authState.isAuthenticated) {
        this.claims = await this.$auth.getUser()
      }
    },
    async login() {
      await this.$auth.signInWithRedirect({ originalUri: '/todos' })
    },
    async logout() {
      await this.$auth.signOut()
    }
  },
}
</script>

This top-level component defines the header bar and includes the router component. The header bar has a login or logout button and will show the authenticated user's email address when logged in.

The app gets the authenticated user's email address from the JWT claims. (A claim is a piece of information asserted about the subject by the authenticating authority.) This happens in the updateClaims() method, which is triggered when the component is created, and is also triggered by a watch method so that it is updated as the authenticated state changes.

Create a new file to encapsulate the resource server access logic.

src/Api.js

import axios from 'axios'

const instance = axios.create({
  baseURL: process.env.VUE_APP_SERVER_URI,
  timeout: 2000
});

const createApi = (auth) => {

  instance.interceptors.request.use(async function (config) {
    const accessToken = auth.getAccessToken()
    config.headers = {
      Authorization: `Bearer ${accessToken}`
    }
    return config;
  }, function (error) {
    return Promise.reject(error);
  });

  return {

    // (C)reate
    createNew(text, completed) {
      return instance.post('/todos', {title: text, completed: completed})
    },

    // (R)ead
    getAll() {
      return instance.get('/todos', {
        transformResponse: [function (data) {
          return data ? JSON.parse(data)._embedded.todos : data;
        }]
      })
    },

    // (U)pdate
    updateForId(id, text, completed) {
      return instance.put('todos/' + id, {title: text, completed: completed})
    },

    // (D)elete
    removeForId(id) {
      return instance.delete('todos/' + id)
    }
  }
}

export default createApi

All of the requests to the server go through this module. Take a look at how the access token is retrieved from the global auth object and injected into every request.

Create the router file.

src/router/index.js

import { createRouter, createWebHistory } from 'vue-router'
import { navigationGuard } from '@okta/okta-vue'
import Todos from '@/components/Todos';
import Home from '@/components/Home';
import { LoginCallback } from '@okta/okta-vue'

const routes = [
  {
    path: '/',
    component: Home
  },
  {
    path: '/todos',
    component: Todos,
    meta: {
      requiresAuth: true
    }
  },
  { path: '/callback', component: LoginCallback },
]

const router = createRouter({
  history: createWebHistory(process.env.BASE_URL),
  routes,
})

router.beforeEach(navigationGuard)

export default router

The router has three paths. The home path and the todos path are straightforward. The Okta Vue SDK provides the last path, /callback, to handle the login redirect from the Okta servers after authentication.

Create the Home component.

src/components/Home.vue

<template>
  <div class="column justify-center items-center" id="row-container">
    <q-card class="my-card">
      <q-card-section style="text-align: center">
        <div v-if='authState && authState.isAuthenticated'>
          <h6 v-if="claims && claims.email">You are logged in as {{ claims.email }}</h6>
          <h6 v-else>You are logged in</h6>
          <q-btn flat color="primary" @click="todo">Go to Todo app</q-btn>
          <q-btn flat @click="logout">Log out</q-btn>
        </div>
        <div v-else>
          <h6>Please <a href="#" @click.prevent="login">log in</a> to access Todo app</h6>
        </div>
      </q-card-section>
    </q-card>
  </div>
</template>

<script>
export default {
  name: 'home-component',
  data: function () {
    return {
      claims: ''
    }
  },
  created() { 
    this.setup() 
  },
  methods: {
    async setup() {
      if (this.authState && this.authState.isAuthenticated) {
        this.claims = await this.$auth.getUser()
      }
    },
    todo() {
      this.$router.push('/todos')
    },
    async login() {
      await this.$auth.signInWithRedirect({ originalUri: '/todos' })
    },
    async logout() {
      await this.$auth.signOut()
    }
  }
}
</script>

Create the TodoItem component.

src/components/TodoItem.vue

<template>
  <q-item-section avatar class="check-icon" v-if="this.item.completed">
    <q-icon color="green" name="done" @click="handleClickSetCompleted(false)"/>
  </q-item-section>
  <q-item-section avatar class="check-icon" v-else>
    <q-icon color="gray" name="check_box_outline_blank" @click="handleClickSetCompleted(true)"/>
  </q-item-section>
  <q-item-section v-if="!editing">{{ this.item.title }}</q-item-section>
  <q-item-section v-else>
    <input
        class="list-item-input"
        type="text"
        name="textinput"
        ref="input"
        v-model="editingTitle"
        @change="handleDoneEditing"
        @blur="handleCancelEditing"
    />
  </q-item-section>
  <q-item-section avatar class="hide-icon" @click="handleClickEdit">
    <q-icon color="primary" name="edit"/>
  </q-item-section>
  <q-item-section avatar class="hide-icon close-icon" @click="handleClickDelete">
    <q-icon color="red" name="close"/>
  </q-item-section>
</template>
<script>

import { nextTick } from 'vue'

export default {
  name: 'TodoItem',
  props: {
    item: Object,
    deleteMe: Function,
    showError: Function,
    setCompleted: Function,
    setTitle: Function
  },
  data: function () {
    return {
      editing: false,
      editingTitle: this.item.title,
    }
  },
  methods: {
    handleClickEdit() {
      this.editing = true
      this.editingTitle = this.item.title
      nextTick(function () {
        this.$refs.input.focus()
      }.bind(this))
    },
    handleCancelEditing() {
      this.editing = false
    },
    handleDoneEditing() {
      this.editing = false
      this.$api.updateForId(this.item.id, this.editingTitle, this.item.completed).then((response) => {
        this.setTitle(this.item.id, this.editingTitle)
        this.$log.info('Item updated:', response.data);
      }).catch((error) => {
        this.showError('Failed to update todo title')
        this.$log.debug(error)
      });
    },
    handleClickSetCompleted(value) {
      this.$api.updateForId(this.item.id, this.item.title, value).then((response) => {
        this.setCompleted(this.item.id, value)
        this.$log.info('Item updated:', response.data);
      }).catch((error) => {
        this.showError('Failed to update todo completed status')
        this.$log.debug(error)
      });
    },
    handleClickDelete() {
      this.deleteMe(this.item.id)
    }
  }
}
</script>

<style scoped>
.todo-item .close-icon {
  min-width: 0px;
  padding-left: 5px !important;
}

.todo-item .hide-icon {
  opacity: 0.1;
}

.todo-item:hover .hide-icon {
  opacity: 0.8;
}

.check-icon {
  min-width: 0px;
  padding-right: 5px !important;
}

input.list-item-input {
  border: none;
}
</style>

This component encapsulates a single todo item. It has logic for editing the title, setting the completed status, and deleting items. If you look closely at the code, you'll notice that it sends changes to the server and updates the local copy stored in the todos array in the parent component.

Create the Todos component.

src/components/Todos.vue

<template>
  <div class="column justify-center items-center" id="row-container">
    <q-card class="my-card">
      <q-card-section>
        <div class="text-h4">Todos</div>
        <q-list padding>
          <q-item
              v-for="item in filteredTodos" :key="item.id"
              clickable
              v-ripple
              rounded
              class="todo-item"
          >
            <TodoItem
                :item="item"
                :deleteMe="handleClickDelete"
                :showError="handleShowError"
                :setCompleted="handleSetCompleted"
                :setTitle="handleSetTitle"
                v-if="filter === 'all' || (filter === 'incomplete' && !item.completed) || (filter === 'complete' && item.completed)"
            ></TodoItem>
          </q-item>
        </q-list>
      </q-card-section>
      <q-card-section>
        <q-item>
          <q-item-section avatar class="add-item-icon">
            <q-icon color="green" name="add_circle_outline"/>
          </q-item-section>
          <q-item-section>
            <input
                type="text"
                ref="newTodoInput"
                v-model="newTodoTitle"
                @change="handleDoneEditingNewTodo"
                @blur="handleCancelEditingNewTodo"
            />
          </q-item-section>
        </q-item>
      </q-card-section>
      <q-card-section style="text-align: center">
        <q-btn color="amber" text-color="black" label="Remove Completed" style="margin-right: 10px" 
               @click="handleDeleteCompleted"></q-btn>
        <q-btn-group>
          <q-btn glossy :color="filter === 'all' ? 'primary' : 'white'" text-color="black" label="All" 
                 @click="handleSetFilter('all')"/>
          <q-btn glossy :color="filter === 'complete' ? 'primary' : 'white'" text-color="black" label="Completed" 
                 @click="handleSetFilter('complete')"/>
          <q-btn glossy :color="filter === 'incomplete' ? 'primary' : 'white'" text-color="black" label="Incomplete" 
                 @click="handleSetFilter('incomplete')"/>
          <q-tooltip>
            Filter the todos
          </q-tooltip>
        </q-btn-group>
      </q-card-section>
    </q-card>
    <div v-if="error" class="error">
      <q-banner inline-actions class="text-white bg-red" @click="handleErrorClick">
        ERROR: {{ this.error }}
      </q-banner>
    </div>
  </div>
</template>

<script>

import TodoItem from '@/components/TodoItem';
import { ref } from 'vue'

export default {
  name: 'LayoutDefault',
  components: {
    TodoItem
  },

  data: function() {
    return {
      todos: [],
      newTodoTitle: '',
      visibility: 'all',
      loading: true,
      error: '',
      filter: 'all'
    }
  },

  setup() {
    return {
      alert: ref(false),
    }
  },
  mounted() {
    this.$api.getAll()
        .then(response => {
          this.$log.debug('Data loaded: ', response.data)
          this.todos = response.data
        })
        .catch(error => {
          this.$log.debug(error)
          this.error = 'Failed to load todos'
        })
        .finally(() => this.loading = false)
  },

  computed: {
    filteredTodos() {
      if (this.filter === 'all') return this.todos
      else if (this.filter === 'complete') return this.todos.filter(todo => todo.completed)
      else if (this.filter === 'incomplete') return this.todos.filter(todo => !todo.completed)
      else return []
    }
  },

  methods: {
    handleSetFilter(value) {
      this.filter = value
    },

    handleClickDelete(id) {
      const todoToRemove = this.todos.find(todo => todo.id === id)
      this.$api.removeForId(id).then(() => {
        this.$log.debug('Item removed:', todoToRemove);
        this.todos.splice(this.todos.indexOf(todoToRemove), 1)
      }).catch((error) => {
        this.$log.debug(error);
        this.error = 'Failed to remove todo'
      });
    },

    handleDeleteCompleted() {
      const completed = this.todos.filter(todo => todo.completed)
      Promise.all(completed.map(todoToRemove => {
        return this.$api.removeForId(todoToRemove.id).then(() => {
          this.$log.debug('Item removed:', todoToRemove);
          this.todos.splice(this.todos.indexOf(todoToRemove), 1)
        }).catch((error) => {
          this.$log.debug(error);
          this.error = 'Failed to remove todo'
          return error
        })
      }))
    },

    handleDoneEditingNewTodo() {
      const value = this.newTodoTitle && this.newTodoTitle.trim()
      if (!value) {
        return
      }
      this.$api.createNew(value, false).then((response) => {
        this.$log.debug('New item created:', response)
        this.newTodoTitle = ''
        this.todos.push({
          id: response.data.id,
          title: value,
          completed: false
        })
        this.$refs.newTodoInput.blur()
      }).catch((error) => {
        this.$log.debug(error);
        this.error = 'Failed to add todo'
      });
    },
    handleCancelEditingNewTodo() {
      this.newTodoTitle = ''
    },

    handleSetCompleted(id, value) {
      let todo = this.todos.find(todo => id === todo.id)
      todo.completed = value
    },

    handleSetTitle(id, value) {
      let todo = this.todos.find(todo => id === todo.id)
      todo.title = value
    },

    handleShowError(message) {
      this.error = message
    },

    handleErrorClick() {
      this.error = null;
    },
  },
}
</script>

<style>
#row-container {
  margin-top: 100px;
}

.my-card {
  min-width: 600px;
}

.error {
  color: red;
  text-align: center;
  min-width: 600px;
  margin-top: 10px;
}
</style>

This component encapsulates the card that holds all of the todos and the todo-associated interface elements. It also handles the rest of the functions related to updating todos on the server and in the local cache.

You're welcome to delete the HelloWorld.vue component if you want. Or you can leave it. It's not needed.

Confirm your Spring Boot and Vue todo app works

Make sure the Spring Boot API is still running. In a separate Bash shell, from the resource server directory, run the following command (if it is not already still running).

./gradlew bootRun

Start the Vue app using the embedded development server. From the client directory:

npm run serve

Open a browser and navigate to http://localhost:8080. You'll see the "please log in" page.

Log into the app using Okta's sign-in interface.

That will redirect you to the Todo app's main screen.

You should be able to delete items, add new items, rename, and filter items. All data is stored on the Spring Boot resource server and is presented by the Vue + Quasar frontend.

Use Auth0 to secure the API

You can also use Auth0 to secure the application! Let's start with the API (in the resource-server directory of the GitHub repo or your main project).

The first step is to open the build.gradle file for the Spring Boot project and update the dependencies. You have to remove the Okta Spring Boot Starter (as it does not work with Auth0 yet) and add in some Spring Security dependencies that were being included by the Okta starter.

Update the implementation dependencies in build.gradle.

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.springframework.boot:spring-boot-starter-data-rest'
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.security:spring-security-oauth2-resource-server'
    implementation 'org.springframework.boot:spring-boot-starter-security'
    implementation 'org.springframework.security:spring-security-config'
    implementation 'org.springframework.security:spring-security-oauth2-jose'

    compileOnly 'org.projectlombok:lombok'
    runtimeOnly 'com.h2database:h2'
    annotationProcessor 'org.projectlombok:lombok'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

Create an AudienceValidator class. This will validate JWTs very simply by checking to make sure the audience matches what is loaded from the application properties and passed into the constructor.
src/main/java/com/example/demo/AudienceValidator.java

package com.example.demo;

import org.springframework.security.oauth2.core.OAuth2Error;
import org.springframework.security.oauth2.core.OAuth2TokenValidator;
import org.springframework.security.oauth2.core.OAuth2TokenValidatorResult;
import org.springframework.security.oauth2.jwt.Jwt;

class AudienceValidator implements OAuth2TokenValidator<Jwt> {
    private final String audience;

    AudienceValidator(String audience) {
        this.audience = audience;
    }

    public OAuth2TokenValidatorResult validate(Jwt jwt) {
        OAuth2Error error = new OAuth2Error("invalid_token", "The required audience is missing", null);

        if (jwt.getAudience().contains(audience)) {
            return OAuth2TokenValidatorResult.success();
        }
        return OAuth2TokenValidatorResult.failure(error);
    }
}

You need to add a JWT validator bean to the security configuration class. This uses the AudienceValidator class you added above to validate JWTs. Update the SecurityConfiguration class to the following.

src/main/java/com/example/demo/SecurityConfiguration.java

package com.example.demo;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.oauth2.core.DelegatingOAuth2TokenValidator;
import org.springframework.security.oauth2.core.OAuth2TokenValidator;
import org.springframework.security.oauth2.jwt.*;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
public class SecurityConfiguration {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http.authorizeHttpRequests()
            .anyRequest().authenticated()
            .and()
            .oauth2ResourceServer().jwt();
        return http.build();
    }

    @Value("${auth0.audience}")
    private String audience;

    @Value("${spring.security.oauth2.resourceserver.jwt.issuer-uri}")
    private String issuer;

    @Bean
    JwtDecoder jwtDecoder() {
        NimbusJwtDecoder jwtDecoder = (NimbusJwtDecoder)
            JwtDecoders.fromOidcIssuerLocation(issuer);

        OAuth2TokenValidator<Jwt> audienceValidator = new AudienceValidator(audience);
        OAuth2TokenValidator<Jwt> withIssuer = JwtValidators.createDefaultWithIssuer(issuer);
        OAuth2TokenValidator<Jwt> withAudience = new DelegatingOAuth2TokenValidator<>(withIssuer, audienceValidator);

        jwtDecoder.setJwtValidator(withAudience);

        return jwtDecoder;
    }
}

Install the Auth0 CLI and run auth0 login in a terminal.

Waiting for the login to complete in the browser... done

 ▸    Successfully logged in.
 ▸    Tenant: dev-0xb84jzp.us.auth0.com

Take note of the domain listed as the tenant. This is your Auth0 domain. If you need to find it again later, you can use auth0 tenants list.

Update src/main/resources/application.properties. Fill in your actual Auth0 domain.

server.port=9000
auth0.audience=http://my-api
spring.security.oauth2.resourceserver.jwt.issuer-uri=https://<your-auth0-domain>/

Start the API.

./gradlew bootRun

Make sure it starts successfully.

2022-10-06 10:09:59.535  INFO 89160 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 9000 (http) with context path ''
2022-10-06 10:09:59.541  INFO 89160 --- [           main] com.example.demo.DemoApplication         : Started DemoApplication in 3.014 seconds (JVM running for 3.252)
Todo(id=1, title=Buy milk, completed=false)
Todo(id=2, title=Eat pizza, completed=false)
Todo(id=3, title=Update tutorial, completed=true)
Todo(id=4, title=Study Vue, completed=false)
Todo(id=5, title=Go kayaking, completed=true)
<==========---> 80% EXECUTING [2m 58s]
> :bootRun

Open a second terminal window in the same directory. Create a test Auth0 API. The Auth0 API is what exposes identity functionality for all authentication and authorization protocols, such as OpenID Connect and OAuth.

auth0 apis create -n myapi --identifier http://my-api

Just press enter three times to accept the default values for scopes, token lifetime, and allow offline access. The scopes here refer to custom scopes, not the standard scopes (email, profile, and openid) that you will need for OIDC and OAuth.

 Scopes: 
 Token Lifetime: 86400
 Allow Offline Access: No

=== dev-0xb84jzp.us.auth0.com API created

  ID                    6323478u98u98919206c2f73e6d  
  NAME                  myapi                     
  IDENTIFIER            http://my-api             
  SCOPES                                          
  TOKEN LIFETIME        86400                     
  ALLOW OFFLINE ACCESS  ✗

Use Auth0 CLI to create a token. Don't forget to set the audience!

auth0 test token -a http://my-api

If you don't use the -a flag to set the audience to your Auth0 API, the test token you create will be an opaque token that cannot be verified and will not work. If you decide to use a different Auth0 API for some reason, you need to make sure the audience identifiers match in the application.properties file and the command to create a test token.

Save the token in a shell variable.

TOKEN=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Im5yMWZw...

You can verify that the endpoint is protected.

http :9000/todos

And test the protected endpoint using the token.

http :9000/todos "Authorization: Bearer $TOKEN"

Update the Vue client to use Auth0

Auth0 has helpful docs for integrating with Vue. The first step is to create an OpenID Connect (OIDC) application on the Auth0 servers using their CLI. Open a terminal and navigate to the client project directory.

auth0 apps create

Name: vue-spring-boot
Type: Single Page Web Application
All the URLs: http://localhost:8080

 Name: vue-spring-boot
 Description: 
 Type: Single Page Web Application
 Callback URLs: http://localhost:8080
 Allowed Logout URLs: http://localhost:8080
 Allowed Origin URLs: http://localhost:8080
 Allowed Web Origin URLs: http://localhost:8080

=== dev-0rb77iup.us.auth0.com application created

Update the .env file. Fill in the OIDC Client ID and Auth0 domain.

VUE_APP_CLIENT_ID=<your-client-id>
VUE_APP_AUTH0_DOMAIN=<your-auth0-domain>
VUE_APP_AUTH0_AUDIENCE=http://my-api
VUE_APP_SERVER_URI=http://localhost:9000

Notice that the audience is the same as the audience used to create the test token, which is the Auth0 API.

Install the Auth0 Vue SDK. Make sure you're in the client directory.

npm install @auth0/auth0-vue@2

If you want, you can remove the Okta Vue SDK.

npm remove @okta/okta-vue

Update src/main.js to the following. This configures and installs the Auth0 plugin for Vue.

import { createApp } from 'vue'
import App from './App.vue'
import { Quasar } from 'quasar'
import quasarUserOptions from './quasar-user-options'
import VueLogger from 'vuejs3-logger'
import router from './router'
import createApi from './Api'

import { createAuth0 } from '@auth0/auth0-vue';

const options = {
  isEnabled: true,
  logLevel: 'debug',
  stringifyArguments: false,
  showLogLevel: true,
  showMethodName: false,
  separator: '|',
  showConsoleColors: true
};

const app = createApp(App)
  .use(Quasar, quasarUserOptions)
  .use(VueLogger, options)
  .use(router)
  .use(createAuth0({
      domain: process.env.VUE_APP_AUTH0_DOMAIN,
      clientId: process.env.VUE_APP_CLIENT_ID,
      authorizationParams: {
        redirect_uri: window.location.origin,
        audience: process.env.VUE_APP_AUTH0_AUDIENCE
      }
    })
  );

// pass auth0 to the api (to get a JWT), which is set as a global property
app.config.globalProperties.$api = createApi(app.config.globalProperties.$auth0)

app.mount('#app')

Update one line in src/Api.js. You need to change the following line.

const accessToken = auth.getAccessToken()

To this.

const accessToken = await auth.getAccessTokenSilently();

As is seen below.

import axios from 'axios'

...

const createApi = (auth) => {

  instance.interceptors.request.use(async function (config) {
    const accessToken = await auth.getAccessTokenSilently(); // UPDATE ME
    config.headers = {
      Authorization: `Bearer ${accessToken}`
    }
    return config;
  }, function (error) {
    return Promise.reject(error);
  });

  ...

}

export default createApi

Update src/App.vue.

<template>
  <q-layout view="hHh lpR fFf">

    <q-header elevated class="bg-primary text-white">
      <q-toolbar>
        <q-toolbar-title>
          <q-avatar>
            <q-icon name="kayaking" size="30px"></q-icon>
          </q-avatar>
          Todo App
        </q-toolbar-title>
        {{ isAuthenticated ? user.email : "" }}
        <q-btn flat round dense icon="logout" v-if='isAuthenticated' @click="logout"/>
        <q-btn flat round dense icon="account_circle" v-else @click="login"/>
      </q-toolbar>
    </q-header>

    <q-page-container>
      <router-view></router-view>
    </q-page-container>

  </q-layout>
</template>

<script>

import { useAuth0 } from '@auth0/auth0-vue';

export default {
  setup() {

    const { loginWithRedirect, user, isAuthenticated, logout } = useAuth0();

    return {
      login: () => {
        loginWithRedirect();
      },
      logout: () => {
        logout({ logoutParams: { returnTo: window.location.origin } });
      },
      user,
      isAuthenticated
    };
  }
}
</script>

Update src/components/Home.vue.

<template>
  <div class="column justify-center items-center" id="row-container">
    <q-card class="my-card">
      <q-card-section style="text-align: center">
        <div v-if='isAuthenticated'>
          <h6>You are logged in as {{user.email}}</h6>
          <q-btn flat color="primary" @click="todo">Go to Todo app</q-btn>
          <q-btn flat @click="logout">Log out</q-btn>
        </div>
        <div v-else>
          <h6>Please <a href="#" @click.prevent="login">log in</a> to access Todo app</h6>
        </div>
      </q-card-section>
    </q-card>
  </div>
</template>

<script>

import { useAuth0 } from '@auth0/auth0-vue';
import { useRouter } from 'vue-router'

export default {
  name: 'HomeComponent',
  setup() {

    const { loginWithRedirect, user, isAuthenticated, logout } = useAuth0();
    const router = useRouter()

    return {
      login: () => {
        loginWithRedirect();
      },
      logout: () => {
        logout({ returnTo: window.location.origin });
      },
      todo() {
        router.push('/todos')
      },
      user,
      isAuthenticated
    };
  }
}
</script>

Finally, update src/router/index.js.

import { createRouter, createWebHistory } from 'vue-router'
import Todos from '@/components/Todos';
import Home from '@/components/Home';

const routes = [
  {
    path: '/',
    component: Home
  },
  {
    path: '/todos',
    component: Todos,
    meta: {
      requiresAuth: true
    }
  },
]

const router = createRouter({
  history: createWebHistory(process.env.BASE_URL),
  routes,
})

export default router

The usage of the Auth0 SDK is pretty similar to the Okta Vue SDK. If you have any questions, take a look at the auth0-vue GitHub repository.

Make sure your Spring Boot API is still running. Run the client.

npm run serve

This time when you log in you will be directed to Auth0.

After that, you will be redirected back to the todo app.

Do more with Spring Boot, Vue, and Okta

You built a Spring Boot resource server backend and a Vue frontend in this tutorial. The Vue client used the latest Vue 3 version with the Quasar framework. The app included full CRUD (create, read, update, and delete) capabilities. It was all secured first using Okta, and then, a second time, via Auth0.

You can find the source code for this example on GitHub in the @oktadev/okta-spring-boot-vue-crud-example repository.

If you liked this post, there's a good chance you'll like similar ones:

If you have questions, please ask them in the comments below! If you're into social media, follow us: @oktadev on Twitter, Okta for Developers on LinkedIn, and OktaDev on Facebook. If you like learning via video, subscribe to our YouTube channel.

Create Kubernetes Microservices on Azure with Cosmos DB

Andrew Hughes — Fri, 17 Jun 2022 03:45:43 +0000

In this tutorial, you'll learn how to deploy a JHipster-based reactive microservice to Azure Kubernetes Service (AKS). You'll use Azure's Cosmos DB as a persistent store for one of the services. For security, you'll use Okta as an OAuth 2.0 and OpenID Connect (OIDC) provider. You'll also securely encrypt all secrets in the project configuration files using Kubernetes secrets and kubeseal. This tutorial focuses on deploying an already generated project to Azure AKS. It does not go into great detail about generating the project. To see how the project was generated using JHipster, take a look at Reactive Java Microservices with Spring Boot and JHipster.

The project has a few different pieces:

JHipster Registry: a Eureka server for service discovery and a Spring Cloud Config server for centralized configuration management
Gateway: public Spring Cloud Gateway application using Vue
Store: Spring Boot microservice using Azure's Cosmo DB API for MongoDB
Blog: Spring Boot microservice using a Neo4J database

This tutorial has a lot of different technologies in it. I've tried to make it as simple and as explicit as possible, but it's probably helpful to have some basic knowledge of Docker and Kubernetes before you start.

If you're already familiar with all the tech in this tutorial, you can skip ahead to the prerequisites section. If not, I'm going to explain them a little before we move on.

JHipster microservices architecture overview

JHipster is a development platform that streamlines the generation, development, and deployment of both monolithic and microservice applications. It supports a dizzying array of frontend (Angular, React, and Vue) and backend (Spring Boot, Micronaut, Quarkus, Node.js, and .NET) technologies. It's designed to be deployed using Docker and Kubernetes, and can easily deploy to all the major cloud platforms, such as AWS, Azure, Heroku, Cloud Foundry, Google Cloud Platform, and OpenShift.

The project in this tutorial uses Spring Boot with Java resource servers and a Vue frontend. It was built with the JHipster generator that quickly scaffolds a new application based on either an interactive shell or a DSL file. You can read more about generating microservices with JHipster in their docs. One of the slick features of the JHipster generator is that you can generate data entities along with applications.

The JHipster Registry that is generated with the microservice includes two important functions: a Eureka server and a Spring Cloud Config server. The Eureka server allows the microservices to dynamically find each other without having to use hard-coded URIs. This means that the microservice can scale and services can be replaced without causing problems. It's a bit like a phonebook or a DNS service for the microservice. The Spring Cloud Config server allows project configuration to be centralized and distributed to all of the different services. In this tutorial you'll use this feature to configure all of the services for Okta OAuth in one place.

The JHipster API Gateway is the public face of your microservice. All public traffic comes through this service, which also includes the Vue frontend. The gateway is one of three application types that can be created by the JHipster generator DSL. The other two are monolith and microservice. A monolith is a non-microservice application with a single service.

The store service and blog service are both examples of the microservice application type. This means that each service is a Spring Boot resources server with some type of SQL or NoSQL backend.

The generator creates four applications. They are designed to be built and run as docker containers, which makes it easy for them to be packaged in Kubernetes pods. Kubernetes is a container orchestrator specifically designed for managing microservice networks. It's something like Docker Compose but designed for microservices with a lot of great features like service discovery, load balancing, automatic rollouts and restarts, resource management, and storage mounting.

Prerequisites

This tutorial has a lot of pieces. Install the required software below and sign up for an Azure Cloud account. You'll need a free Okta account, but you can use the Okta CLI to sign up for it later in the tutorial.

Docker: you'll need to have both Docker Engine and Docker Compose installed (If you install the Docker desktop, this will automatically install both. On Linux, if you install Docker Engine individually, you will have to also install Docker Compose) separately.
Docker Hub: you'll need a Docker Hub to host the docker images so that Azure can pull them.
Java 11: this tutorial requires Java 11. If you need to manage multiple Java versions, SDKMAN! is a good solution. Check out their docs to install it.
Okta CLI: you'll use Okta to add security to the microservice network. You can register for a free account from the CLI.
Azure Cloud account: they offer a free-tier account with a $200 credit to start.
Azure CLI: you'll use the Azure CLI to manage the Kubernetes cluster.
kubectl: CLI to manage Kubernetes clusters.

If you have never had an Azure account before, you can create a new one that will allow free-tier access and has $200 credit allocated to it. This is more than enough to finish this tutorial. However, the credit does expire after 30 days. If you do not have credit left or your credit has expired, this tutorial should only cost a few dollars if you stop and start the AKS cluster when you are not working on it. You can keep an eye on your costs using the cost explorer in the Azure portal and set alerts if you are concerned about it. Upgrading to pay-as-you-go may also alleviate some resource throttling issues around testing the AKS clusters.

Spring Boot microservices for Azure and Cosmos DB

This project is based on two of Matt Raible's tutorials: Reactive Java Microservices with Spring Boot and JHipster and Kubernetes to the Cloud with Spring Boot and JHipster. In these tutorials, he builds a reactive Java microservice architecture and shows how to deploy it to Google Cloud (GCP). I have modified the project to work with Azure and Cosmos DB.

You will first run the project using Docker Compose. Once you have this working, you will run the project as a Kubernetes cluster on Azure. My modifications were relatively minor and involved removing the unnecessary MongoDB instances (from both the docker-compose.yml file and from the Kubernetes descriptors) as well as updating environment values to point the store service to the Cosmos DB instance instead of a MongoDB instance.

Listed briefly, the changes I made from Matt Raible's posts to make this work with Azure and Cosmos DB are as follows. You can skip this list (and the next section) and go right to cloning the Git repository if you want, but since this documents how to update a JHipster-generated project to use Cosmos DB, I thought it was worth including.

In the docker-compose/docker-compose.yml file:

removed the MongoDB service
updated the store service property SPRING_DATA_MONGODB_URI to point to the Cosmos DB instance via a .env file
removed the Keycloak service and the environment variables that configured auth to use Keycloak from the remaining services (not strictly necessary but cleaned things up)

In the k8s/store-k8s directory:

removed the store-mongodb.yml file (This creates the MongoDB Kubernetes service that our project does not need.)
in store-deployment.yml:
- removed the initContainers (The init container waits for the MongoDB instance, which is removed.)
- updated SPRING_DATA_MONGODB_URI env value of the store-app container to the Cosmos DB URI (This points the store to the Cosmos DB instance.)
- properly secured the Cosmos DB connection string using Kubernetes secrets and kubeseal

Setting the store app's initial status for Eureka

Creating this tutorial, I ran into a problem with the store app getting stuck as OUT_OF_SERVICE. When I inspected the logs, I found that the service started as UP, quickly went to DOWN, and then OUT_OF_SERVICE. Later, it would go back to UP but the Eureka server never registered this change.

There's an open issue documenting this problem on Spring Cloud Netflix and Netflix Eureka.

A temporary fix taken from the issue on GitHub is to override the health reporting implementation so that it returns DOWN instead of OUT_OF_SERVICE while the program is still starting. This blocks it from ever reporting OUT_OF_SERVICE. You can see the fix in the EurekaFix.java file in the store app.

Clone the microservices project from GitHub

Clone the modified JHipster reactive microservice project from GitHub and checkout the start tag.

git clone https://github.com/oktadev/okta-azure-kubernetes-cosmosdb-example.git \
  azure-k8s-cosmosdb
cd azure-k8s-cosmosdb
git fetch --all --tags
git checkout tags/start -b working

Create the Azure Cosmos DB with API for MongoDB

You need to create an Azure Cosmos DB instance. You can either use the Azure Portal or the CLI to create a new Cosmos DB instance. Make sure you create a one that is Azure Cosmos DB API for MongoDB (Cosmos DB supports various database types). If you use the portal, it's pretty self-explanatory but don't forget to enable the free tier and enable a public network.

Here are the instructions for using the CLI.

Log into the Azure CLI using a Bash shell. This will redirect you to a browser to log into the Azure portal.

az login

This should show you the subscriptions for your account.

[
  {
    "cloudName": "AzureCloud",
    "homeTenantId": "21c44b6d-a007-4d48-80cb-c45966ca1af9",
    "id": "90eb9f51-b4be-4a9f-a69f-11b7668a874d",
    "isDefault": true,
    "managedByTenants": [],
    "name": "Azure subscription 1",
    "state": "Enabled",
    "tenantId": "21c44b6d-a007-4d48-80cb-c45966ca1af9",
    "user": {
      "name": "andrewcarterhughes@outlook.com",
      "type": "user"
    }
  }
]

Set the subscription in the shell. Your subscription is probably Azure subscription 1, as that is the default. Make sure you use the subscription that was created when you registered for a free account (or whatever subscription you want if you already have an account).

az account set --subscription <you-subscription-name>

Open a Bash shell. Create a resource group with the following command.

az group create --name australia-east --location australiaeast

Create the Cosmos DB account in the resource group. Substitute your Azure subscription name in the command below (it's probably Azure subscription 1, which is what mine defaulted to).

az cosmosdb create --name jhipster-cosmosdb --resource-group australia-east \
  --kind MongoDB --subscription <you-subscription-name> --enable-free-tier true \
  --enable-public-network true

Once that command returns (it may take a few minutes), it should list a lot of JSON showing properties of the created Cosmos DB account.

If you get an error that says:

(BadRequest) DNS record for cosmosdb under zone Document is already taken.

Then you need to change the --name parameter to something else. Since this is used to generate the public URI for the database it needs to be unique across Azure. Try adding your name or a few random numbers.

I'm using the Australia East location because that was the location that had free tier AKS nodes available when I wrote this tutorial. You can use any resource group you want as long as it allows you to create the AKS cluster later in the tutorial. Even if you can't use the free tier or the free credits, if you stop and start the AKS cluster between working on the tutorial, the cost should be very small (mine was less than a few dollars). The application should still work if the Cosmos DB database is in a different resource group and region since the database URI is configured to be publicly accessible.

List the connection string for the Cosmos DB API for MongoDB endpoint using the following command. If you changed the database name above, you will need to update it in the command below.

az cosmosdb keys list --type connection-strings --name jhipster-cosmosdb \
  --resource-group australia-east

This will list four connection strings. You need to save (copy and paste somewhere) the first, the primary connection string. (Ellipses have been used for brevity below.)

{
  "connectionStrings": [
    {
      "connectionString": "mongodb://jhipster-cosmosdb:XBq5KZ81V8hM63KjCOezi1arq...",
      "description": "Primary MongoDB Connection String"
    },
    ...
  ]
}

Edit the .env file in the docker-compose subdirectory. Add the following variables to it, substituting your connection string for the placeholder. Make sure the connection string is enclosed in quotes. This value is referenced by the docker-compose.yml file and passed to the store service, pointing it to the Cosmos DB MongoDB database.

The ENCRYPT_KEY will be used as the key for encrypting sensitive values stored in the Spring Cloud Config and used by the JHipster registry. You can put whatever value you want in there. A UUID works well, but any string value will work. The longer, the better.

docker-compose/.env

SPRING_DATA_MONGO_URI=<your-connection-string>
ENCRYPT_KEY=<your-encryption-key>

Configure identity with Okta

Before you begin, you’ll need a free Okta developer account. Install the Okta CLI and run okta register to sign up for a new account. If you already have an account, run okta login. Then, run okta apps create jhipster. Select the default app name, or change it as you see fit. Accept the default Redirect URI values provided for you.

What does the Okta CLI do?

The Okta CLI streamlines configuring a JHipster app and does several things for you:

Creates an OIDC app with the correct redirect URIs:
- login: http://localhost:8080/login/oauth2/code/oidc and http://localhost:8761/login/oauth2/code/oidc
- logout: http://localhost:8080 and http://localhost:8761
Creates ROLE_ADMIN and ROLE_USER groups that JHipster expects
Adds your current user to the ROLE_ADMIN and ROLE_USER groups
Creates a groups claim in your default authorization server and adds the user’s groups to it

NOTE: The http://localhost:8761* redirect URIs are for the JHipster Registry, which is often used when creating microservices with JHipster. The Okta CLI adds these by default.

Run cat .okta.env (or type .okta.env on Windows) to see the issuer and credentials for your app.

NOTE: You can also use the Okta Admin Console to create your app. See Create a JHipster App on Okta for more information.

Take note of the name because you will need to find the app in the Okta Admin Console and update the redirect URIs a little later. The okta apps command creates a config file named .okta.env. It will look something like the following. It helpfully lists the values you will need in the next step.

export SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_OIDC_ISSUER_URI="https://dev-13337.okta.com/oauth2/default"
export SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_OIDC_CLIENT_ID="2989u928u383..."
export SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_OIDC_CLIENT_SECRET="09328uu098u4..."

Both the Docker Compose project and the Kubernetes project use Spring Cloud Config to centralize configuration. The JHipster registry service makes these config values available to all of the other services in the cluster.

Open docker-compose/central-server-config/application.yml and add the following to the end, filling in the issuer-uri, client-id, and client-secret taken from the .okta.env file. This is the Spring Cloud Config file for the Docker Compose project.

docker-compose/central-server-config/application.yml

spring:
  security:
    oauth2:
      client:
        provider:
          oidc:
            issuer-uri: https://<your-okta-domain>/oauth2/default
        registration:
          oidc:
            client-id: <client-id>
            client-secret: <client-secret>

Build the Docker images and run the app with Docker Compose

You're all set to run the app locally using Docker and Docker Compose. You need to build the docker image for each of the projects: gateway, store, and blog (you don't have to build the registry because it uses an image).

In the three different app directories, run the following Gradle command.

./gradlew -Pprod bootJar jibDockerBuild

The default Docker resource settings may not be enough to run this project. You may need to bump them. These settings worked for me.

CPUs: 8
Memory: 25 GB
Swap: 2 GB
Disk image size: 120 GB

Navigate to the docker-compose directory and run the app. You can use the -d param to run it as a daemon but for the moment I like seeing the logs. You're just running this in Docker Compose as a warm-up for the Azure deployment anyway.

docker-compose up

Give that a minute or two to finish running all the services.

Open the gateway service at http://localhost:8080.

Go to Account and Sign in. You should be directed to the Okta sign-in form.

You should be able to authenticate with your Okta credentials.

Make sure all parts of the application are working. First, test the store (which is using the Cosmos DB Mongo database) by going to Entities and Product. Make sure you can add a new product and see it in the list of products. Next, create a blog (Entities and Blog).

If that works, you can take a look at the Administration menu. There's a lot of helpful info there.

You can also check the JHipster Registry at http://localhost:8761.

Encrypt the client secret

Leaving secrets in plain text in repositories is a security risk. There are two values in this app that are sensitive: the Cosmos DB connection string that includes the username and password and the Okta OIDC app client secret. You were able to avoid exposing the database credentials by using a .env file. However, the Okta client secret is exposed as plain text in the Spring Cloud Config file (docker-compose/central-server-config/application.yml). This can be encrypted using the JHipster registry.

Open the registry (http://localhost:8761) and click on Configuration and Encryption.

Paste your client secret in the text box. Click Encrypt.

This, incidentally, is why you needed the ENCRYPT_KEY property in the .env file. That's the key that JHipster registry uses to encrypt these values (so keep it secret!).

You can now copy the encrypted value and paste it back into the application.yml file. Make sure you include the {cipher} part. It should look similar to below. Don't forget the quotes!

docker-compose/central-server-config/application.yml

...
spring:
  security:
    oauth2:
      client:
        provider:
          oidc:
            issuer-uri: https://dev-123456.okta.com/oauth2/default
        registration:
          oidc:
            client-id: 0oa6ycm987987uy98
            client-secret: "{cipher}88acb434dd088acb434dd088acb434dd0..."

Stop the app if you have not already using control-c. Restart it.

docker-compose up

Make sure you can still sign into the gateway at http://localhost:8080.

You may be wondering (like I did initially), why can't I just put the client secret in the .env file? This doesn't work because the .env file is processed by Spring Cloud Config and JHipster registry after the container is composed, not by Docker Compose during the container creation, which is when the .env file is processed.

You're done with the Docker Compose implementation. To clean up, you can run the following command. This will stop and remove the containers, networks, volumes, and images created by docker-compose up.

docker-compose down --remove-orphans

Create the Azure Kubernetes cluster

The app works locally. Now it's time to deploy it to an Azure Kubernetes Cluster (AKS). The first step is to create an AKS cluster.

It's super easy to use the CLI to create a cluster. I'll show you the command below. However, there's a wrinkle. The free tier cannot create a cluster in many of the regions because of resource quotas. At least, this was the case when I was working on this tutorial. Nor is there an easy way to quickly see what regions will allow you to create a free-tier cluster. This is why I used Australia East as the region--it allowed me to create a free cluster.

If the command below does not work, I suggest going to the Azure portal and creating a Kubernetes cluster there. Select Create a service and Kubernetes Service. You'll have to select different regions and see what sizes are available (under Node size and Change size) until you find a region that will allow you to create something in the free tier. But hopefully the command will work and you won't have to worry about it.

The size I'm using for this tutorial is Standard B4ms with two nodes. I found that I needed two nodes for the cluster to start properly.

Run the following command to create the AKS cluster.

az aks create --resource-group australia-east --name jhipster-demo \
  --node-count 2 --enable-addons monitoring --generate-ssh-keys --node-vm-size standard_b4ms

This will probably take a few minutes.

As a side note, you can stop the cluster at any point. This will pause billing on the cluster.

az aks stop --resource-group australia-east --name jhipster-demo

And you can start it again.

az aks start --resource-group australia-east --name jhipster-demo

You can stop and start the cluster from the Azure portal as well.

The next step is to get the credentials for the cluster and merge them into .kube/config so that kubectl can use them. Use the following command.

az aks get-credentials --resource-group australia-east --name jhipster-demo

You should see output that ends like the following.

Merged "jhipster-demo" as current context in /home/andrewcarterhughes/.kube/config

You should be able to use kubectl to get the node on Azure.

kubectl get nodes

NAME                                STATUS   ROLES   AGE    VERSION
aks-nodepool1-21657131-vmss000000   Ready    agent   105s   v1.22.6
aks-nodepool1-21657131-vmss000001   Ready    agent   108s   v1.22.6

You can also list a lot of information about the cluster in JSON format using:

az aks list --resource-group australia-east

Configure Kubernetes for Okta and Cosmos DB

The Kubernetes files in the k8s directory were created with the JHipster Kubernetes sub-generator (see the docs for info). To see how the original project was generated, take a look at Matt Raible's JHipster and Kubernetes tutorial. As outlined above, these files were modified to work with Azure Cosmos DB instead of MongoDB in a Kubernetes pod (which is what the sub-generator assumes).

Configure Spring OAuth in the Kubernetes pod by updating k8s/registry-k8s/application-configmap.yml. You can use the same values you used above in the Docker Compose section, in docker-compose/central-server-config/application.yml.

Make sure you use the encrypted client secret enclosed in quotes with the {cipher} prefix. You're going to copy both the encryption key and the encrypted client secret from the Docker Compose configuration to avoid having to re-encrypt the client secret with a new key.

data:
  application.yml: |-
    ...
    spring:
      security:
        oauth2:
          client:
            provider:
              oidc:
                issuer-uri: https://<your-okta-domain>/oauth2/default
            registration:
              oidc:
                client-id: <client-id>
                client-secret: "{cipher}<encrypted-client-secret>"

To configure the JHipster Registry to use OIDC for authentication, you have to modify k8s/registry-k8s/jhipster-registry.yml to enable the oauth2 profile. This has already been done for you in the example app in the project Git repository.

- name: SPRING_PROFILES_ACTIVE
  value: prod,k8s,oauth2

Also in k8s/registry-k8s/jhipster-registry.yml, update the ENCRYPT_KEY value to use the same encryption key you used above in the Docker Compose section in the .env file.

- name: ENCRYPT_KEY
  value: <your-encryption-key>

To configure the store service to use the Cosmo database, you need to put your connection string in k8s/store-k8s/store-deployment.yml.

- name: SPRING_DATA_MONGODB_URI
  value: "<your-connection-string>"

Both the encryption key and the database connection string are sensitive values that need to be encrypted. You'll see how to do that just a little later in this tutorial.

Build Docker images and push to Docker Hub

Previously you built the docker images, but you left them in the local repository. Now you need to upload them to Docker Hub so that Azure AKS can find them. If you haven't already signed up for a Docker Hub account, please do so now.

In each of the three directories (blog, store, and gateway), run the following command. Save your Docker Hub username in a Bash variable as shown below and you can copy and paste the commands and run them in each service directory.

DOCKER_HUB_USERNAME=<docker-hub-username>
# in blog
./gradlew bootJar -Pprod jib -Djib.to.image=$DOCKER_HUB_USERNAME/blog
# in store
./gradlew bootJar -Pprod jib -Djib.to.image=$DOCKER_HUB_USERNAME/store
# in gateway
./gradlew bootJar -Pprod jib -Djib.to.image=$DOCKER_HUB_USERNAME/gateway

To briefly explain what's happening here, take a look at the blog service's Kubernetes descriptor file. It defines a container named blog-app that uses the docker image andrewcarterhughes/blog, which is my Docker Hub username and the blog image.

k8s/blog-k8s/blog-deployment.yml

containers:
  - name: blog-app
    image: andrewcarterhughes/blog

Thus in the k8s directory, each service (store, blog, gateway, and registry) defines a container and a docker image to be run in that container, along with a whole lot of configuration (which is really a lot of what JHipster is bootstrapping for you). The registry does not have a project folder because it uses a stock image that can be pulled directly from the JHipster Docker repository.

To use the images you just created with Kubernetes, do a find and replace in the k8s directory. Replace all instances of andrewcarterhughes with your Docker Hub username (<docker-hub-username>).

One nice feature of Kubernetes is the ability to define init containers. These are containers that run before the main container and can be used to create or wait for necessary resources like databases. I noticed while I was debugging things in this app that a lot of the errors happened in the init containers. It's helpful to know this because if you try and inspect the main container log nothing will be there because the container hasn't even started yet. You have to check the log for the init container that failed. The Kubernetes management tools that I mention below really come in handy for this.

Deploy your microservices to Azure AKS

You can manage a Kubernetes service purely with kubectl. However, there are some pretty helpful tools for monitoring and logging. Both k9s and Kubernetes Lens are great. I recommend installing one or both of these and using them to inspect and monitor your Kubernetes services. They are especially helpful when things go wrong (not that things ever go wrong, I wouldn't know anything about that, I just heard about it from friends, I swear). Kubernetes Lens is a full-on desktop app that describes itself as a Kubernetes IDE. In comparison, k9s is a lighter-weight, text-based tool.

Open a Bash shell and navigate to the k8s subdirectory of the project.

Deploy your microservice architecture to Azure with:

./kubectl-apply.sh -f

If you open this file, you'll see that it creates the namespace and applies the project files. If you do this manually, it's important that the namespace is created first and that the registry is run before the other services.

...
suffix=k8s
kubectl apply -f namespace.yml
kubectl apply -f registry-${suffix}/
kubectl apply -f blog-${suffix}/
kubectl apply -f gateway-${suffix}/
kubectl apply -f store-${suffix}/
...

You can check on your pods with the following command. If you're on the free tier, this may take a few minutes. Using the pay-as-you-go plan, everything was up and running almost immediately for me.

kubectl get pods -n demo

NAME                                  READY   STATUS    RESTARTS   AGE
blog-6896f6dd58-mbjkn                 1/1     Running   0          3m51s
blog-neo4j-0                          1/1     Running   0          3m48s
gateway-7f6d57765f-2fhfb              1/1     Running   0          3m46s
gateway-postgresql-647476b4d5-jdp5c   1/1     Running   0          3m44s
jhipster-registry-0                   1/1     Running   0          3m52s
store-7889695569-k4wkv                1/1     Running   0          3m41s

Here's an example of what this looks like with Kubernetes Lens (the containers were still booting).

Another useful command is describe. I won't replicate the output here, but if you want more detailed information for debugging, you can also run the following.

kubectl describe pods -n demo

To tail logs, you can use the name of the pod.

kubectl logs <pod-name> --tail=-1 -n demo

Although, like I said, k9s and Lens are really the way to go for more detailed inspection.

Here's a screenshot from k9s. You can dig down into the different pods to get more detailed information and inspect logs.

You can use port-forwarding to see the JHipster Registry.

kubectl port-forward svc/jhipster-registry -n demo 8761

Open a browser and navigate to http://localhost:8761. You will be redirected to the Okta login screen, after which you will be taken to the registry.

Make sure everything is green. If you have an error, check the logs for the pod that caused the error. You can restart a specific deployment by deleting it and re-applying it. For example, to restart the store, you can use the commands below from the k8s directory.

kubectl delete -f store-k8s/
kubectl apply -f store-k8s/

Once all is good, control-c to stop forwarding the registry. Expose the gateway and open it.

kubectl port-forward svc/gateway -n demo 8080

Go to http://localhost:8080.

Authenticate with Okta. Make sure you can add blogs, posts, tags, and products. Because the store service uses the same Cosmos DB instance that you were using with Docker Compose locally, any test products you created earlier will still be there.

In preparation for the next step, delete everything you just deployed to AKS in the demo namespace.

kubectl delete all --all -n demo

The first all refers to all resource types. The second --all refers to every object in the resource types (as opposed to specifying an object name or ID). Thus by specifying the namespace you are deleting every object of every resource type in that namespace.

This is one of the benefits of using a namespace. You can do a delete like this. If you do this from the default namespace, you'll risk deleting things you didn't mean to delete or pods added by Kubernetes and Azure for infrastructure administration.

You can also just delete the entire namespace. It will be recreated if you use the Bash script to apply the deployments. This deletes absolutely everything from the namespace but is a little slower. If you do this, you need to make sure that you recreate the namespace later (I'll remind you).

kubectl delete namespace demo

Encrypt the sensitive configuration parameters

There are two really important config values that need to be encrypted: (1) the Cosmos DB connection string (which contains the database credentials) and (2) the OIDC client secret. Because these two values are processed differently, you're going to use two slightly different methods for encrypting them.

There are three different layers of encryption happening here. I found this a little confusing so I'm going to explain it briefy.

JHipster registry encryption for Spring Cloud Config values (values in k8s/registry-k8s/application-configmap.yml)
Kubernetes "encryption" (obfuscation, really) that moves secrets found in Kubernetes deployment files to base64-encoded secrets files
kubeseal which hardens Kubernetes secrets to properly encrypted values

The first above is only for Spring Cloud Config values. The latter two are used to encrypt values in the Kubernetes descriptor files (the other yml files in the k8s directory).

When you use JHipster registry encryption, you have to define an ENCRYPT_KEY value that is used by JHipster to encrypt the secrets. However, because this value is stored in yml files that are going to be committed to a repository, this value must be properly encrypted to ensure the security of the Spring Cloud Config values.

The Cosmos DB connection string (the SPRING_DATA_MONGODB_URI env var) is a Kubernetes deployment value, same as the ENCRYPT_KEY, not a Spring Cloud Config value.

Thus, to harden the OIDC client secret, you must (1) define an ENCRYPT_KEY to enable JHipster registry encryption, (2) use JHipster registry to encrypt the client ID and place the encrypted value in the application-configmap.yml, and (3) use Kubernetes secrets and kubeseal to properly encrypt the ENCRYPT_KEY.

Securing the Cosmos DB connection string is the same as the ENCRYPT_KEY: use Kubernetes secrets and kubeseal to properly encrypt it.

Matt Raible did a great job of explaining secrets management in Kubernetes in his post, Kubernetes to the Cloud with Spring Boot and JHipster. He also linked to a lot of great resources. I'm not going to go into much more detail explaining it here. Check his post out for more info.

The first thing you need to do is install kubeseal into the AKS cluster. You can take a look at the kubeseal GitHub page for more info.

kubectl apply -f https://github.com/bitnami-labs/sealed-secrets/releases/download/v0.17.5/controller.yaml

Retrieve the certificate keypair that this controller generates.

kubectl get secret -n kube-system -l sealedsecrets.bitnami.com/sealed-secrets-key -o yaml

Copy the raw value of tls.crt and decode it. You can use the command line, or learn more about base64 encoding/decoding in our documentation.

echo -n <paste-value-here> | base64 --decode

Put the raw value in a tls.crt file.

Next, install Kubeseal. On macOS, you can use Homebrew. For other platforms, see the release notes.

brew install kubeseal

Encrypt ENCRYPT_KEY and SPRING_DATA_MONGODB_URI (the Cosmos DB connect string). Run the following command to do this, replacing the two values with your encryption key and your connection string.

kubectl create secret generic project-secrets \
  --from-literal=ENCRYPT_KEY='<your-encryption-key>' \
  --from-literal=SPRING_DATA_MONGODB_URI='<your-connection-string>' \
  --dry-run=client -o yaml > secrets.yml

If you deleted the namespace earlier, you need to create it again (it won't hurt to run this if you didn't delete the namespace).

kubectl apply -f namespace.yml

Now, use kubeseal to convert the secrets to encrypted secrets.

kubeseal --cert tls.crt --format=yaml -n demo < secrets.yml > sealed-secrets.yml

Remove the original secrets file and deploy your sealed secrets.

rm secrets.yml
kubectl apply -n demo -f sealed-secrets.yml && kubectl get -n demo sealedsecret project-secrets

You need to update the yml files to refer to the encrypted values. Add the following env variable to the jhister-registry container in k8s/registry-k8s/jhipster-registry.yml (if an ENCRYPT_KEY already exists, replace it).

env:
  ...
  - name: ENCRYPT_KEY
    valueFrom:
      secretKeyRef:
        name: project-secrets
        key: ENCRYPT_KEY

In k8s/store-k8s/store-deployment.yml, change the SPRING_DATA_MONGODB_URI env variable to use the sealed secret.

env:
  ...
  - name: SPRING_DATA_MONGODB_URI
    valueFrom:
      secretKeyRef:
        name: project-secrets
        key: SPRING_DATA_MONGODB_URI

Deploy the cluster.

./kubectl-apply.sh -f

Give the cluster a bit to start. Check it with one of the tools I mentioned or the following:

kubectl get pods -n demo

Once everything is ready, port forward the registry to check the services.

kubectl port-forward svc/jhipster-registry -n demo 8761

Make sure you can log in and that all the services are green. You should either be automatically logged in and redirected back to the home page or directed to log in with the Okta login screen.

This is the happy dance.

Forward the gateway and test the app.

kubectl port-forward svc/gateway -n demo 8080

Log in. Make sure everything works. Kick the tires. Start a blog. Create some products. Influence some people. Restore democracy. Take over the world. Whatever you want.

Once you're done with everything, you can delete the resource group. This will also delete all the resources in the resource group, including the Cosmos database and the AKS cluster. If you have multiple subscriptions, you may need to add a --subscription param.

az group delete --name australia-east

Wait for this to finish. Once it is done, it's probably a good idea to log into the Azure Portal and make sure that the AKS cluster, the Cosmos DB instance, and the resource group have been deleted.

Azure AKS, Kubernetes, and Spring Boot microservices deployed!

Thanks to Julien Dubois for help getting this tutorial finished!

In this project you saw how to deploy a JHipster microservice to Azure AKS. You saw how you can use a managed Cosmos DB instance in place of a MongoDB pod in Kubernetes. You saw how to deploy the app first with Docker Compose and then later with kubectl and the Azure CLI. Finally, you properly encrypted all of the sensitive configuration values using a combination of JHipster registry encryption, Kubernetes secrets, and kubeseal.

As I mentioned at the top, this project is based on two of Matt Raible's tutorials:

Deepu Sasidharan wrote a tutorial, Deploying JHipster Microservices on Azure Kubernetes Service (AKS), that was also a big help.

If you liked this post, there's a good chance you'll like similar ones:

Kubernetes Microservices on Azure with Cosmos DB

Andrew Hughes — Thu, 09 Jun 2022 17:03:32 +0000

The project has a few different pieces:

JHipster Registry: a Eureka server for service discovery and a Spring Cloud Config server for centralized configuration management
Gateway: public Spring Cloud Gateway application using Vue
Store: Spring Boot microservice using Azure's Cosmo DB API for MongoDB
Blog: Spring Boot microservice using a Neo4J database

If you're already familiar with all the tech in this tutorial, you can skip ahead to the prerequisites section. If not, I'm going to explain them a little before we move on.

JHipster microservices architecture overview

The store service and blog service are both examples of the microservice application type. This means that each service is a Spring Boot resources server with some type of SQL or NoSQL backend.

Prerequisites

Docker: you'll need to have both Docker Engine and Docker Compose installed (If you install the Docker desktop, this will automatically install both. On Linux, if you install Docker Engine individually, you will have to also install Docker Compose) separately.
Docker Hub: you'll need a Docker Hub to host the docker images so that Azure can pull them.
Java 11: this tutorial requires Java 11. If you need to manage multiple Java versions, SDKMAN! is a good solution. Check out their docs to install it.
Okta CLI: you'll use Okta to add security to the microservice network. You can register for a free account from the CLI.
Azure Cloud account: they offer a free-tier account with a $200 credit to start.
Azure CLI: you'll use the Azure CLI to manage the Kubernetes cluster.
kubectl: CLI to manage Kubernetes clusters.

Spring Boot microservices for Azure and Cosmos DB

In the docker-compose/docker-compose.yml file:

removed the MongoDB service
updated the store service property SPRING_DATA_MONGODB_URI to point to the Cosmos DB instance via a .env file
removed the Keycloak service and the environment variables that configured auth to use Keycloak from the remaining services (not strictly necessary but cleaned things up)

In the k8s/store-k8s directory:

removed the store-mongodb.yml file (This creates the MongoDB Kubernetes service that our project does not need.)
in store-deployment.yml:
- removed the initContainers (The init container waits for the MongoDB instance, which is removed.)
- updated SPRING_DATA_MONGODB_URI env value of the store-app container to the Cosmos DB URI (This points the store to the Cosmos DB instance.)
- properly secured the Cosmos DB connection string using Kubernetes secrets and kubeseal

Setting the store app's initial status for Eureka

There's an open issue documenting this problem on Spring Cloud Netflix and Netflix Eureka.

Clone the microservices project from GitHub

Clone the modified JHipster reactive microservice project from GitHub and checkout the start tag.

git clone https://github.com/oktadev/okta-azure-kubernetes-cosmosdb-example.git \
  azure-k8s-cosmosdb
cd azure-k8s-cosmosdb
git fetch --all --tags
git checkout tags/start -b working

Create the Azure Cosmos DB with API for MongoDB

Here are the instructions for using the CLI.

Log into the Azure CLI using a Bash shell. This will redirect you to a browser to log into the Azure portal.

az login

This should show you the subscriptions for your account.

[
  {
    "cloudName": "AzureCloud",
    "homeTenantId": "21c44b6d-a007-4d48-80cb-c45966ca1af9",
    "id": "90eb9f51-b4be-4a9f-a69f-11b7668a874d",
    "isDefault": true,
    "managedByTenants": [],
    "name": "Azure subscription 1",
    "state": "Enabled",
    "tenantId": "21c44b6d-a007-4d48-80cb-c45966ca1af9",
    "user": {
      "name": "andrewcarterhughes@outlook.com",
      "type": "user"
    }
  }
]

az account set --subscription <you-subscription-name>

Open a Bash shell. Create a resource group with the following command.

az group create --name australia-east --location australiaeast

Create the Cosmos DB account in the resource group. Substitute your Azure subscription name in the command below (it's probably Azure subscription 1, which is what mine defaulted to).

az cosmosdb create --name jhipster-cosmosdb --resource-group australia-east \
  --kind MongoDB --subscription <you-subscription-name> --enable-free-tier true \
  --enable-public-network true

Once that command returns (it may take a few minutes), it should list a lot of JSON showing properties of the created Cosmos DB account.

If you get an error that says:

(BadRequest) DNS record for cosmosdb under zone Document is already taken.

List the connection string for the Cosmos DB API for MongoDB endpoint using the following command. If you changed the database name above, you will need to update it in the command below.

az cosmosdb keys list --type connection-strings --name jhipster-cosmosdb \
  --resource-group australia-east

This will list four connection strings. You need to save (copy and paste somewhere) the first, the primary connection string. (Ellipses have been used for brevity below.)

{
  "connectionStrings": [
    {
      "connectionString": "mongodb://jhipster-cosmosdb:XBq5KZ81V8hM63KjCOezi1arq...",
      "description": "Primary MongoDB Connection String"
    },
    ...
  ]
}

docker-compose/.env

SPRING_DATA_MONGO_URI=<your-connection-string>
ENCRYPT_KEY=<your-encryption-key>

Configure identity with Okta

Before you begin, you’ll need a free Okta developer account. Install the Okta CLI and run okta register to sign up for a new account. If you already have an account, run okta login. Then, run okta apps create jhipster. Select the default app name, or change it as you see fit. Accept the default Redirect URI values provided for you.

What does the Okta CLI do?

The Okta CLI streamlines configuring a JHipster app and does several things for you:

Creates an OIDC app with the correct redirect URIs:
- login: http://localhost:8080/login/oauth2/code/oidc and http://localhost:8761/login/oauth2/code/oidc
- logout: http://localhost:8080 and http://localhost:8761
Creates ROLE_ADMIN and ROLE_USER groups that JHipster expects
Adds your current user to the ROLE_ADMIN and ROLE_USER groups
Creates a groups claim in your default authorization server and adds the user’s groups to it

NOTE: The http://localhost:8761* redirect URIs are for the JHipster Registry, which is often used when creating microservices with JHipster. The Okta CLI adds these by default.

Run cat .okta.env (or type .okta.env on Windows) to see the issuer and credentials for your app.

NOTE: You can also use the Okta Admin Console to create your app. See Create a JHipster App on Okta for more information.

export SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_OIDC_ISSUER_URI="https://dev-13337.okta.com/oauth2/default"
export SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_OIDC_CLIENT_ID="2989u928u383..."
export SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_OIDC_CLIENT_SECRET="09328uu098u4..."

docker-compose/central-server-config/application.yml

spring:
  security:
    oauth2:
      client:
        provider:
          oidc:
            issuer-uri: https://<your-okta-domain>/oauth2/default
        registration:
          oidc:
            client-id: <client-id>
            client-secret: <client-secret>

Build the Docker images and run the app with Docker Compose

In the three different app directories, run the following Gradle command.

./gradlew -Pprod bootJar jibDockerBuild

The default Docker resource settings may not be enough to run this project. You may need to bump them. These settings worked for me.

CPUs: 8
Memory: 25 GB
Swap: 2 GB
Disk image size: 120 GB

docker-compose up

Give that a minute or two to finish running all the services.

Open the gateway service at http://localhost:8080.

Go to Account and Sign in. You should be directed to the Okta sign-in form.

You should be able to authenticate with your Okta credentials.

If that works, you can take a look at the Administration menu. There's a lot of helpful info there.

You can also check the JHipster Registry at http://localhost:8761.

Encrypt the client secret

Open the registry (http://localhost:8761) and click on Configuration and Encryption.

Paste your client secret in the text box. Click Encrypt.

This, incidentally, is why you needed the ENCRYPT_KEY property in the .env file. That's the key that JHipster registry uses to encrypt these values (so keep it secret!).

You can now copy the encrypted value and paste it back into the application.yml file. Make sure you include the {cipher} part. It should look similar to below. Don't forget the quotes!

docker-compose/central-server-config/application.yml

...
spring:
  security:
    oauth2:
      client:
        provider:
          oidc:
            issuer-uri: https://dev-123456.okta.com/oauth2/default
        registration:
          oidc:
            client-id: 0oa6ycm987987uy98
            client-secret: "{cipher}88acb434dd088acb434dd088acb434dd0..."

Stop the app if you have not already using control-c. Restart it.

docker-compose up

Make sure you can still sign into the gateway at http://localhost:8080.

docker-compose down --remove-orphans

Create the Azure Kubernetes cluster

The app works locally. Now it's time to deploy it to an Azure Kubernetes Cluster (AKS). The first step is to create an AKS cluster.

The size I'm using for this tutorial is Standard B4ms with two nodes. I found that I needed two nodes for the cluster to start properly.

Run the following command to create the AKS cluster.

az aks create --resource-group australia-east --name jhipster-demo \
  --node-count 2 --enable-addons monitoring --generate-ssh-keys --node-vm-size standard_b4ms

This will probably take a few minutes.

As a side note, you can stop the cluster at any point. This will pause billing on the cluster.

az aks stop --resource-group australia-east --name jhipster-demo

And you can start it again.

az aks start --resource-group australia-east --name jhipster-demo

You can stop and start the cluster from the Azure portal as well.

The next step is to get the credentials for the cluster and merge them into .kube/config so that kubectl can use them. Use the following command.

az aks get-credentials --resource-group australia-east --name jhipster-demo

You should see output that ends like the following.

Merged "jhipster-demo" as current context in /home/andrewcarterhughes/.kube/config

You should be able to use kubectl to get the node on Azure.

kubectl get nodes

NAME                                STATUS   ROLES   AGE    VERSION
aks-nodepool1-21657131-vmss000000   Ready    agent   105s   v1.22.6
aks-nodepool1-21657131-vmss000001   Ready    agent   108s   v1.22.6

You can also list a lot of information about the cluster in JSON format using:

az aks list --resource-group australia-east

Configure Kubernetes for Okta and Cosmos DB

data:
  application.yml: |-
    ...
    spring:
      security:
        oauth2:
          client:
            provider:
              oidc:
                issuer-uri: https://<your-okta-domain>/oauth2/default
            registration:
              oidc:
                client-id: <client-id>
                client-secret: "{cipher}<encrypted-client-secret>"

- name: SPRING_PROFILES_ACTIVE
  value: prod,k8s,oauth2

Also in k8s/registry-k8s/jhipster-registry.yml, update the ENCRYPT_KEY value to use the same encryption key you used above in the Docker Compose section in the .env file.

- name: ENCRYPT_KEY
  value: <your-encryption-key>

To configure the store service to use the Cosmo database, you need to put your connection string in k8s/store-k8s/store-deployment.yml.

- name: SPRING_DATA_MONGODB_URI
  value: "<your-connection-string>"

Both the encryption key and the database connection string are sensitive values that need to be encrypted. You'll see how to do that just a little later in this tutorial.

Build Docker images and push to Docker Hub

DOCKER_HUB_USERNAME=<docker-hub-username>
# in blog
./gradlew bootJar -Pprod jib -Djib.to.image=$DOCKER_HUB_USERNAME/blog
# in store
./gradlew bootJar -Pprod jib -Djib.to.image=$DOCKER_HUB_USERNAME/store
# in gateway
./gradlew bootJar -Pprod jib -Djib.to.image=$DOCKER_HUB_USERNAME/gateway

k8s/blog-k8s/blog-deployment.yml

containers:
  - name: blog-app
    image: andrewcarterhughes/blog

Deploy your microservices to Azure AKS

Open a Bash shell and navigate to the k8s subdirectory of the project.

Deploy your microservice architecture to Azure with:

./kubectl-apply.sh -f

...
suffix=k8s
kubectl apply -f namespace.yml
kubectl apply -f registry-${suffix}/
kubectl apply -f blog-${suffix}/
kubectl apply -f gateway-${suffix}/
kubectl apply -f store-${suffix}/
...

You can check on your pods with the following command. If you're on the free tier, this may take a few minutes. Using the pay-as-you-go plan, everything was up and running almost immediately for me.

kubectl get pods -n demo

NAME                                  READY   STATUS    RESTARTS   AGE
blog-6896f6dd58-mbjkn                 1/1     Running   0          3m51s
blog-neo4j-0                          1/1     Running   0          3m48s
gateway-7f6d57765f-2fhfb              1/1     Running   0          3m46s
gateway-postgresql-647476b4d5-jdp5c   1/1     Running   0          3m44s
jhipster-registry-0                   1/1     Running   0          3m52s
store-7889695569-k4wkv                1/1     Running   0          3m41s

Here's an example of what this looks like with Kubernetes Lens (the containers were still booting).

Another useful command is describe. I won't replicate the output here, but if you want more detailed information for debugging, you can also run the following.

kubectl describe pods -n demo

To tail logs, you can use the name of the pod.

kubectl logs <pod-name> --tail=-1 -n demo

Although, like I said, k9s and Lens are really the way to go for more detailed inspection.

Here's a screenshot from k9s. You can dig down into the different pods to get more detailed information and inspect logs.

You can use port-forwarding to see the JHipster Registry.

kubectl port-forward svc/jhipster-registry -n demo 8761

Open a browser and navigate to http://localhost:8761. You will be redirected to the Okta login screen, after which you will be taken to the registry.

kubectl delete -f store-k8s/
kubectl apply -f store-k8s/

Once all is good, control-c to stop forwarding the registry. Expose the gateway and open it.

kubectl port-forward svc/gateway -n demo 8080

Go to http://localhost:8080.

In preparation for the next step, delete everything you just deployed to AKS in the demo namespace.

kubectl delete all --all -n demo

kubectl delete namespace demo

Encrypt the sensitive configuration parameters

There are three different layers of encryption happening here. I found this a little confusing so I'm going to explain it briefy.

JHipster registry encryption for Spring Cloud Config values (values in k8s/registry-k8s/application-configmap.yml)
Kubernetes "encryption" (obfuscation, really) that moves secrets found in Kubernetes deployment files to base64-encoded secrets files
kubeseal which hardens Kubernetes secrets to properly encrypted values

The first above is only for Spring Cloud Config values. The latter two are used to encrypt values in the Kubernetes descriptor files (the other yml files in the k8s directory).

The Cosmos DB connection string (the SPRING_DATA_MONGODB_URI env var) is a Kubernetes deployment value, same as the ENCRYPT_KEY, not a Spring Cloud Config value.

Securing the Cosmos DB connection string is the same as the ENCRYPT_KEY: use Kubernetes secrets and kubeseal to properly encrypt it.

The first thing you need to do is install kubeseal into the AKS cluster. You can take a look at the kubeseal GitHub page for more info.

kubectl apply -f https://github.com/bitnami-labs/sealed-secrets/releases/download/v0.17.5/controller.yaml

Retrieve the certificate keypair that this controller generates.

kubectl get secret -n kube-system -l sealedsecrets.bitnami.com/sealed-secrets-key -o yaml

Copy the raw value of tls.crt and decode it. You can use the command line, or learn more about base64 encoding/decoding in our documentation.

echo -n <paste-value-here> | base64 --decode

Put the raw value in a tls.crt file.

Next, install Kubeseal. On macOS, you can use Homebrew. For other platforms, see the release notes.

brew install kubeseal

kubectl create secret generic project-secrets \
  --from-literal=ENCRYPT_KEY='<your-encryption-key>' \
  --from-literal=SPRING_DATA_MONGODB_URI='<your-connection-string>' \
  --dry-run=client -o yaml > secrets.yml

If you deleted the namespace earlier, you need to create it again (it won't hurt to run this if you didn't delete the namespace).

kubectl apply -f namespace.yml

Now, use kubeseal to convert the secrets to encrypted secrets.

kubeseal --cert tls.crt --format=yaml -n demo < secrets.yml > sealed-secrets.yml

Remove the original secrets file and deploy your sealed secrets.

rm secrets.yml
kubectl apply -n demo -f sealed-secrets.yml && kubectl get -n demo sealedsecret project-secrets

env:
  ...
  - name: ENCRYPT_KEY
    valueFrom:
      secretKeyRef:
        name: project-secrets
        key: ENCRYPT_KEY

In k8s/store-k8s/store-deployment.yml, change the SPRING_DATA_MONGODB_URI env variable to use the sealed secret.

env:
  ...
  - name: SPRING_DATA_MONGODB_URI
    valueFrom:
      secretKeyRef:
        name: project-secrets
        key: SPRING_DATA_MONGODB_URI

Deploy the cluster.

./kubectl-apply.sh -f

Give the cluster a bit to start. Check it with one of the tools I mentioned or the following:

kubectl get pods -n demo

Once everything is ready, port forward the registry to check the services.

kubectl port-forward svc/jhipster-registry -n demo 8761

Make sure you can log in and that all the services are green. You should either be automatically logged in and redirected back to the home page or directed to log in with the Okta login screen.

This is the happy dance.

Forward the gateway and test the app.

kubectl port-forward svc/gateway -n demo 8080

Log in. Make sure everything works. Kick the tires. Start a blog. Create some products. Influence some people. Restore democracy. Take over the world. Whatever you want.

az group delete --name australia-east

Wait for this to finish. Once it is done, it's probably a good idea to log into the Azure Portal and make sure that the AKS cluster, the Cosmos DB instance, and the resource group have been deleted.

Azure AKS, Kubernetes, and Spring Boot microservices deployed!

Thanks to Julien Dubois for help getting this tutorial finished!

As I mentioned at the top, this project is based on two of Matt Raible's tutorials:

Deepu Sasidharan wrote a tutorial, Deploying JHipster Microservices on Azure Kubernetes Service (AKS), that was also a big help.

If you liked this post, there's a good chance you'll like similar ones: