To install Keycloak with Docker, open a terminal and make sure the port 8080 is free.

docker run -p 8080:8080 -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin quay.io/keycloak/keycloak:11.0.2

This will start Keycloak on local port 8080. It will create the admin user with username admin and password admin Feel free to modify 11.0.2 by any keycloak version of your wish. If you are running docker behind a proxy server, make sure it is either configured into docker or disabled. Otherwise, you might face a connection timeout because docker cannot download the required data.

To verify that Keycloak is running correctly, go to the admin console : http://localhost:8080/auth/admin Log in using the username and password mentioned above: admin.

You should be logged in successfully, and it prompts the admin console.

Download the last version of Keycloak from Keycloak website : https://www.keycloak.org/downloads In the table Server choose Standalone server distribution. ZIP or Tar format are available, click on either to download Keycloak.

After extracting the archive file, you should have a directory named keycloak followed by the version. For example, if you chose version 11.0.2, the folder must be named keycloak-11.0.2.

Open keycloak folder to make it your current directory.

cd keycloak-11.0.2

To start keycloak and have it ready for further steps, run the following command.

bin/standalone.sh

bin/standalone.bat

Keycloak runs on localhost:8080 by default.

You need to create an admin user because it does not come by default when installing Keycloak. To do this, open http://localhost:8080/auth in your favorite browser.

A window Welcome to Keycloak should be prompted. If not, check if any error appear in the terminal.

Fill the form by adding Username and Password. Click on Create to create the admin user.

Above Administration Console should be printed "User created" in a green rectangle.

To check that the admin user was created correctly, click on Administration user which should redirect you to a Login form. Enter the Username and Password created earlier to log in.

After successfully logged in, the admin console is prompted.

A realm is the place where groups of applications, and their environment, can be created. It gathers :

• One or several applications

• One or several users

• Sessions

• Events

• Clients and their scopes

By default, there is a realm called Master. It is used to manage Keycloak. It is not recommended to associate your application with this realm as it could disturb Keycloak functioning.

To create a new realm to manage your application:

1. Open Keycloak admin console http://localhost:8080/auth/admin.
2. Hover the mouse over the dropdown in the top-left corner where it says Master, and press Add realm.
3. Fill the form by adding the realm name, myRealm for example.
4. Click on Create to create the new realm.

To verify that your realm is created, on the top-left corner where it said Master previously should be now your realm name or myRealm is you followed the example.

To switch from a realm to another, hover the realm name, and the other realm created appear in the dropdown. Click on any realm name to change the current realm. Make sure all configuration or modification are saved before changing the current realm or be subject to lose your configuration.

Initially there are no users in a new realm. An unlimited number of user can be created per realm. A realm contains resources such as client which can be accessed by users.

To create a new user:

1. Open the Keycloak admin console: http://localhost:8080/auth/admin
2. Click on Users in the left menu
3. Press Add user
4. Fill the form (Username is the only mandatory field) with this value Username: myUser
5. Click Save

A new user is just created but it needs a password to be able to login. To initialize it, do this:

1. Click on Credentials at the top of the page, under Myuser.
2. Fill Password and Password confirmation with the user password of your choice.
3. If the Temporary field is set to ON, the user has to update password on next login. Click ON to make it OFF and prevent it.
4. Press Set Password.
5. A pop-up window is popping off. Click on Set Password to confirm the new password.

To verify that the new user is created correctly:

1. Open the Keycloak account console: http://localhost:8080/auth/realms/myRealm/account.
2. Login with myUser and password chosen earlier.

You should now be logged-in to the account console where users can manage their accounts.

To create your first client:

1. Open the Keycloak admin console: http://localhost:8080/auth/admin.
2. Make sure the current realm is myRealm and not Master.
3. Navigate to the left menu, into configure section, click on Clients. This window displays a table with every client from the realm.
4. Click on Create.
5. Fill the following:
   1. Client ID : myClientID
   2. Client Protocol : openid-connect
