Preparing and Configuring Keycloak

The first step in Security implementation is to have a Keycloak instance. This section discusses creating and configuring Keycloak step-by-step.

 In many tutorials, there are prepared configurations that can be imported to Keycloak to get started easily. You will not be doing this here. You will be going step by step to perform all the needed configuration. This is the best way to learn: learning by doing.

Open http://localhost:9080 to access the welcome page:

Next, click Administration Console to authenticate to the console. Use the admin credentials for the username and password:

Next, you need to create a new realm . Start by clicking Add Realm:

When you boot up Keycloak for the first time, it creates a predefined realm for you. This initial realm is the master realm. It is the highest level in the hierarchy of realms. Admin accounts in this realm have permissions to view and manage any other realm created on the server instance. When you define your initial admin account, you create an account in the master realm. Your initial login to the admin console will also be via the master realm.

You will land next on the first step of creating a new realm. Call the realm quarkushop-realm then click Create:

Next, you will get the quarkushop-realm configuration page:

In the quarkushop-realm, you need to define the roles that you will be using: the user and admin roles. To do this, simply go to Roles ➤Add Role:

Now you can create the admin role :

Create the user role as well:

Now that you have created the roles, you need to create the users. Just go to the Users menu:

 Sometimes on this screen, the list of users isn’t loaded when you open the page. If this happens, just click View All Users to load the list.

Click Add User to create the users (for this example, Nebrass, Jason, and Marie):

Then after clicking Save, click the Credentials tab, where you will define the user passwords.

 Don’t forget to set the Temporary to OFF to prevent Keycloak from asking you to update the password on the first login. Then, click Set Password:

Next, go to the Role Mappings tab and add all the roles to Nebrass. Yes! I’ll be the admin of this app.

Now create the Jason user and define a password:

Add the user role to Jason:

Next, create the Marie user and define a password:

Add the user role to Marie:

You are finished configuring roles and users! Now, click Clients to list the realm clients.

Click Create to add a new client with the following settings:

Click Save to get the client configuration screen:

It’s mandatory to define a protocol mapper for your client.

Click the Mappers tab to configure a mapper:

Then click Create to add a new mapper:

 Why Do We Define Token Claim Name as Groups?

We will use the protocol mapper to map the User Realm role (which can be user or admin) to a property called groups, which we will add as a plain string to the ID token, the access token, and the userinfo.

This is why we defined our mapper to affect the User roles to the Groups property embedded in the JWT token.

 The URL http://localhost:9080/auth/realms/quarkushop-realm/protocol/openid-connect/token is composed of:

 The jq is a lightweight and flexible command-line JSON processor that I’m using to format the JSON output.

 For prettier output, I omitted the value of refresh_token, as it’s very long and useless.

Copy the access_token value. Then go to jwt.io and paste the JWT access_token there to decode it:

Note that there is a JSON attribute called groups that holds the Roles array that we assigned to Nebrass in Keycloak.

Good! Keycloak is running and working like expected. You’ll now begin implementing security on the Java side.

Implementing the auth² Java Components in QuarkuShop

Java Source Code Side

In the Java code, you need to protect the REST APIs based on the authorization matrix that we created for each service.

Let’s begin with the Carts REST API, where all operations are allowed for users and admins. Only the authenticated subjects are allowed on the Carts REST API. To satisfy this requirement, we have an @Authenticated annotation from the io.quarkus.security package, which will grant access only to authenticated subjects.

 To differentiate between an application user and the role user, I will refer to an application user as a subject. The term subject came in the old good Java Authentication and Authorization Service (JAAS) to represent the caller that is making a request to access a resource. A subject may be any entity, including as a person or service.

As all the operations in the CartResource require an authenticated subject, you have to annotate the CartResource class with @Authenticated so it will be applied to all the operations. See Listing 6-1.

@Authenticated

@Path("/carts")

@Tags(value = @Tag(name = "cart", description = "All the cart methods"))

public class CartResource {

    ...

}

Listing 6-1

com.targa.labs.quarkushop.web.CartResource

The next REST API is the Category API, where only the admin can create and delete categories. All the other operations are allowed by everyone (the admin, user, and anonymous). To grant access to a specific role only, use the @RolesAllowed annotation from the javax.annotation.security package.

 JavaDoc of javax.annotation.security.RolesAllowed

@RolesAllowed: Specifies the list of security roles permitted to access the method(s) in an application.

The value of the @RolesAllowed annotation is a list of security role names. This annotation can be specified on a class or on methods:

