Securing Nuxt Apps with Keycloak

Nuxt is an open source web framework that makes developing web applications easier.

In this article we'll be using Keycloak to secure a Nuxt Web application. We will use two different methods: keycloak-js and oidc-client-ts.

Phase Two is a Keycloak as a Service provider enabling SaaS builders to accelerate time-to-market with powerful enterprise features like SSO, identity, and user management features. Phase Two enhances Keycloak through a variety of open-source extentions for modern SaaS use cases. Phase Two supports both hosted and on-premise deployment options.

What is Keycloak?

Keycloak has been a leader in the Identity and Access Management world since its launch almost 8 years ago. It is an open-source offering under the stewardship of Red Hat

INFO
If you just want to skip to the code, visit the Phase Two Nuxt example. We are also building Keycloak examples for other frameworks.

TOC

• Keycloak Setup
• Nuxt + Keycloak-Js
• Nuxt + OIDC Client

Setting up a Keycloak Instance

TIP
If you already have a functioning Keycloak instance, you can skip to the next section.

Setting up an OIDC Client

We need to create a OpenID Connect Client in Keycloak for the app to communicate with.

OIDC Config

Adding a Non-Admin User

INFO
It is bad practice to use your Admin user to sign in to an Application.

Since we do not want to use our Admin user for signing into the app we will build, we need to add another non-admin user.

Setting up a Nuxt Project

INFO
We will use the Phase Two Nuxt example code here, but the logic could easily be applied to any existing application.

This example uses Nuxt3. There are a couple methods by which you can integrate Keycloak to your Nuxt application. We're going to explore two methods here, one uses keycloak-js and the other leverages oidc-client-ts. The keycloak-js library provides a simple, client-only method, but lacks some of the sophistication provided by the oidc-client library that is heavily supported and more widely used.

Using keycloak-js

INFO
For this example, we need to disable "Client Authentication" in the OIDC client that was setup earlier. This is available under Client > Settings > Capability config > Client authentication to OFF.

1. Clone the Phase Two example repo.
2. Open the Nuxt folder within /frameworks/nuxt and open the keycloak-js folder within /frameworks/nuxt/keycloak-js.
3. Run npm install and then npm run dev. keycloak-js is a Javascript library that provides a fast way to secure an application.
4. The project makes use of the following Nuxt items: components, composables, layouts, and plugins. We'll review each in kind.
5. The main component that shows the User's authenticated state is in /components/User. In this component we call the useKeycloak composable, which let's us key into the keycloak-js functions that we've wrapped to make easily availble.

   const { keycloak, authState } = useKeycloak();

   function login() {
     keycloak.login();
   }

   function logout() {
     keycloak.logout();
   }

Lower in the file the component leverages v-if checks to determine if the authState is authenticated or not. Depending on the state, a Log in or Log out button is available.

1. Let's take a look at the setup for the composable next. Our composable is in /composables/keycloak-c. A composable is a function defined that can be called anywhere in the Nuxt application. It's a good way to abstract logic to be reused. In our case we use it to wrap a keycloak-js plugin (more on that in the next step) and help provided a state value for the authenticated state.

   export const useKeycloak = () => {
     const nuxtApp = useNuxtApp();
     const keycloak = nuxtApp.$keycloak as Keycloak;
     const authState = useState("authState", () => "unAuthenticated");

     keycloak.onAuthSuccess = () => (authState.value = "authenticated");
     keycloak.onAuthError = () => (authState.value = "error");

     return {
       keycloak,
       authState,
     };
   };

1. In the plugin, /plugins/keycloak.client.ts we instantiate the keycloak-js library. We can then attach that instance to the NuxtApp instance. Substitute the correct values for your Keycloak instance that we created earlier in the tutorial.

   export default defineNuxtPlugin((nuxtApp) => {
     const initOptions: KeycloakConfig = {
       url: "https://euc1.auth.ac/auth/",
       realm: "shared-deployment-001",
       clientId: "reg-example-1",
     };

     const keycloak = new Keycloak(initOptions);

     nuxtApp.$keycloak = keycloak;

     keycloak.init({
       onLoad: "check-sso",
     });
   });

1. The logic for checking the authenticated state can be used to expand in ways to secure your site in a number of ways.

Using oidc-client

The oidc-client-ts package is a well-maintained and used library. It provides a lot of utilities for building out a fully production app.