6. Press Save
   1. Modify Access type : confidential
   2. Update Valid Redirect URIs : http://localhost:7987/*
   3. Click on + to add the new URI.
7. Click on Save.

A new tab named Credentials is created. Click on it to access this new tab.

• Select Client Authenticator : Client ID and Secret

• Click on generate secret to generate client secret.

Keycloak is now configured and ready. Keep keycloak running on your terminal and open a new tab to set up Helidon.

Update the pom.xml file and add the following Helidon dependency to the <dependencies> section.

<dependency>
    <groupId>io.helidon.microprofile</groupId>
    <artifactId>helidon-microprofile-oidc</artifactId>
</dependency>

The OIDC security provider configuration can be joined to helidon configuration file. This file is located here: src/main/resources/application.yaml. It can be easily used to configure the web server without modifying application code.

security:
  providers:
    - abac:
      # Adds ABAC Provider - it does not require any configuration
    - oidc:
        redirect-uri: "/oidc/redirect"
        audience: "account"
        client-id: "myClientID"   
        header-use: true
        client-secret: "Client secret generated into Keycloak client credential"  
        identity-uri: "http://localhost:8080/auth/realms/myRealm"   
        frontend-uri: "http://localhost:7987"   

• client-id must be the same as the one configure in keycloak.
• The client secret generate by Keycloak during Create a client section.
• identity-uri is used to redirect the user to keycloak.
• frontend-uri will direct you back to the application.

The client secret is the one generate into Keycloak Client Credentials. It must be copy past into client-id variable from application.yaml.

Make sure keycloak and the application are not running on the same port. The application port value can be changed into microprofile-config.properties.

server.port=7987
server.host=localhost

If the port 7987 is already used, check what port is free on your machine.

server.port="{Your-new-port}"

frontend-uri: "http://localhost:{Your-new-port}"

The GreetResource class is a JAX-RS resource available at the endpoint /greet. Use @Authenticated annotation to protect any method or endpoint. Modify the getDefaultMessage method with the @Authenticated to limit its access.

import io.helidon.security.annotations.Authenticated;

    @Authenticated
    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public JsonObject getDefaultMessage() {
        return createResponse("World");
    }

When a client will send an HTTP GET request at the endpoint http://localhost:7987/greet, he will be redirected to keycloak. Keycloak will check if the client has the required authorisation to access this endpoint. If the client can log in successfully, keycloak redirect it to the wished endpoint. If the client cannot log in, or the required access data are incomplete, Keycloak refuses the access.

At this stage of the application, tests cannot pass because of OIDC security. The only way to authenticate a user is through the front end of that server which can be accessed with the browser for example.

In order to keep security and test the application locally, a new security provider must be provided. By adding specific configuration to the test, it is possible to override the application configuration.

The following explains how to set a basic authentication instead of oidc security provider only for the tests. Which means, at the end of this guide, the application will be secured by oidc and the tests will use basic authentication.

In the test folder helidon-quickstart-mp/src/test:

mkdir resources
cd resources
touch application.yaml

Open the application.yaml file you just created.

app:
  greeting: "Hello"

server:
  port: 7987
  host: localhost

security:
  providers:
    - abac:
    - http-basic-auth:
        users:
          - login: "jack"
            password: "jackIsGreat"

By adding this new application.yaml, it will append the properties to the application.yaml located into java/resources. The oidc properties are not overridden, and the server cannot decide which security provider to choose.

Excluding oidc dependency during the test leaves only basic authentication security available for the tests.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <configuration>
        <classpathDependencyExcludes>
            <classpathDependencyExclude>io.helidon.microprofile:helidon-microprofile-oidc</classpathDependencyExclude>
        </classpathDependencyExcludes>
    </configuration>
</plugin>

In the MainTest.java file, tests need to be modified to check the application security when accessing /greet path with a GET method.

First step is to configure the server with the new application.yaml.

import io.helidon.config.Config;

