To run the sample application included in this chapter, you need to have Node.js (https://nodejs.org/) installed on your workstation.

You also need to have a local copy of the GitHub repository associated with the book. If you have Git installed, you can clone the repository by running this command in a terminal:

$ git clone https://github.com/PacktPublishing/Keycloak---Identity-and-Access-Management-for-Modern-Applications-2nd-Edition.git

Alternatively, you can download a ZIP of the repository from https://github.com/PacktPublishing/Keycloak---Identity-and-Access-Management-for-Modern-Applications-2nd-Edition/archive/main.zip.

Check out the following link to see the Code in Action video:

https://packt.link/oxOr8

The sample application consists of two parts – a frontend web application and a backend REST API.

The frontend web application is a single-page application written in JavaScript. As we want to focus on what Keycloak can offer, the application is very simple. Furthermore, to make it as simple as possible to run the application, it uses Node.js. The application provides the following features:

• Login with Keycloak.
• It displays the user’s name.
• It displays the user’s profile picture, if available.
• It shows the ID token.
• It shows the Access token.
• It refreshes the tokens.
• It invokes the secured endpoint provided by the backend.

The backend REST API is also very simple and is implemented with Node.js. It provides a REST API with two endpoints:

• /public: A publicly available endpoint with no security
• /secured: A secured endpoint requiring an access token with the myrealm global role

Node.js is used for example applications as we want to make the code as easy to understand and as simple to run as possible, regardless of what programming language you are familiar with.

The following diagram shows the relationship between the frontend, the backend, and Keycloak. The frontend authenticates the users using Keycloak and then invokes the backend, which uses Keycloak to verify that the request should be permitted:

Figure 2.1: Application overview

Now that you have a basic understanding of the sample application, let’s look at some more details on how it all comes together.

When the user clicks on the login button in the frontend application, the browser is redirected to the Keycloak login page. The user then authenticates with Keycloak, before the browser is redirected back to the application with a special code called an authorization code. The application then invokes Keycloak to exchange the authorization code for the following tokens:

• An ID token: This provides the application information pertaining to the authenticated user.
• An access token: The application includes this token when making a request to a service, which allows the service to verify whether the request should be permitted.
• A refresh token: Both the ID and the access token have short expirations – by default, 5 minutes. The refresh token is used by the application to obtain new tokens from Keycloak.

The flow described is what is known as the authorization code flow in OpenID Connect. If you are not already familiar with OAuth 2.0 or OpenID Connect, they can be a bit daunting at first, but once you become familiar with them, they are actually quite simple and easy to understand.

To help visualize the login process, a simplified sequence diagram is provided as follows:

Figure 2.2: Authorization code flow in OpenID Connect simplified

The steps in this diagram are as follows:

1. The User clicks on the login button.
2. The application redirects to the Keycloak Login page.
3. The Keycloak login page is displayed to the User.
4. The User fills in the username and password and submits the results to Keycloak.
5. After verifying the username and password, Keycloak sends the Authorization code to the application.
6. The application exchanges the Authorization code for an ID token and an access token. The application can now verify the identity of the user by inspecting the ID token.

The next step related to Keycloak is when the frontend invokes the backend. The backend REST API has a protected endpoint that can only be invoked by a user with the global role, myrole.

To be completely accurate, the frontend is granted permissions to invoke the backend on behalf of the user. This is part of the beauty of OAuth 2.0. An application does not have access to do everything that the user is able to do, only what it should be able to do.

When the frontend makes a request to the backend, it includes the access token within the request. By default, Keycloak uses JSON Web Signature (JWS) as the token format. These types of tokens are often referred to as non-opaque tokens, meaning the contents of the token are directly visible to the application.

The token also includes a digital signature, making it possible to verify that the token was indeed issued by Keycloak. In essence, this means that the backend can both verify the token and read the contents without a request to Keycloak, resulting in less demand on the Keycloak server and lower latency when processing requests to the backend.

To help visualize what happens when the frontend sends a request to the backend, take a look at the following diagram:

Figure 2.3: Secured request from the frontend to the backend simplified

The steps in the diagram are as follows:

1. The Backend retrieves Keycloak’s public keys. The Backend does not need to do this for all requests to the Backend, but can instead cache the keys in memory.
2. The Frontend sends a request to the Backend, including the access token.
3. The Backend uses the public keys it retrieved earlier to verify that the access token was issued by a trusted Keycloak instance, and then verifies that the token is valid and that the token contains the role myrole.
4. The Backend returns the results to the Frontend.

You now have a basic understanding of how the sample applications are secured with Keycloak. In the next section, you will learn how to run the sample application.

In this section, you will learn how to run the sample application.

If you don’t already have Node.js installed on your workstation, go to https://nodejs.org/ for instructions on how to install it.

To run the frontend on Node.js, open a terminal and run the following commands:

$ cd Keycloak---Identity-and-Access-Management-for-Modern-Applications-2nd-Edition/ch2/frontend/
$ npm install
$ npm start

Next, open a new terminal to run the backend using the following commands:

$ cd Keycloak---Identity-and-Access-Management-for-Modern-Applications-2nd-Edition/ch2/backend/
$ npm install
$ npm start

Now that you have the sample application running with Node.js, you can register it with Keycloak, which we will cover in the next section.

In the previous chapter, covering how to get started with Keycloak, you learned how to run Keycloak, as well as how to create your first realm. Prior to continuing this section, you should have Keycloak running with the realm created, as covered in the previous chapter. In summary, what you require before continuing is the following:

• Keycloak up and running
• A realm named myrealm
• A global role named myrole
• A user with the preceding role

Before an application can log in with Keycloak, it has to be registered as a client with Keycloak.

Before registering the frontend, let’s see what happens if an unregistered application tries to authenticate with Keycloak. Open http://localhost:8000 and then click on the Login button.

You will see an error page from Keycloak with the message Client not found. This error is telling you that the application is not registered with Keycloak.

To register the frontend with Keycloak, open the Keycloak admin console. At the top of the menu on the left-hand side, there is an option to select what realm you are working with. Make sure you have selected the realm named myrealm. In the menu on the left-hand side, click on Clients, and then click on Create client.

Fill in the form with the following values:

• Client ID: myclient

After filling in the Client ID field, click on Next. On the following screen, it is possible to enable and disable various capabilities required by an application. For now, you can simply ignore this step and click on Save.

Before the client can be used by the frontend application to authenticate with Keycloak, you have to register the URL for the application. Under Access settings, fill in the following values:

• Valid redirect URIs: http://localhost:8000/
• Valid post redirect URIs: http://localhost:8000/
• Web origins: http://localhost:8000

Once you have filled in the form, click on Save. Before we continue to try to log in with the frontend application, let’s look a bit more at what the last configuration values you entered mean:

• Valid redirect URIs: This value is very important in an OpenID Connect authorization code flow when a client-side application is used. A client-side application is not able to have any credentials as they would be visible to end users of the application. To prevent any malicious applications from being able to masquerade as the real application, the valid redirect URIs instruct Keycloak to only redirect the user to a URL that matches a valid redirect URI. In this case, since the value is set to http://localhost:8000/, an application hosted on http://attacker.com would not be able to authenticate.
• Valid post redirect URIs: This is the same as the previous value, but for logout requests rather than login requests, as it is fairly common for an application to have different redirect URIs for login and logout. Keycloak supports adding a special post redirect URI with the value +, which results in permitting all valid redirect URIs as post redirect URIs.
• Web origins: This option registers the valid web origins of the application for Cross-Origin Resource Sharing (CORS) requests. To obtain tokens from Keycloak, the frontend application has to send an AJAX request to Keycloak, and browsers do not permit an AJAX request from one web origin to another, unless CORS is used. Keycloak supports adding a special web origin with the value +, which results in permitting all valid redirect URIs as web origins.

The following screenshot shows the created client in the Keycloak admin console.

Figure 2.4: Client settings in the admin console

Now you can go back to the frontend by opening http://localhost:8000. This time, when you click on the Login button, you will see the Keycloak login page. Log in with the username and password you created during the previous chapter.

Let’s take a look at the ID token that Keycloak issued. Click on the Show ID Token button. The ID token that is displayed will look something like the following:

{
  "exp": 1664300152,
  "iat": 1664299852,
  "auth_time": 1664298915,
  "jti": "21bb9f32-98ce-49aa-896d-796cb716be59",
  "iss": "http://localhost:8080/realms/myrealm",
  "aud": "myclient",
  "sub": "eb14ea82-45e2-4413-8997-129fd0fc865b",
  "typ": "ID",
  "azp": "myclient",
  "nonce": "ccf5f374-aa07-4280-b63a-efdba9c355c9",
  "session_state": "22884115-55cb-4285-ba92-26c4bf74f74b",
  "at_hash": "ngdMORpXQcEQJ6d9s3uHvw",
  "acr": "0",
  "sid": "22884115-55cb-4285-ba92-26c4bf74f74b",
  "email_verified": true,
  "name": "Stian Thorgersen",
  "preferred_username": "st",
  "given_name": "Stian",
  "family_name": "Thorgersen",
  "email": "[email protected]"
}}