• Specifying it at a class level means that it applies to all the operations in the class.

• Specifying it on a method means that it applies to that method only.

• If applied to the class and operations levels, the method value overrides the class value when the two conflict.

Based on the JavaDoc, we will pass the desired role as the value of the annotation. Apply the @RolesAllowed("admin") annotation to the operations where you create and delete categories:

@Path("/categories")

@Tags(value = @Tag(name = "category", description = "All the category methods"))

public class CategoryResource {

    ...

    @RolesAllowed("admin")

    @POST

        public CategoryDto create(CategoryDto categoryDto) {

        return this.categoryService.create(categoryDto);

    }

    @RolesAllowed("admin")

    @DELETE

    @Path("/{id}")

    public void delete(@PathParam("id") Long id) {

        this.categoryService.delete(id);

    }

}

For the Customer REST API, only the admin is allowed to access all the services. Annotating the CustomerResource class with @RolesAllowed("admin") will apply this policy.

Next is the Order REST API, where the authenticated subjects can access all the operations, except for the findAll() method , which is allowed only for admin. So we combine the two @Authenticated annotations in the class level and @RolesAllowed on the method requiring a specific role:

@Authenticated

@Path("/orders")

@Tag(name = "order", description = "All the order methods")

public class OrderResource {

    ...

    @RolesAllowed("admin")

    @GET

    public List<OrderDto> findAll() {

        return this.orderService.findAll();

    }

    ...

}

 While we are using @RolesAllowed in the local method, we are overriding the policy applied by the class level @Authenticated.

After OrderResource, we will deal with the OrderItem REST API, where only authenticated subjects are allowed to access all the services. Annotating the OrderItemResource class with @Authenticated will apply this policy.

The PaymentResource grants access only to authenticated subjects, except that deleting and listing all payments are granted only to the admin:

@Authenticated

@Path("/payments")

@Tag(name = "payment", description = "All the payment methods")

public class PaymentResource {

    ...

    @RolesAllowed("admin")

    @GET

    public List<PaymentDto> findAll() {

        return this.paymentService.findAll();

    }

    @RolesAllowed("admin")

    @DELETE

    @Path("/{id}")

    public void delete(@PathParam("id") Long id) {

        this.paymentService.delete(id);

    }

    ...

}

For the Product REST API, all operations are allowed by everyone, except for creating and deleting products, which are allowed only by the admin:

@Path("/products")

@Tag(name = "product", description = "All the product methods")

public class ProductResource {

    ...

    @RolesAllowed("admin")

    @POST

        public ProductDto create(ProductDto productDto) {

        return this.productService.create(productDto);

    }

    @RolesAllowed("admin")

    @DELETE

    @Path("/{id}")

    public void delete(@PathParam("id") Long id) {

        this.productService.delete(id);

    }

    ...

}

Finally, the last REST API is ReviewResource:

@Path("/reviews")

@Tag(name = "review", description = "All the review methods")

public class ReviewResource {

    ...

    @Authenticated

    @POST

    @Path("/product/{id}")

        public ReviewDto create(ReviewDto reviewDto, @PathParam("id") Long id) {

        return this.reviewService.create(reviewDto, id);

    }

    @RolesAllowed("admin")

    @DELETE

    @Path("/{id}")

    public void delete(@PathParam("id") Long id) {

        this.reviewService.delete(id);

    }

}

Great! You have applied the first-level authorization layer!

Don’t be too confident, though. This implementation leaks more levels of authorization. For example, users are authorized to delete Orders or OrderItems, but we can’t verify that the authenticated subject is only deleting his own Orders or OrderItems and not those of other users. We know how to define access rules based on roles, but how can we gather more information about the authenticated subject?

For this purpose, we will create a new REST API called UserResource. When invoked, UserResource will return the current authenticated subject information as a response.

UserResource will look like this:

@Path("/user")

@Authenticated

@Tag(name = " user", description = "All the user methods")

public class UserResource {

    @Inject

    JsonWebToken jwt;                                           ①

    @GET

    @Path("/current/info")

    public JsonWebToken getCurrentUserInfo() {                  ②

        return jwt;

    }

    @GET

    @Path("/current/info/claims")

    public Map<String, Object> getCurrentUserInfoClaims() {     ③

        return jwt.getClaimNames()

                .stream()

                .map(name -> Map.entry(name, jwt.getClaim(name)))

                .collect(Collectors.toMap(

                        entry -> entry.getKey(),

                        entry -> entry.getValue())

                );

    }

}

