Chapter 2. Protect a service application by using OpenID Connect (OIDC) Bearer token authentication

To complete this guide, you need:

This example shows how you can build a simple microservice that offers two endpoints:

These endpoints are protected and can only be accessed if a client sends a bearer token along with the request, which must be valid (for example, signature, expiration, and audience) and trusted by the microservice.

A Keycloak server issues the bearer token and represents the subject for which the token was issued. Because it is an OAuth 2.0 authorization server, the token also references the client acting on the user’s behalf.

Any user with a valid token can access the /api/users/me endpoint. As a response, it returns a JSON document with user details obtained from the information in the token.

The /api/admin endpoint is protected with RBAC (Role-Based Access Control), which only users with the admin role can access. At this endpoint, the @RolesAllowed annotation is used to enforce the access constraint declaratively.

Follow the instructions in the next sections and create the application step by step. You can also go straight to the completed example.

You can clone the Git repository by running the command git clone https://github.com/quarkusio/quarkus-quickstarts.git -b 3.8, or you can download an archive.

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

You can either create a new Maven project with the oidc extension or you can add the extension to an existing Maven project. Complete one of the following commands:

To create a new Maven project, use the following command:

For Windows users:

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:

This will add the following to your build file:

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

Where:

For more information, see the Quarkus OpenID Connect (OIDC) configuration properties guide.

For more information, see the Keycloak documentation about creating and configuring a new realm.

When you are done with dev mode, you can run the application as a standard Java application.

You can compile this same demo as-is into native mode without any modifications. This implies that you no longer need to install a JVM on your production environment. The runtime technology is included in the produced binary and optimized to run with minimal resources required.

Compilation takes a bit longer, so this step is disabled by default.

For information about testing your application in dev mode, see the preceding Run the application in dev mode section.

You can test the application launched in JVM or native modes with curl.

export access_token=$(\
    curl --insecure -X POST http://localhost:8180/realms/quarkus/protocol/openid-connect/token \
    --user backend-service:secret \
    -H 'content-type: application/x-www-form-urlencoded' \
    -d 'username=alice&password=alice&grant_type=password' | jq --raw-output '.access_token' \
 )

export access_token=$(\
    curl --insecure -X POST http://localhost:8180/realms/quarkus/protocol/openid-connect/token \
    --user backend-service:secret \
    -H 'content-type: application/x-www-form-urlencoded' \
    -d 'username=alice&password=alice&grant_type=password' | jq --raw-output '.access_token' \
 )

The preceding example obtains an access token for the user alice.

curl -v -X GET \
  http://localhost:8080/api/users/me \
  -H "Authorization: Bearer "$access_token

curl -v -X GET \
  http://localhost:8080/api/users/me \
  -H "Authorization: Bearer "$access_token

curl -v -X GET \
   http://localhost:8080/api/admin \
   -H "Authorization: Bearer "$access_token

curl -v -X GET \
   http://localhost:8080/api/admin \
   -H "Authorization: Bearer "$access_token

export access_token=$(\
    curl --insecure -X POST http://localhost:8180/realms/quarkus/protocol/openid-connect/token \
    --user backend-service:secret \
    -H 'content-type: application/x-www-form-urlencoded' \
    -d 'username=admin&password=admin&grant_type=password' | jq --raw-output '.access_token' \
 )

export access_token=$(\
    curl --insecure -X POST http://localhost:8180/realms/quarkus/protocol/openid-connect/token \
    --user backend-service:secret \
    -H 'content-type: application/x-www-form-urlencoded' \
    -d 'username=admin&password=admin&grant_type=password' | jq --raw-output '.access_token' \
 )

For information about writing integration tests that depend on Dev Services for Keycloak, see the Dev Services for Keycloak section of the "OpenID Connect (OIDC) Bearer token authentication" guide.