DEV Community: Anu Shibin Joseph Raj

KeyCloak OAuth2 + React JS Integration

Anu Shibin Joseph Raj — Tue, 29 Apr 2025 09:07:54 +0000

Today, we will see how I integrated KeyCloak’s OAuth2 authentication with my React JS application.

For those who don’t know (like me before doing this exercise), KeyCloak is a server that provides OAuth2 authentication very easily. We don’t need to worry about the hassles of setting up authentication manually. We simply use their APIs in the frontend to easily authenticate to our application.

In this article, we will do the following:

Create a KeyCloak server
Create a Client configuration in the KeyCloak server
Scaffold a Vite JS Project to write a React JS application
Use the keycloak-js frontend library to authenticate to the Keycloak server

Please note that I am not going to set up a “production” grade system here. This will be a very simple setup that helps us understand how to easily connect the client and server and get going.

You may download the source code of this app from my GitHub repo: https://github.com/anushibin007/keycloak-vite-demo

Step 1: Create a KeyCloak server

To create a KeyCloak server, let’s use their official Docker image.

Let’s write a docker compose file to make things easier to maintain. We need a keycloak application server and a db to persist the state. To do that, put the following items into a docker-compose.yml file:

# docker-compose.yml
services:
    keycloak-mysql:
        container_name: keycloak-mysql
        image: mysql:8
        volumes:
            - keycloak-db-vol:/var/lib/mysql
        environment:
            MYSQL_ROOT_PASSWORD: root
            MYSQL_DATABASE: keycloak
            MYSQL_USER: keycloak
            MYSQL_PASSWORD: password
    keycloak-server:
        container_name: keycloak
        image: quay.io/keycloak/keycloak:24.0.1
        command: ["start-dev", "--import-realm"]
        environment:
            DB_VENDOR: MYSQL
            DB_ADDR: mysql
            DB_DATABASE: keycloak
            DB_USER: keycloak
            DB_PASSWORD: password
            KEYCLOAK_ADMIN: admin
            KEYCLOAK_ADMIN_PASSWORD: admin
        ports:
            - "8181:8080"
        volumes:
            - keycloak-server-vol:/opt/keycloak/data/import/
        depends_on:
            - keycloak-mysql

volumes:
    keycloak-db-vol:
    keycloak-server-vol:

Start the compose by running docker compose up -d
You should now be able to access the keycloak server at http://localhost:8181/ with the credentials mentioned above (username and password are both admin)

Step 2: Create a Client in the KeyCloak server

