Authorization in Quarkus
Updated on January 24, 2024In this lab, you will:
- Learn how to build a Quarkus API with Java.
- Learn how to secure your API with OAuth 2.0.
- Test your protected API endpoints.
Why Use Quarkus to Build APIs?
Quarkus is a Kubernetes-native Java framework tailored for GraalVM and the JVM, with the goal of making Java the leading platform in Kubernetes and serverless environments, while offering developers a framework to address a wider range of distributed application architectures.
The OAuth 2.0 authorization framework is a protocol that allows a user to grant a third-party website or application access to the user's protected resources without necessarily revealing their long-term credentials or even their identity.
In this lab, you'll learn how to use Java and Quarkus to build a REST API that's secured with OAuth 2.0. You'll also learn how to make authenticated requests to test it works as expected.
Lab Setup
Set up a development environment
- Use your favorite text editor or IDE. We recommend using IntelliJ IDEA.
- Ensure that you have Java
17+
installed in your system. You can easily install it using SDKMAN!. - Windows commands in this lab are written for PowerShell.
Create an Auth0 Account
If you already have an Auth0 account, you can log in to your tenant and continue to the next step.
Otherwise, sign up for a free Auth0 account.
During the sign-up process, you create something called an Auth0 Tenant, where you configure your use of Auth0.
Set up the Auth0 CLI
If you are not familiar with the Auth0 CLI, you can follow the "Auth0 CLI Basics" lab to learn how to build, manage, and test your Auth0 integrations from the command line.
There are different ways to install the Auth0 CLI, depending on your operating system.
Test the Auth0 CLI installation
Run the following command to show in the terminal the version of your Auth0 CLI installation:
auth0 --version
You should see the following output:
auth0 version <version-number> <hash>
Install the Quarkus CLI
Use SDKMAN to install the Quarkus CLI:
curl -s "https://get.sdkman.io" | bashsdk install quarkus
For more installation options, see the Quarkus documentation.
Install HTTPie (Optional)
HTTPie is a command-line HTTP and API testing client that can be used instead of cURL for sending API requests. You can install it using the official installation guide if you are interested.
Create a Quarkus API
Create a new app with JWT support:
quarkus create app com.okta.rest:quarkus --extension="smallrye-jwt,resteasy-reactive" --gradle
For Maven support, pass the option --maven
instead of --gradle
.
Navigate to the quarkus
project folder and run your Quarkus app:
quarkus dev
Test the API from another terminal:
http :8080/hello
Secure Your API with OAuth 2.0
In a terminal, connect the Auth0 CLI to your Auth0 tenant.
auth0 login
auth0 login
command.Then, run the command below to see your available Auth0 tenants:
auth0 tenants list
Copy the domain of the Auth0 tenant that you'd like to use and paste it into the following input box:
When you enter a value in the input fields present on this page, any code snippet that uses such value updates to reflect it. Using the input fields makes copying and pasting code as you follow along easy.
Now, update the content of the src/main/resources/application.properties
file to configure a resource server using the Auth0 domain:
mp.jwt.verify.issuer=https://AUTH0-DOMAIN/mp.jwt.verify.publickey.location=${mp.jwt.verify.issuer}.well-known/jwks.json
The second value, mp.jwt.verify.publickey.location
, reads from the first, mp.jwt.verify.issuer
, so you only need to provide a value for mp.jwt.verify.publickey.location
.
Rename GreetingResource.java
to HelloResource.java
and add user information to the hello()
method:
package com.okta.rest;import io.quarkus.security.Authenticated;import jakarta.ws.rs.GET;import jakarta.ws.rs.Path;import jakarta.ws.rs.Produces;import jakarta.ws.rs.core.Context;import jakarta.ws.rs.core.MediaType;import jakarta.ws.rs.core.SecurityContext;import java.security.Principal;@Path("/hello")public class HelloResource {@GET@Authenticated@Produces(MediaType.TEXT_PLAIN)public String hello(@Context SecurityContext context) {Principal userPrincipal = context.getUserPrincipal();return "Hello, " + userPrincipal.getName() + "!";}}
Rename GreetingResourceTest.java
to HelloResourceTest.java
and modify it to expect a 401
instead of a 200
:
package com.okta.rest;import io.quarkus.test.junit.QuarkusTest;import org.junit.jupiter.api.Test;import static io.restassured.RestAssured.given;@QuarkusTestpublic class HelloResourceTest {@Testpublic void testHelloEndpoint() {given().when().get("/hello").then().statusCode(401);}}
Test Your API
Open a new terminal to test the /hello
endpoint in the HelloResource.java
file:
http :8080/hello
You will get a 401 Unauthorized
response because you didn't pass in an access token.
Get an access token
You can get an access token using the Auth0 CLI to test making a secure call to your protected API endpoint:
auth0 test token -a https://AUTH0-DOMAIN/api/v2/ -s openid
Select any available client when prompted. You also will be prompted to open a browser window and log in with a user credential. You can sign up as a new user using an email and password or using the Google social login.
Paste the access token value in the following field so that you can use it to test your resource server:
Run the following command to make an authenticated request to your resource server:
http :8080/hello "Authorization: Bearer AUTH0-ACCESS-TOKEN"
You should receive a 200 OK
response with a message similar to the following:
Hello, auth0|61bcbc76f64d4a0072af8a1d!
Stop the resource server using Ctrl+C
.
Recap
In this lab, you learned how to build a Java REST API with Quarkus, secure it with OAuth 2.0, and learn how to make authenticated requests using the tool of your preference. If you'd like to see what's in the access token you created, you can copy and paste it into JWT.io. Isn't it cool how you can create and test a Quarkus API with Auth0 so quickly?
quarkus create app com.okta.rest:quarkus --extension="smallrye-jwt,resteasy-reactive" --gradlequarkus devauth0 tenants listauth0 test token -a https://AUTH0-DOMAIN/api/v2/ -s openidhttp :8080/hello "Authorization: Bearer AUTH0-ACCESS-TOKEN"
Check out our other Quarkus labs Authentication in Quarkus and Role Based Access Control in Quarkus to learn more about Auth0 security integration in Quarkus Java applications. To level-up your authorization game, check out this tutorial about how to use OpenFGA with Quarkus.