• ① Inject a JsonWebToken, which is an implementation of the specification that defines the use of JWT as a bearer token. This injection will use an instance of the JWT token in the incoming request.

• ② The JsonWebToken will return the injected JWT token.

• ③ The getCurrentUserInfoClaims() method will return the list of the available claims and their respective values embedded in the JWT token. The claims will be extracted from the JWT token instance injected in the UserResource.

Let’s test this new REST API. Start by getting a new access_token:

export access_token=$(curl -X POST http://localhost:9080/auth/realms/quarkushop-realm/protocol/openid-connect/token

      -H 'content-type: application/x-www-form-urlencoded'

      -d 'client_id=quarkushop'

      -d 'username=nebrass'

      -d 'password=password'

      -d 'grant_type=password' | jq --raw-output '.access_token')

Then, invoke the /user/current/info REST API:

curl -X GET -H "Authorization: Bearer $access_token" http://localhost:8080/api/user/current/info | jq '.'

You will get as a response the JWT token:

{

  "audience": [

    "account"

  ],

  "claimNames": [

    "sub", "resource_access", "email_verified", "allowed-origins", "raw_token", "iss",

    "groups", "typ", "preferred_username", "given_name", "aud", "acr", "realm_access",

    "azp", "scope", "name", "exp", "session_state", "iat", "family_name", "jti", "email"

  ],

  "expirationTime": 1597530481,

  "groups": ["offline_access", "admin", "uma_authorization", "user"],

  "issuedAtTime": 1597530181,

  "issuer": "http://localhost:9080/auth/realms/quarkushop-realm",

  "name": "nebrass",

  "rawToken": "eyJhbGci...L5A",

  "subject": "355877ad-2677-482b-a95f-a28f7fdb5999",

  "tokenID": "7416ee6e-e74c-45ae-bf85-8889744eaacf"

}

Good, we have the available claims. Let’s get their respective values:

{

  "sub": "355877ad-2677-482b-a95f-a28f7fdb5999",

  "resource_access": {

    "account": {

      "roles": ["manage-account", "manage-account-links", "view-profile"]

    }

  },

  "email_verified": true,

  "allowed-origins": ["http://localhost:8080"],

  "raw_token": "eyJhbGci...L5A",

  "iss": "http://localhost:9080/auth/realms/quarkushop-realm",

  "groups": ["offline_access", "admin", "uma_authorization", "user"],

  "typ": "Bearer",

  "preferred_username": "nebrass",

  "given_name": "Nebrass",

  "aud": ["account"],

  "acr": "1",

  "realm_access": {

    "roles": ["offline_access", "admin", "uma_authorization", "user"]

  },

  "azp": "quarkushop",

  "scope": "email profile",

  "name": "Nebrass Lamouchi",

  "exp": 1597530481,

  "session_state": "68069099-f534-434f-8d08-d8d75b8ff1c6",

  "iat": 1597530181,

  "family_name": "Lamouchi",

  "jti": "7416ee6e-e74c-45ae-bf85-8889744eaacf",

  "email": "[email protected]"

}

Wonderful! Now you know how to access the security details that you can use to identify the authenticated subjects exactly. By the way, you can have the same information about the JWT token. You can get the same JWT token an alternative way:

@GET()

@Path("/current/info-alternative")

public Principal getCurrentUserInfoAlternative(@Context SecurityContext ctx) {

    return ctx.getUserPrincipal();

}

The @Context SecurityContext ctx passed as the method parameter is used to inject the SecurityContext in the current context.

 SecurityContext is an injectable interface that provides access to security-related information like the Principal.

 The Principal interface represents the abstract notion of a principal, which can be used to represent any entity, such as an individual, a corporation, or a login ID. In this case, the principal is the JWT token.

 I will not dig into the full implementation of the authorization layer. I will stop here; otherwise, I would need to spend two more chapters just on this content.

The last step of the security part is to add a REST API that returns an access_token for a given username and password. This can be useful, especially with the Swagger UI. Speaking of Swagger UI, we need to make it aware of our Security layer.

We will start by creating the TokenService, which will be the REST client that makes the request of the access_token from Keycloak.

As we are using Java 11, we can enjoy one of its great new features: the brand new HTTP client.

As you did before using the cURL command, you need to use the Java 11 HTTP client to request an access_token:

@RequestScoped                              ①

public class TokenService {

    @ConfigProperty(name = "mp.jwt.verify.issuer", defaultValue = "undefined")

    Provider<String> jwtIssuerUrlProvider;  ②

    @ConfigProperty(name = "keycloak.credentials.client-id", defaultValue = "undefined")