1. Clone the Phase Two example repo.
2. Open the Nuxt folder within /frameworks/nuxt and open the /nuxt/oidc-client-ts folder.
3. Run npm install and then npm run dev.
4. The structure of the project is similar to the keycloak-js version but with a the use of services, stores, and middleware.
5. We'll review where we configure out Keycloak instance. First open /services/keycloak-config.ts. In this file you will want to update it with the values for the Keycloak instance we set-up earlier in the tutorial. Make sure you are using the one with Client Authentication enabled. Update the clientSecret with the value. Use and environment variable here if you wish.

   export const keycloakConfig = {
     authorityUrl: "https://euc1.auth.ac",
     applicationUrl: "http://localhost:3000",
     realm: "shared-deployment-001",
     clientId: "reg-example-1",
     clientSecret: "CLIENT_SECRET",
   };

1. Switch over to the /services/auth-service now to see how the Oidc instance is started. The class pulls in values from the keycloakConfig to use in the constructor. The other functions are wrappers around methods provided by the oidc-client library. This allows us to key into things like signInRedirect and signoutRedirect.

How the settings are integrated:

   const settings = {
     authority: `${keycloakConfig.authorityUrl}/auth/realms/${keycloakConfig.realm}`,
     client_id: keycloakConfig.clientId,
     client_secret: keycloakConfig.clientSecret,
     redirect_uri: `${window.location.origin}/auth`,
     silent_redirect_uri: `${window.location.origin}/silent-refresh`,
     post_logout_redirect_uri: `${window.location.origin}`,
     response_type: "code",
     userStore: new WebStorageStateStore(),
     loadUserInfo: true,
   };
   this.userManager = new UserManager(settings);

Example function wrapper:

   public signInRedirect() {
     return this.userManager.signinRedirect();
   }

1. With the AuthService defined, we can now expose that through a composable. Switch to the /composables/useServices file. The file is simple but provides a way for any component to hook into the service instance.

   import AuthService from "@/services/auth-service";
   import ApplicationService from "@/services/application-service";
   import { useAuth } from "@/stores/auth";

   export const useServices = () => {
     const authStore = useAuth();

     return {
       $auth: new AuthService(),
       $application: new ApplicationService(authStore.access_token),
     };
   };

We pull in the AuthService then expose it through the $auth variable. The $application variable exposes the ApplicationService which is provided as an example of how you could secure API calls.

1. We leverage the pinia library to make store User information to make it easily accessible. Open /stores/auth/index. From within this file, we can wrap the User object exposed by the oidc-client package. This can then be leveraged in the middleware function we want to define or to pull information quickly about the user.
2. There are a few main pages in play here that we define to create paths the library can leverage. The /pages/auth, /pages/logout, /pages/silent-refresh create paths at the same name. These are used to do the redirection during authentication or log out. From within these we use the AuthService to direct the user around within the app. For instance in /auth:

   const authenticateOidc = async () => {
     try {
       await services.$auth.signInCallback();
       router.push("/");
     } catch (error) {
       console.error(error);
     }
   };

   await authenticateOidc();

The router.push naively sends someone to the home page. This could be updated to go to any number of places, including the page one started the login flow from if you were to store that information to be retrieved.

1. We have also created a middleware file in /middleware/auth.global to be used in a couple of ways. It checks if the user is authenticated and based on that knowledge, stores the user information in the store (if not there) or could be used to send someone to login. For our example, we created buttons to initiate that but there is a comment which shows how you could force a set of paths to require login.

   const authFlowRoutes = ["/auth", "/silent-refresh", "/logout"];

   export default defineNuxtRouteMiddleware(async (to, from) => {
     const authStore = useAuth();
     const services = useServices();
     const user = (await services.$auth.getUser()) as User;

     if (!user && !authFlowRoutes.includes(to.path)) {
       // use this to automatically force a sign in and redirect
       // services.$auth.signInRedirect();
     } else {
       authStore.setUpUserCredentials(user);
     }
   });

1. Now that we have all the things setup, we can define the user component /components/User to easily pull information about the user's state and display the appropriate UI.

   const authStore = useAuth();
   const user = authStore.user;

   const signIn = () => services.$auth.signInRedirect();
   const signOut = () => services.$auth.logout();

With this, the user object is now easily available. A simple v-if="user" allows the app to determine what UI to show.

1. A bit more complicated of a setup, but more elegant in the handling of the logged in flow. The oidc-client allows for much better fine-tuning of the experience.

Learning more

Phase Two's enhanced Keycloak provides many ways to quickly control and tweak the log in and user management experience. Our blog has many use cases from customizing login pages, setting up magic links (password-less sign in), and Organization workflows.