I hope you are logged in to the KeyCloak admin portal (at http://localhost:8181/admin/master/console/)
Now, go to the “Clients” section on the left pane
Click on “Create client”
In the “General settings” step, the client type should be “OpenID Connect”
Give the the Client ID as “vite-frontend”
Click Next
Now you are in the “Capability config” step
Enable only the “Standard flow” option. Disable everything else. This is very important.
Click Next
Now you are in the “Login settings” step
Fill the “Valid redirect URIs” as http://localhost:*
Fill the “Web origins” as *
Click “Save”

Let’s allow user registration from the frontend. For that,

In the KeyCloak admin portal, go to “Realm settings” from the left pane
Then go to the “Login” tab
Then enable the following items:
User registration
Forgot password
Remember me
Email as username
The KeyCloak server is now completely set up. Let’s move on to the frontend.

Step 3: Create a React JS application

Let’s create a React JS application using the Vite JS scaffold.

Run the following command:

npm create vite@latest keycloak-react-client -- --template react

The above command will scaffold a new Vite JS project. Let us now switch to that directory and install the required dependencies and start the dev server

# switch to the client application folder
cd keycloak-react-client

# install the default dependencies
npm install

# install all the other libraries
# required to run the keycloak integration
npm install --save keycloak-js @react-keycloak/web react-router-dom

# start the dev server
npm run dev

Now the frontend application should be running although it will just be showing a dummy application at http://localhost:5173

Step 4: Use the keycloak-js frontend library to authenticate to the Keycloak server

The base is now laid. Let us now add business code to the frontend.

Let us start with a simple login button

// src/Login.jsx
import { useKeycloak } from "@react-keycloak/web";

export default function Login() {
    const { keycloak } = useKeycloak();

    return (
        <div className="login">
            <button onClick={() => keycloak.login()}>Login</button>
        </div>
    );
}

Now we will create a “secure” page that only logged in users can visit

// src/SecurePage.jsx
import { useKeycloak } from "@react-keycloak/web";

export default function SecurePage() {
    const { keycloak } = useKeycloak();
    return (
        <div className="secure-page">
            <p>Welcome, {keycloak.tokenParsed.email}</p>
            <p>Your access token (keep it safe!): {keycloak.token}</p>
        </div>
    );
}

Let us now create a “SecurityGuy” component that will act as a a guard to either let us in or not

// src/SecurityGuy.jsx
import { useKeycloak } from "@react-keycloak/web";
import Login from "./Login";

export default function SecurityGuy({ children }) {
    const { keycloak } = useKeycloak();

    const isLoggedIn = keycloak.authenticated;

    return isLoggedIn ? children : <Login />;
}

What we are essentially doing here is, if we are logged in, we show the children components (check the next point to understand this concept) or else, we just show the Login page with the login button.

Let us now add routes and config to our App.jsx file:

// src/App.jsx
import React from "react";
import { ReactKeycloakProvider } from "@react-keycloak/web";
import { BrowserRouter, Route, Routes } from "react-router-dom";
import "./App.css";
import SecurityGuy from "./SecurityGuy";
import SecurePage from "./SecurePage";
import Keycloak from "keycloak-js";

const keycloak = new Keycloak({
    url: "http://localhost:8181",
    realm: "master",
    clientId: "vite-frontend",
});

function App() {
    return (
        <ReactKeycloakProvider authClient={keycloak}>
            <BrowserRouter>
                <Routes>
                    <Route
                        path="/"
                        element={
                            <SecurityGuy>
                                <SecurePage />
                            </SecurityGuy>
                        }
                    />
                </Routes>
            </BrowserRouter>
        </ReactKeycloakProvider>
    );
}

export default App;

Note that the highlighted section might vary for you if you are changing ports, etc. If you are strictly following this tutorial, then you can simply copy paste that code as it is.

Also, if you see in the above code, the SecurityGuy is kinda “guarding” the secure page. That is, only if we are logged in, we see the items inside the secure page. Else, we see the Login button.

Finally, remove the “Strict mode” in main.jsx so that you don’t get any multiple-initialization errors. The exact error message is: “A ‘Keycloak’ instance can only be initialized once.“

I couldn’t figure out the “proper” way to fix this issue. If you know, please let me know. For now, let’s do this “hack”. I have removed the tags from the main.jsx file to disable “Strict mode”.

// src/main.jsx
import { createRoot } from "react-dom/client";
import "./index.css";
import App from "./App.jsx";

createRoot(document.getElementById("root")).render(<App />);

Test the authentication

Access your frontend application at http://localhost:5173/
You should see just the Login button because you are not logged in
Click on the “Login” button
This should take you to the KeyCloak login page
Since we do not have any application users, let’s create one by clicking on the “Register” button
Fill the mandatory fields with some dummy data and click on the “Register” button
You should be logged in now and see an authentication token that was returned from the KeyCloak server

Homework

Try to implement a simple logout button to logout the user after you are logged in 🙂

Conclusion

We have completed a simple implementation of an OAuth2 authentication using a KeyCloak server and a Vite JS frontend application. Read more about KeyCloak in its official documentation:

https://www.keycloak.org/securing-apps/javascript-adapter

Follow me for more technical articles

Solve IntelliJ Maven Build Cache Issue

Anu Shibin Joseph Raj — Fri, 04 Apr 2025 10:03:39 +0000

The problem

When I was developing a Spring Boot project in IntelliJ, I encountered this strange issue where IntelliJ had cached the generated resources of my Maven POM.xml file. And there were some issues with the POM file. I figured out a fix to the issue and implemented it. But after that, when I try to run the build from IntelliJ, it kept failing with the same error over and over. If I try to run the maven project from command line, it works. But it didn’t work from IntelliJ.

Every stack overflow post and even ChatGPT said to simply do the “Invalidate Caches/Restart” option from the main menu. But for some reason, that didn’t clear the cache. I tested this with two projects to make sure that I was not doing anything wrong. And I was able to reproduce the issue in both projects.

The fix

Ultimately, the fix was to delete the .idea and target folders from the workspace and restart the workspace. But note that this will clear all your IntelliJ customizations for the workspace – a small price to pay to get your code to work.

I am still not sure if this is a known issue from IntelliJ. Regardless, this was a new learning that I wanted to share. Thanks for reading ✨

Solve 404 when using BrowserRouter with GitHub pages

Anu Shibin Joseph Raj — Wed, 26 Mar 2025 16:07:50 +0000

Context

When you use the BrowserRouter component from the react-router-dom library, you will be able to set up routes in your React JS application that can be visited from the frontend.

It works on your local development environment. But it stops working after deploying it to GitHub pages! You will see a 404 error whenever you try to visit any of the routes.

One of the "fix" that I used to do was to use a HashRouter to solve this issue. This is because the original path remains the same. We just use anchors or "hashes" to switch between page content.

Why

Let's first look at why BrowserRouter is not friendly with GitHub Pages. GitHub Pages has this thing where when we access an URL other than the root URL, it looks for a physical folder there.

So, when we visit /country/india for example, it will look for /country/india/index.html. This way of looking for files is not always feasible for us in production. Perhaps SSG would help fix this issue but even there we are limited because we need to know in advance about all the countries in the world so that we can generate html files for them.

Fix

So, how do we fix it now?

There is this feature in GitHub Pages where if we put a file called "404.html", at the root of your static file deployment, it will use that as the 404 page instead of the one that GitHub shows by default. This is simply an out of the box GitHub feature that is provided to the user to show their own custom 404 page.

We are going to take advantage of this custom 404 page 😈

We are going to simply clone our index.html file when we run the GitHub pipeline for Pages. We will rename the cloned file to 404.html. After this, all the 404 requests will go to index.html and it will serve the required content as expected.

Sample code

Here is a sample GitHub Actions YML file to get this done with a project scaffolded using Vite JS. I have added a comment in the line that does our fix.

name: gh-pages build

on:
    push:
        branches: [master]

jobs:
    build:
        permissions:
            pages: write
            id-token: write
        environment:
            name: github-pages
            url: ${{ steps.deployment.outputs.page_url }}
        runs-on: ubuntu-latest
        steps:
            - name: Checkout ⏬
              uses: actions/checkout@v2

            - name: Install 🔧
              run: npm install

            - name: Build 🔥
              run: CI='' npm run build && cp ./dist/index.html ./dist/404.html # THE FIX

            - name: Setup Pages ⚙
              uses: actions/configure-pages@v3

            - name: Upload artifact 🔼
              uses: actions/upload-pages-artifact@v3
              with:
                  path: "./dist"

            - name: Deploy to GitHub Pages 🚀
              id: deployment
              uses: actions/deploy-pages@v4

Follow me for more tips on React JS, Java, & Docker