    Provider<String> clientIdProvider;      ③

    public String getAccessToken(String userName, String password)

                        throws IOException, InterruptedException {

        String keycloakTokenEndpoint =

                    jwtIssuerUrlProvider.get() + "/protocol/openid-connect/token";

        String requestBody = "username=" + userName + "&password=" + password +

                    "&grant_type=password&client_id=" + clientIdProvider.get();

        if (clientSecret != null) {

            requestBody += "&client_secret=" + clientSecret;

        }

        HttpClient client = HttpClient.newBuilder().build();

        HttpRequest request = HttpRequest.newBuilder()

                .POST(BodyPublishers.ofString(requestBody))

                .uri(URI.create(keycloakTokenEndpoint))

                .header("Content-Type", "application/x-www-form-urlencoded")

                .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

        String accessToken = "";

        if (response.statusCode() == 200) {

            ObjectMapper mapper = new ObjectMapper();

            try {

                accessToken = mapper.readTree(response.body()).get("access_token").textValue();

            } catch (IOException e) {

                e.printStackTrace();

            }

        } else {

            throw new UnauthorizedException();

        }

        return accessToken;

    }

}

• ① The annotation creates an instance of TokenService for every HTTP request.

• ② Gets the mp.jwt.verify.issuer property value to build the Keycloak token’s endpoint URL.

• ③ Gets the keycloak.credentials.client-id property value, which is needed to request the access_token.

 We are getting the property value as Provider<String> and not String to avoid failing the native image build.

Next, add the getAccessToken() method:

@Path("/user")

@Authenticated

@Tag(name = " user", description = "All the user methods")

public class UserResource {

    @Inject JsonWebToken jwt;

    @POST

    @PermitAll

    @Path("/access-token")

    @Produces(MediaType.TEXT_PLAIN)

    public String getAccessToken(@QueryParam("username") String username,

                                @QueryParam("password") String password)

                        throws IOException, InterruptedException {

        return tokenService.getAccessToken(username, password);

    }

    ...

}

Excellent! You can test the new method from the Swagger UI:

Yippee! You now need to find a way to make Swagger UI apply the access_token to request all the REST APIs.

I thought this would be a long trip, but it was a very easy task. Just 10 lines of code are enough to make the party:

@SecurityScheme(

        securitySchemeName = "jwt",             ①

        description = "JWT authentication with bearer token",

        type = SecuritySchemeType.HTTP,         ①

        in = SecuritySchemeIn.HEADER,           ①

        scheme = "bearer",                      ①

        bearerFormat = "Bearer [token]")        ①

@OpenAPIDefinition(

        info = @Info(                           ②

                title = "QuarkuShop API",

                description = "Sample application for the book 'Playing with Java Microservices with Quarkus and Kubernetes'",

                contact = @Contact(name = "Nebrass Lamouchi", email = "[email protected]", url = "https://blog.nebrass.fr"),

                version = "1.0.0-SNAPSHOT"

        ),

        security = @SecurityRequirement(name = "JWT") ③

)

public class OpenApiConfig extends Application {

}

• ① @SecurityScheme defines a security scheme that can be used by the OpenAPI operations.

• ② Add a description for the OpenAPI definition.

• ③ Link the created security schema jwt to the OpenAPI definition.

Check the Swagger UI again:

Note that there is the lock icon .

Use the getAccessToken() operation to create an access_token and then click Authorize to pass the generated access_token to the SecurityScheme. Finally, click Authorize:

Now, when you click any operation, Swagger UI will include the access_token as a bearer to every request.

Excellent! You now have the Keycloak and the Security Java components. Next, you need to refactor the tests to be aware of the Security layer.

Update the Integration Tests to Support auth²

For the tests, you need to dynamically provision the Keycloak instance, as you did for the database using the Testcontainers library.

We will use the same library to provision Keycloak. We will not use a plain Docker container as we did with PostgreSQL, because there, Flyway populated the database for us. For Keycloak, we don’t have a built-in mechanism that will create the Keycloak realms for us. The only possible solution is to use a Docker Compose file that will import a sample Keycloak realms file. Fortunately, Testcontainers has great support to provision Docker Compose files.

The QuarkusTestResourceLifecycleManager will communicate with the provisioned Keycloak instance using the TokenService that we created, and it will use the sample Realm credentials to get access_tokens that we will use in the integration tests.

We will get two access_tokens: one for the admin role and one for the user role. We will store them, along with mp.jwt.verify.publickey.location and mp.jwt.verify.issuer, as system properties in the current test scope.