Here is a list of some of the more interesting values within the ID token:

• exp: This is the date and time the token expires in seconds since 01/01/1970 00:00:00 UTC (often referred to as Unix or Epoch time).
• iss: This is the issuer of the token, which you may notice is the URL of the Keycloak realm.
• sub: This is the unique identifier of the authenticated user.
• name: This is the first name and last name of the authenticated user.
• preferred_username: This is the username of the authenticated user. You should avoid this as a key for the user as it may be changed, and may even refer to a different user in the future. Instead, always use the sub field for the user key.

The ID token is used by the application to establish the identity of the authenticated user.

Next, let’s take a look at the access token. Click on the Show Access Token button. Let’s also take a look at some fields in this token:

• allowed-origins: This is a list of permitted web origins for the application. The backend service can use this field when deciding whether web origins should be permitted for CORS requests.
• realm_access: This contains a list of global realm roles. It is the intersection between the roles granted to the user, and the roles the client has access to.
• resource_access: This contains a list of client roles.
• scope: Scopes can be used both to decide what fields (or claims) to include in the token and by backends to decide what APIs the token can access.

Currently, the information within the tokens is the default fields available in Keycloak. If you want to add additional information, Keycloak is very flexible in allowing you to customize the content within the tokens.

Let’s give this a go by adding a picture for the user. Leave the tab with the frontend open, and then open a new tab with the Keycloak admin console. In the menu on the left-hand side, click on Users, and select the user you created previously. Now let’s add a custom attribute to the user. Click on Attributes. In the table, there will be two empty input fields at the bottom. In the Key column, set the value to picture, and in the Value column, set the value to the URL of a profile picture (in the following screenshot, I’ve used my GitHub avatar). Then, click on Save.

