Quarkus - Using OpenID Connect to Protect Web Applications

This guide demonstrates how to use the OpenID Connect Extension to protect your application using Quarkus, where authentication and authorization are based on tokens issued by OpenId Connect and OAuth 2.0 compliant Authorization Servers such as Keycloak.

The extension allows you to easily enable authentication to your web application based on the Authorization Code Flow so that your users are redirected to a OpenID Connect Provider (e.g.: Keycloak) to authenticate and, once the authentication is complete, return back to your application.

We are going to give you a guideline on how to use OpenId Connect to authenticate users using the Quarkus OpenID Connect Extension.

Prerequisites

To complete this guide, you need:

  • less than 15 minutes

  • an IDE

  • JDK 1.8+ installed with JAVA_HOME configured appropriately

  • Apache Maven 3.6.2+

  • jq tool

  • Docker

Architecture

In this example, we build a very simple web application with a single page:

  • /index.html

This page is protected and can only be accessed by authenticated users.

Solution

We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the completed example.

Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.

The solution is located in the security-openid-connect-web-authentication-quickstart directory.

Creating the Maven Project

First, we need a new project. Create a new project with the following command:

mvn io.quarkus:quarkus-maven-plugin:1.6.0.Final:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=security-openid-connect-web-authentication-quickstart \
    -Dextensions="oidc"
cd security-openid-connect-web-authentication-quickstart

If you already have your Quarkus project configured, you can add the oidc extension to your project by running the following command in your project base directory:

./mvnw quarkus:add-extension -Dextensions="oidc"

This will add the following to your pom.xml:

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-oidc</artifactId>
</dependency>

Configuring the application

The OpenID Connect extension allows you to define the configuration using the application.properties file which should be located at the src/main/resources directory.

Configuring using the application.properties file