We will use it with the @QuarkusTestResource(KeycloakRealmResource.class) annotation.

Good! I implemented all the tests; you can find them in my GitHub repository.

Adding Keycloak to the Production Environment

The last step is to add the production Keycloak entries to Docker Compose in the Production VM. We also need to add the Production realms.

You can export the realm from the local Keycloak instance in very few steps.

You will get two Keycloak realm files—quarkushop-realm-realm.json and quarkushop-realm-users-0.json—in ~/keycloak-realms.

 The "sslRequired": "none" property disables the required SSL certificate for any request.

Then, copy the two files—quarkushop-realm-realm.json and quarkushop-realm-users-0.json—to the /opt/realms directory in the Azure VM instance, which is the Production environment.

Here we are in the Azure VM instance. We will finish the last step: adding the Keycloak service to the /opt/docker-compose.yml file:

 1 version: '3'

 2 services:

 3   quarkushop:

 4     image: nebrass/quarkushop-monolithic-application:latest

 5     environment:

 6       - QUARKUS_DATASOURCE_JDBC_URL=jdbc:postgresql://postgresql-db:5432/demo

 7       -

  MP_JWT_VERIFY_PUBLICKEY_LOCATION=http://51.103.50.23:9080/auth/realms/quarkushoprealm/protocol/openid-connect/certs   ①

 8       - MP_JWT_VERIFY_ISSUER=http://51.103.50.23:9080/auth/realms/quarkushop-realm ①

 9    ports:

10      - 8080:8080

11   postgresql-db:

12     image: postgres:13

13     volumes:

14       - /opt/postgres-volume:/var/lib/postgresql/data

15     environment:

16       - POSTGRES_USER=developer

17       - POSTGRES_PASSWORD=p4SSW0rd

18       - POSTGRES_DB=demo

19       - POSTGRES_HOST_AUTH_METHOD=trust

20    ports:

21      - 5432:5432

22   keycloak:                                     ②

23     image: jboss/keycloak:latest

24     command:

25       [

26         '-b','0.0.0.0',

27

28         '-Dkeycloak.migration.action=import',

29         '-Dkeycloak.migration.provider=dir',

30         '-Dkeycloak.migration.dir=/opt/jboss/keycloak/realms',

31         '-Dkeycloak.migration.strategy=OVERWRITE_EXISTING',

32         '-Djboss.socket.binding.port-offset=1000',

33         '-Dkeycloak.profile.feature.upload_scripts=enabled',

34       ]

35

36

37   volumes:

38     - ./realms:/opt/jboss/keycloak/realms

39   environment:

40     - KEYCLOAK_USER=admin     ③

41     - KEYCLOAK_PASSWORD=admin ③

42     - DB_VENDOR=POSTGRES      ④

43     - DB_ADDR=postgresql-db   ⑤

44     - DB_DATABASE=demo        ⑥

45     - DB_USER=developer       ⑥

46     - DB_SCHEMA=public        ⑥

47     - DB_PASSWORD=p4SSW0rd    ⑥

48   ports:

49     - 9080:9080

50   depends_on:                 ⑦

51     - postgresql-db           ⑦

• ① Overrides the MP_JWT_VERIFY_PUBLICKEY_LOCATION and MP_JWT_VERIFY_ISSUER properties to ensure that the application points to the Azure VM instance instead of the localhost.

• ② Adds the Keycloak Docker service.

• ③ Defines the Keycloak cluster’s username and password.

• ④ Defines the Keycloak Database vendor as PostgreSQL, as we have a PostgreSQL DB instance in our services.

• ⑤ Defines the DB host as the postgresql-db, which will be resolved dynamically by Docker with the service IP.

• ⑥ Defines the Keycloak database credentials as the same as the PostgreSQL credentials.

• ⑦ Expresses the dependency between the Keycloak and PostgreSQL services.

 As you can see, all the credentials are listed as plain text in the docker-compose.yml file.

 Unfortunately, this feature is available only for Docker Swarm clusters.

Good! The Docker Compose services are ready to go!

We need just to add an exception to the Azure VM instance networking rules for the Keycloak port. In the Azure VM instance, go to the Networking section and add an exception for port 9080:

Excellent! The production environment has all the needed elements to deploy a new version of the QuarkuShop container without risking the PostgreSQL DB or the Keycloak cluster.

Go to the production Swagger UI and enjoy QuarkuShop: the greatest online store!

Good! It’s time to move to the next anti-disaster layer: monitoring .