:

Figure 2.5: Adding a custom attribute to a user

Now, go back to the tab where you have the frontend open. To display the profile picture, you can click on the Refresh button. When you click on this button, the tokens will be refreshed, and the new ID token will now contain the picture attribute you just added, which allows the application to display a profile picture for the user.

Next, you will learn how to securely invoke the backend from the frontend.

Now, open http://localhost:3000/ and click on the Public endpoint link. You will see a message saying Public message!. The public endpoint is not secured by Keycloak and can be invoked without an access token.

Next, let’s try the secured endpoint that is protected by Keycloak. Open http://localhost:3000/ again. This time, click on the Secured endpoint link. Now you will see a message saying Access denied. This request is not permitted since it requires a valid access token to invoke the endpoint.

Let’s now try to invoke the secured endpoint from the frontend. Open http://localhost:8000/ and click on Invoke Service. You will now see a message displayed saying Secret message!. If instead you get the message Access Denied, this is most likely caused by the user not having the myrole role.

When you click Invoke Service, the frontend sends an AJAX request to the backend service, including the access token in the request, which allows the backend to verify that the invocation is done on behalf of a user who has the required role to access the endpoint.

In this chapter, you learned how to secure your first application, consisting of a frontend web application and a backend REST API with Keycloak. You also gained a basic understanding of how Keycloak leverages OpenID Connect to make this all happen in a standard and secure way. Together with what you learned in the first chapter of the book, you now have a solid foundation to start learning more about Keycloak.

In the next chapter, we will dive deeper into securing applications with Keycloak, giving you a better understanding of how it all works.

1. How does an application authenticate with Keycloak?
2. What do you need to configure in the Keycloak admin console in order to allow an application to authenticate with Keycloak?
3. How does an application securely invoke a protected backend service?

Join our community on Discord

Join our community’s Discord space for discussions with the authors and other readers:

https://packt.link/SecNet