quarkus.oidc.auth-server-url=http://localhost:8180/auth/realms/quarkus
quarkus.oidc.client-id=frontend
quarkus.oidc.application-type=web-app
quarkus.http.auth.permission.authenticated.paths=/*
quarkus.http.auth.permission.authenticated.policy=authenticated

This is the simplest configuration you can have when enabling authentication to your application.

The quarkus.oidc.client-id property references the client_id issued by the OpenID Connect Provider and, in this case, the application is a public client (no client secret is defined).

The quarkus.oidc.application-type property is set to web-app in order to tell Quarkus that you want to enable the OpenID Connect Authorization Code Flow, so that your users are redirected to the OpenID Connect Provider to authenticate.

For last, the quarkus.http.auth.permission.authenticated permission is set to tell Quarkus about the paths you want to protect. In this case, all paths are being protected by a policy that ensures that only authenticated users are allowed to access. For more details check Security Guide.

Starting and Configuring the Keycloak Server

To start a Keycloak Server you can use Docker and just run the following command:

docker run --name keycloak -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin -p 8180:8080 {keycloak-docker-image}

You should be able to access your Keycloak Server at localhost:8180/auth.

Log in as the admin user to access the Keycloak Administration Console. Username should be admin and password admin.

Import the realm configuration file to create a new realm. For more details, see the Keycloak documentation about how to create a new realm.

Running and Using the Application

Running in Developer Mode

To run the microservice in dev mode, use ./mvnw clean compile quarkus:dev.

Running in JVM Mode

When you’re done playing with "dev-mode" you can run it as a standard Java application.

First compile it:

./mvnw package

Then run it:

java -jar ./target/security-openid-connect-web-authentication-quickstart-runner.jar

Running in Native Mode

This same demo can be compiled into native code: no modifications required.

This implies that you no longer need to install a JVM on your production environment, as the runtime technology is included in the produced binary, and optimized to run with minimal resource overhead.

Compilation will take a bit longer, so this step is disabled by default; let’s build again by enabling the native profile:

./mvnw package -Pnative

After getting a cup of coffee, you’ll be able to run this binary directly:

./target/security-openid-connect-web-authentication-quickstart-runner

Testing the Application

To test the application, you should open your browser and access the following URL:

If everything is working as expected, you should be redirected to the Keycloak server to authenticate.

In order to authenticate to the application you should type the following credentials when at the Keycloak login page:

  • Username: alice

  • Password: alice

After clicking the Login button you should be redirected back to the application.

Redirection

When the user is redirected to the OpenID Connect Provider to authenticate, the redirect URL includes a redirect_uri query parameter which indicates to the Provider where the user has to be redirected to once the authentication has been completed.

Quarkus will set this parameter to the current request URL by default. For example, if the user is trying to access a Quarkus service endpoint at http://localhost:8080/service/1 then the redirect_uri parameter will be set to http://localhost:8080/service/1. Similarly, if the request URL is http://localhost:8080/service/2 then the redirect_uri parameter will be set to http://localhost:8080/service/2, etc.

OpenID Connect Providers may be configured to require the redirect_uri parameter to have the same value (eg. http://localhost:8080/service/callback) for all the redirect URLs. In such cases a quarkus.oidc.authentication.redirect-path property has to be set, for example, quarkus.oidc.authentication.redirect-path=/service/callback, and Quarkus will set the redirect_uri parameter to an absolute URL such as http://localhost:8080/service/callback which will be the same regardless of the current request URL.

If quarkus.oidc.authentication.redirect-path is set but the original request URL has to be restored after the user has been redirected back to a callback URL such as http://localhost:8080/service/callback then a quarkus.oidc.authentication.restore-path-after-redirect property has to be set to true which will restore the request URL such as http://localhost:8080/service/1, etc.

Logout

By default the logout is based on the expiration time of the ID Token issued by the OpenID Connect Provider. When the ID Token expires, the current user session at the Quarkus endpoint is invalidated and the user is redirected to the OpenID Connect Provider again to authenticate. If the session at the OpenID Connect Provider is still active, users are automatically re-authenticated without having to provide their credentials again.

The current user session may be automatically extended by enabling a quarkus.oidc.token.refresh-expired property. If it is set to true then when the current ID Token expires a Refresh Token Grant will be used to refresh ID Token as well as Access and Refresh Tokens.

User-Initiated Logout

Users can request a logout by sending a request to the Quarkus endpoint logout path set with a quarkus.oidc.logout.path property. For example, if the endpoint address is https://application.com/webapp and the quarkus.oidc.logout.path is set to "/logout" then the logout request has to be sent to https://application.com/webapp/logout.

This logout request will start an RP-Initiated Logout and the user will be redirected to the OpenID Connect Provider to logout where a user may be asked to confirm the logout is indeed intended.

The user will be returned to the endpoint post logout page once the logout has been completed if the quarkus.oidc.logout.post-logout-path property is set. For example, if the endpoint address is https://application.com/webapp and the quarkus.oidc.logout.post-logout-path is set to "/signin" then the user will be returned to https://application.com/webapp/signin (note this URI must be registered as a valid post_logout_redirect_uri in the OpenID Connect Provider).

If the quarkus.oidc.logout.post-logout-path is set then a q_post_logout cookie will be created and a matching state query parameter will be added to the logout redirect URI and the OpenID Connect Provider will return this state once the logout has been completed. It is recommended for the Quarkus web-app applications to check that a state query parameter matches the value of the q_post_logout cookie which can be done for example in a JAX-RS filter.

Note that a cookie name will vary when using OpenID Connect Multi-Tenancy. For example, it will be named q_post_logout_tenant_1 for a tenant with a tenant_1 id, etc.

Accessing ID and Access Tokens

ID Token is always a JWT token. One can access ID Token claims by injecting JsonWebToken with an IdToken qualifier:

import javax.inject.Inject;
import org.eclipse.microprofile.jwt.JsonWebToken;
import io.quarkus.oidc.IdToken;
import io.quarkus.security.Authenticated;

@Path("/web-app")
@Authenticated
public class ProtectedResource {

    @Inject
    @IdToken
    JsonWebToken idToken;

    @GET
    public String getUserName() {
        return idToken.getName();
    }
}

Access Token is usually used by the OIDC web-app application to access other endpoints on behalf of the currently logged in user. The raw access token can be accessed as follows:

import javax.inject.Inject;
import org.eclipse.microprofile.jwt.JsonWebToken;
import io.quarkus.oidc.AccessTokenCredential;
import io.quarkus.security.Authenticated;

@Path("/web-app")
@Authenticated
public class ProtectedResource {

    @Inject
    JsonWebToken accessToken;

    // or
    // @Inject
    // AccessTokenCredential accessTokenCredential;

    @GET
    public String getReservationOnBehalfOfUser() {
        String rawAccessToken = accessToken.getRawToken();
        //or
        //String rawAccessToken = accessTokenCredential.getToken();

        // Use the raw access token to access a remote endpoint
        return getReservationfromRemoteEndpoint(rawAccesstoken);
    }
}

Note that AccessTokenCredential will have to be used if the Access Token issued to the Quarkus web-app application is opaque (binary) and can not be parsed to JsonWebToken.

Injection of the JsonWebToken and AccessTokenCredential is supported in both @RequestScoped and @ApplicationScoped contexts.

Configuration Reference

References

Quarkus is open. All dependencies of this project are available under the Apache Software License 2.0 or compatible license.

This website was built with Jekyll, is hosted on Github Pages and is completely open source. If you want to make it better, fork the website and show us what you’ve got.

Navigation
Contribute
Get Help
Quarkus is made of community projects
CC by 3.0 | Privacy Policy Sponsored by