This lab demonstrates a simple browser-login flow using a ready-to-run Helidon SE application with Keycloak and OpenID Connect (OIDC).

The application has a public page and a protected private page. When a user opens the private page without a session, Helidon redirects the browser to Keycloak. After successful login, Keycloak returns the browser to Helidon and the private page displays the authenticated user.

GitHub repository:
https://github.com/puneethbuilds-helidon/helidon-keycloak-oidc-login

What the Lab Demonstrates

Browser → Helidon SE /private → Keycloak login → Helidon OIDC callback → Private page

A browser requests /private. Helidon requires authentication for that route and redirects the browser to Keycloak. Keycloak authenticates the user and sends an authorization code to Helidon’s callback endpoint. Helidon validates the OIDC response, creates the authenticated security context, and redirects the user back to the private page.

What to Create in Keycloak

Before running the application, create the following resources in Keycloak.

Realm: master
OIDC Client: helidon-web
Client type: OpenID Connect
Client authentication: On
Standard flow: Selected
Valid redirect URI: http://localhost:8081/oidc/redirect
Web origin: http://localhost:8081
Test user: for example, labuser

Copy the client secret from Clients → helidon-web → Credentials. The client and test user must be in the same realm. For this short demo, the master realm keeps the setup simple; use a dedicated realm for a real application.

Download the Application

Open the GitHub repository:
https://github.com/puneethbuilds-helidon/helidon-keycloak-oidc-login

Download the standalone JAR from the latest release:
https://github.com/puneethbuilds-helidon/helidon-keycloak-oidc-login/releases/latest

Download:
helidon-keycloak-lab.jar

The release JAR already contains the application and its Helidon runtime dependencies. Maven and source compilation are not required for this demo.

Set Your Keycloak Connection Details

Set the Keycloak connection details in the same terminal that will run the JAR. Replace the sample secret with the secret copied from Keycloak:

export APP_OIDC_REALM=’master’
export APP_OIDC_ISSUER=’http://localhost:8080/realms/master'
export APP_OIDC_CLIENTID=’helidon-web’
export APP_OIDC_SECRET=’replace-with-the-keycloak-client-secret’
export APP_OIDC_FRONTENDURI=’http://localhost:8081'

If you use another realm, update both APP_OIDC_REALM and APP_OIDC_ISSUER. For a realm named helidon-lab, the issuer is http://localhost:8080/realms/helidon-lab.

Start the Helidon Application

From the directory containing the downloaded JAR, run:

java -jar helidon-keycloak-lab.jar

The application starts on port 8081.

Validate the Login Flow

Open the public page:

http://localhost:8081/public

The public page opens without signing in.

Then open the private page:

http://localhost:8081/private

Helidon redirects the browser to Keycloak. Sign in with the test user created earlier. After successful login, Keycloak redirects the browser to /oidc/redirect, and Helidon returns the browser to /private.

The private page confirms that the user was authenticated by Keycloak and displays the authenticated username and available grants.

More Details

This post focuses on downloading and running the release packages.

For the detailed Helidon configuration, detailed Keycloak setup, troubleshooting, and full walkthrough, refer to the main article:

https://blogbypuneeth.medium.com/github-demo-helidon-se-with-keycloak-oidc-protecting-a-private-page-bbde16876c73