@BeforeAll
    public static void startTheServer() {
        server = Server.builder()
                .config(Config.create())
                .build()
                .start();
        serverUrl = "http://localhost:" + server.port();
    }

The server has now one security provider, basic authentication configured. Next step is to modify the test to check that the application is correctly protected.

JsonObject jsonObject;
Response response = client
        .target(serverUrl)
        .path("/greet")
        .request()
        .get(Response.class);

Assertions.assertEquals(401, response.getStatus());

This piece of code uses the webclient to access the application on /greet path with a GET method. The http basic authentication security provider protects this path, so the client should receive an HTTP 401 code for unauthorized.

Only jack user has access to this part of the application.

String encoding = Base64.getEncoder().encodeToString("jack:jackIsGreat".getBytes());

jsonObject = client
        .target(serverUrl)
        .path("/greet")
        .request()
        .header(Http.Header.AUTHORIZATION, "Basic " + encoding)
        .get(JsonObject.class);

Assertions.assertEquals("Hello World!", jsonObject.getString("message"),
                "default message");

The username and password are encoded and placed inside the header in order to authenticate as jack to access the application. If the authentication is successful, the application send the Hello World back as a JsonObject.

Now, the project can be build without skiping test.

mvn clean install

Keycloak supports many authentication and authorization flows, but only two of them will be shown. This section describes another way you can get an access token or refresh a token or identity token. The identity token contains information about the user. The access token contains access information that the application can use to determine what resources the user is allowed to access. Once expired, the refresh token allows the application to obtain a new access token. As these tokens contain sensitive information, they are valid for a very short period. It is possible to make them last longer in order to let you manipulate them with Postman. To do so:

1. Open the Postman Console.
2. Click on the Realm Setting in the left menu.
3. Navigate to the Tokens tab. You can increase the access token lifespan.

Authorization Code Flow

[{"key":"grant_type","value":"authorization_code"},
{"key":"client_id","value":"myClientID"},
{"key":"client_secret","value":"client secret"},
{"key":"code","value":"authorization code"}]

Resource Owner Password Credentials Grant (Direct Access Grants)

[{"key":"Header Prefix","value":"bearer"},
{"key":"Grant type","value":"Password  Credentials"},
{"key":"Access Token URL","value":"http://localhost:8080/auth/realms/myRealm/protocol/openid-connect/token"},
{"key":"Client ID","value":"myClientID"},
{"key":"Client Secret","value":"client secret"},
{"key":"Username","value":"myuser"},
{"key":"Password","value":"password"},
{"key":"Scope","value":"openid"},
{"key":"Client Authentication","value":"Send as Basic Auth Header"}]

To give less access to a specific endpoint, it is possible to configure user role. So the application will grant access only the user with the required role.

Navigate to the GreetResource and find the getDefaultMessage with @Authenticate annotation.

import javax.annotation.security.RolesAllowed;

@RolesAllowed("admin")

The annotation parameter is the role with access to the method. In this case, only user with admin role can have access.

Then, add a user and roles to the helidon-quickstart-mp/src/test/resources/application.yaml file.

- http-basic-auth:
        users:
          - login: "jack"
            password: "jackIsGreat"
            roles: [ "admin", "user" ]
          - login: "john"
            password: "johnPassword"
            roles: [ "user" ]

Now, only Jack has access to secure endpoint as he has an admin role. Jhon, as a simple user, can not access it. Once it is done, go to the tests to check the application behavior. The test from previous section is still passing because jack has access.

The user john has only the user role so when accessing protected endpoint, a 403 (Forbidden) http code is returned.

encoding = Base64.getEncoder().encodeToString("john:johnPassword".getBytes());

response = client
        .target(serverUrl)
        .path("/greet")
        .request()
        .header(Http.Header.AUTHORIZATION, "Basic " + encoding)
        .get(Response.class);

Assertions.assertEquals(403, response.getStatus());

mvn clean install

The tests pass, and your application is secured with specific roles in addition to user IDs.