By Version

Protect a web application by using OpenID Connect (OIDC) authorization code flow

With the Quarkus OpenID Connect (OIDC) extension, you can protect application HTTP endpoints by using the OIDC Authorization Code Flow mechanism.

To learn more about the OIDC authorization code flow mechanism, see OIDC code flow mechanism for protecting web applications.

To learn about how well-known social providers such as Google, GitHub, Microsoft, Twitter, Apple, Facebook, and Spotify can be used with Quarkus OIDC, see Configuring Well-Known OpenID Connect Providers. See also, Authentication mechanisms in Quarkus.

If you want to protect your service applications by using OIDC Bearer token authentication, see OIDC Bearer token authentication.

Pré-requisitos

Para concluir este guia, você precisa:

Cerca de 15 minutos
Um IDE
JDK 11+ instalado com 'JAVA_HOME' configurado adequadamente
Apache Maven 3.9.3
Um container runtime instalado (Docker ou Podman)
Opcionalmente, o Quarkus CLI se você quiser usá-lo
Opcionalmente, Mandrel ou GraalVM instalado e configurado apropriadamente se você quiser criar um executável nativo (ou Docker se você usar uma compilação de contêiner nativo)

Arquitetura

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.

Solução

Recomendamos que siga as instruções nas seções seguintes e crie a aplicação passo a passo. No entanto, você pode ir diretamente para o exemplo completo.

Clone o repositório Git: git clone -b 3.2 https://github.com/quarkusio/quarkus-quickstarts.git, ou baixe um arquivo.

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

Procedimento

Crie o projeto Maven

Primeiro, precisamos de um novo projeto. Crie um novo projeto com o seguinte comando:

CLI

quarkus create app org.acme:security-openid-connect-web-authentication-quickstart \
    --extension='resteasy-reactive,oidc' \
    --no-code
cd security-openid-connect-web-authentication-quickstart

Para criar um projeto Gradle, adicione a opção --gradle ou --gradle-kotlin-dsl.

Para obter mais informações sobre como instalar e usar a CLI do Quarkus, consulte o guia Quarkus CLI.

Maven

mvn io.quarkus.platform:quarkus-maven-plugin:3.2.12.Final:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=security-openid-connect-web-authentication-quickstart \
    -Dextensions='resteasy-reactive,oidc' \
    -DnoCode
cd security-openid-connect-web-authentication-quickstart

Para criar um projeto Gradle, adicione a opção '-DbuildTool=gradle' ou '-DbuildTool=gradle-kotlin-dsl'.

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:

CLI

quarkus extension add 'oidc'

Maven

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

Gradle

./gradlew addExtension --extensions='oidc'

Isto irá adicionar o seguinte trecho no seu arquivo de build:

pom.xml

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

build.gradle

implementation("io.quarkus:quarkus-oidc")

Escreva a aplicação

Let’s write a simple Jakarta REST resource which has all the tokens returned in the authorization code grant response injected:

package org.acme.security.openid.connect.web.authentication;

import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;

import org.eclipse.microprofile.jwt.JsonWebToken;

import io.quarkus.oidc.IdToken;
import io.quarkus.oidc.RefreshToken;

@Path("/tokens")
public class TokenResource {

   /**
    * Injection point for the ID Token issued by the OpenID Connect Provider
    */
   @Inject
   @IdToken
   JsonWebToken idToken;

   /**
    * Injection point for the Access Token issued by the OpenID Connect Provider
    */
   @Inject
   JsonWebToken accessToken;

   /**
    * Injection point for the Refresh Token issued by the OpenID Connect Provider
    */
   @Inject
   RefreshToken refreshToken;

   /**
    * Returns the tokens available to the application. This endpoint exists only for demonstration purposes, you should not
    * expose these tokens in a real application.
    *
    * @return a HTML page containing the tokens available to the application
    */
   @GET
   @Produces("text/html")
   public String getTokens() {
       StringBuilder response = new StringBuilder().append("<html>")
               .append("<body>")
               .append("<ul>");


       Object userName = this.idToken.getClaim("preferred_username");

       if (userName != null) {
           response.append("<li>username: ").append(userName.toString()).append("</li>");
       }

       Object scopes = this.accessToken.getClaim("scope");

       if (scopes != null) {
           response.append("<li>scopes: ").append(scopes.toString()).append("</li>");
       }

       response.append("<li>refresh_token: ").append(refreshToken.getToken() != null).append("</li>");

       return response.append("</ul>").append("</body>").append("</html>").toString();
   }
}

This endpoint has ID, access, and refresh tokens injected. It returns a preferred_username claim from the ID token, a scope claim from the access token, and also a refresh token availability status.

Note that you do not have to inject the tokens - it is only required if the endpoint needs to use the ID token to interact with the currently authenticated user or use the access token to access a downstream service on behalf of this user.

Configure a aplicação

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

quarkus.oidc.auth-server-url=http://localhost:8180/realms/quarkus
quarkus.oidc.client-id=frontend
quarkus.oidc.credentials.secret=secret
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 OIDC provider and the quarkus.oidc.credentials.secret property sets the client secret.

The quarkus.oidc.application-type property is set to web-app in order to tell Quarkus that you want to enable the OIDC authorization code flow, so that your users are redirected to the OIDC provider to authenticate.

Finally, 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 information, see Security Authorization Guide.

Start and configure the Keycloak server

To start a Keycloak server, use Docker and run the following command:

docker run --name keycloak -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin -p 8180:8080 quay.io/keycloak/keycloak:{keycloak.version} start-dev

where keycloak.version should be set to 17.0.0 or higher.

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

To access the Keycloak Administration Console, log in as the admin user. Username should be admin and password admin.

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

Run the application in dev and JVM modes

To run the application in a dev mode, use:

CLI

quarkus dev

Maven

./mvnw quarkus:dev

Gradle

./gradlew --console=plain quarkusDev

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

First, compile it:

CLI

quarkus build

Maven

./mvnw install

Gradle

./gradlew build

Then, run it:

java -jar target/quarkus-app/quarkus-run.jar

Run the application in Native mode

This same demo can be compiled into native code. No modifications are 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. You can build again by enabling the native build:

CLI

quarkus build --native

Maven

./mvnw install -Dnative

Gradle

./gradlew build -Dquarkus.package.type=native

After getting a cup of coffee, you can run this binary directly:

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

Test the application

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

http://localhost:8080/tokens

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

To authenticate to the application, type the following credentials when at the Keycloak login page:

Username: alice
Password: alice

After clicking the Login button, you are redirected back to the application.

For more information about writing the integration tests that depend on Dev Services for Keycloak, see the Dev Services for Keycloak section.

Summary

Congratulations! You have learned how to set up and use the OIDC authorization code flow mechanism to protect and test application HTTP endpoints. After you have completed this tutorial, explore OIDC Bearer token authentication and other authentication mechanisms.

Protect a web application by using OpenID Connect (OIDC) authorization code flow

Pré-requisitos

Arquitetura

Solução

Procedimento

Crie o projeto Maven

Escreva a aplicação

Configure a aplicação

Start and configure the Keycloak server

Run the application in dev and JVM modes

Run the application in Native mode

Test the application

Summary

Referências