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

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.security.providers</groupId>
    <artifactId>helidon-security-providers-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:
      client-id: "myClientID" 
      client-secret: "Client secret generated into Keycloak client credential" 
      identity-uri: "http://localhost:8080/auth/realms/myRealm" 
      audience: "account"
      header-use: "true"
      # proxy-host should be defined if you operate behind a proxy, can be removed otherwise
      proxy-host: ""
      frontend-uri: "http://localhost:7987" 
      server-type: "oidc"
  web-server:
    # protected paths on the web server
    paths:  
      - path: "/greet"
        methods: ["get"]
        authenticate: true

• 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.
• paths section defines the protected application’s path.

Make sure keycloak and the application are not running on the same port. The application port value can be changed into application.yaml.

server:
  port: 7987
  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}"

Once the properties are added, the web server must be set up. The Main.createRouting method gather all configuration properties.

import io.helidon.security.Security;
import io.helidon.security.integration.webserver.WebSecurity;
import io.helidon.security.providers.oidc.OidcSupport;
...
Security security = Security.create(config.get("security"));    

return Routing.builder()
                .register(WebSecurity.create(security, config.get("security"))) 
                .register(OidcSupport.create(config))   
                ...

• Create the Helidon Security instance using configuration.
• Register Helidon WebSecurity instance using security instance and configuration.
• Register Helidon OidcSupport instance.

That code is extracting security properties from application.yaml into two steps. First the Security instance is used to bootstrap security, so the WebSecurity instance can integrate security into Web Server. Then, OidcSupport instance registers the endpoint to which OIDC redirects browser after a successful login.

Helidon sample is now set up and ready.

The Authorization Code flow is suitable for browser-based applications. It is composed of three main steps:

1. The browser visits the application. The user is not logged in, so it redirects the browser to Keycloak which requires username and password for authentication.
2. Keycloak authenticates the user and returns a temporary authorization code as a query parameter in the URL.
3. The authorization code is used to get access and refresh token from Keycloak token endpoint.

For the first step, paste the following URL into your browser: http://localhost:8080/auth/realms/myRealm/protocol/openid-connect/auth?client_id=myClientID&response_type=code. The first part of the url http:/../auth is the Keycloak endpoint to request an authorization code. Two query parameters are provided, the client id and the response type. Press enter and Keycloak responds with different URL containing a query parameter code. You successfully received the authorization code.

In order to achieve the third step, we can use Postman to exchange the authorization code for tokens. In Postman, select the Http POST method. Keycloak endpoint to get token is the following: http://localhost:8080/auth/realms/myRealm/protocol/openid-connect/token. In the body of the request, select x-www-form-urlencoded type. Add the following data:

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

Do not forget to replace the client secret by its value (generated during Create a Client), and authorization code by the code value in the query parameter. Send the request by pressing Send. Keycloak returns an access token and a refresh token.

The Direct Access Grants flow is used by REST clients that want to request tokens on behalf of a user. To use Postman to make this request on behalf of myuser, select the GET method and enter this URL: http://localhost:7987/greet/. Under Authorization tab, select authorization type`OAuth 2.0`. Under it, complete the sentence Add authorization data to with Request Headers, and complete the required fields.

[{"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"}]

Again, make sure to replace client secret by the actual client secret. Click on Get New Access Token. A popup window appears with Authentication complete, click on proceed to display access, refresh and identity token. Copy and paste the access token to Access Token field and press Send. Helidon greeting application sends back Hello World !.

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 set up. By adding specific configuration to the tests, 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 security provider, and the tests will use basic authentication.

<dependency>
    <groupId>io.helidon.security.providers</groupId>
    <artifactId>helidon-security-providers-http-auth</artifactId>
    <scope>test</scope>
</dependency>

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

mkdir resources
cd resources
touch application.yaml

Open the application.yaml file

app:
  greeting: "Hello"

server:
  port: 7987
  host: localhost

security:
  providers:
    - abac:
      # Adds ABAC Provider - it does not require any configuration
    - http-basic-auth:
        users:
          - login: "jack"
            password: "jackIsGreat"
    - oidc:
        client-id: "Your client ID"  
        client-secret: "Your client secret" 
        identity-uri: "http://localhost:8080/auth/realms/myRealm"
        audience: "account"
        frontend-uri: "http://localhost:7987"
        server-type: "oidc"
  web-server:
    # protected paths on the web server - do not include paths served by Jersey, as those are protected directly
    paths:
      - path: "/greet"
        methods: ["get"]
        authenticate: true

• Replace this field by your Keycloak client ID.
• Replace this field by your Keycloak client Password.

Add the http-basic-auth properties in the security → providers property section. This configuration will be used by the tests instead of the java/resources/application.yaml.

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

import java.util.Base64;
import io.helidon.common.http.Http;

webClient.get()
                .path("/greet")
                .request()
                .thenAccept(response -> Assertions.assertEquals(401,response.status().code()))
                .toCompletableFuture()
                .get();

This piece of code uses the webclient to access the application on /greet path with a GET method. The http basic authentication security 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.

webClient.get()
                .path("/greet")
                .headers(headers ->  {
                    String encoding = Base64.getEncoder().encodeToString("jack:jackIsGreat".getBytes());
                    headers.add(Http.Header.AUTHORIZATION, "Basic " + encoding);
                    return headers;
                })
                .request(JsonObject.class)
                .thenAccept(jsonObject -> Assertions.assertEquals("Hello World!", jsonObject.getString("message")))
                .toCompletableFuture()
                .get();

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 skipping test.

mvn clean install

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

Add a user and roles to the helidon-quickstart-se/src/test/resources/application.yaml.

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

Into the web-server section, the roles-allowed parameter defines which roles have access to the protected path and method.

web-server:
    # protected paths on the web server - do not include paths served by Jersey, as those are protected directly
    paths:
      - path: "/greet"
        methods: ["get"]
        roles-allowed: "admin"
        authenticate: true

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 as jack has access.

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

webClient.get()
                .path("/greet")
                .headers(headers ->  {
                    String encoding = Base64.getEncoder().encodeToString("john:johnPassword".getBytes());
                    headers.add(Http.Header.AUTHORIZATION,"Basic " + encoding);
                    return headers;
                })
                .request()
                .thenAccept(response -> Assertions.assertEquals(403, response.status().code()))
                .toCompletableFuture()
                .get();

mvn clean install

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