Keycloak Basics

Keycloak is an open-source Identity and Access Management (IAM) solution. It provides authentication, authorization, and user management for modern applications. Below are the basic concepts for Keycloak.

Key Concepts

All following concepts can be realized in the Keycloak admin interface.

Realm

A Realm is an isolated space within Keycloak where you manage a set of users, credentials, roles, and groups. Realms allow you to manage different users for different applications. Keycloak comes with a default realm called Master, which is intended for administrative purposes. We use a realm called PermaplanT to manage all PermaplanT users.

Client

A Client is an entity that can request authentication from Keycloak. Clients are typically applications (e.g., web apps, mobile apps, APIs) that rely on Keycloak for authentication.

We have a client that allows us to get users for each PermaplanT instance:

  • localhost: users for localhost PermaplanT
  • PermaplanT-MR: users for mr.permaplant.net
  • PermaplanT-Dev: users for dev.permaplant.net
  • PermaplanT-Master: users for master.permaplant.net
  • PermaplanT-Prod: users for www.permaplant.net
  • permaplant-cloud: users for our Nextcloud

The backend communicates with Nextcloud by using the tokens from the PermaplanT-(MR|Dev|Master|Prod) clients. The client permaplant-cloud is currently not used for this communication and some problems of this are described in Keycloak User Tokens with Nextcloud user_oidc.

User

A User is a person who can log into a client managed by Keycloak. Users can be created manually in the Keycloak Admin UI.

User Groups

Users can be part of groups, with different permissions. For PermaplanT we have the following groups:

  • Testing: full access to all the testing maps (SUT_*).
  • Developer: full access to the maps created via CI (maps/1, 1000 plantings etc.).
  • Member/Regular Member: full access to their associated maps.
  • Member/Contributing Member: full access to their associated maps.
  • Member/Supporting Member: full access to their associated maps.
  • Admin: full access to all the maps, regardless of permissions.

Users without a group have read only access to maps, and can't view plants.

Role

Roles define the permissions that a user or group has. You can assign roles at both the realm level (global roles) and the client level (specific to a particular application).

We are not using any roles at the moment.

Keycloak Authentication Workflow

We use Keycloak for an authentication process with bearer tokens.

This is described in more detail in the backend documentation.

Getting user token as User

The tokens are JWT tokens.

To receive a token as a user an API request to Keycloak has to be made.

  • client_id: id of Client we want to get the access token from
  • client_secret: password of Client we want to get the access token from
  • username: username of User we want to get access token for
  • password: password of User we want to get access token for
curl --location 'https://auth.permaplant.net/realms/PermaplanT/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'client_id=localhost' \
--data-urlencode 'client_secret=EXAMPLE_CLIENT_SECRET' \
--data-urlencode 'username=filip' \
--data-urlencode 'password=EXAMPLE_PASSWORD'

The returned access token can be used to make requests to PermaplanT and Nextcloud, by setting Authorization: Bearer <returned_access_token> in the header.

Keycloak User Tokens with Nextcloud user_oidc

Since a new update, the Nextcloud plugin user_oidc expects two extra fields when checking the JWT token.

The fields are:

  • azp (Authorized Party): The Keycloak client that provided the token
  • aud (Audience): The audience the token is meant for

If we access e.g. www.permaplant.net we get the token PermaplanT-Prod and with it access Nextcloud, which expects a token from permaplant-cloud. In this case azp is wrong and aud is not set at all by default by Keycloak.

Possibilities to solve this are:

  1. Use one single Keycloak PermaplanT Client for all tokens and set aud with an extra setting for all Clients in the token
  2. Disable azp and aud checking for the tokens
  3. Mixture of both solutions

We decided for the moment for solution 2. This solution is still secure, since users need to still authenticate with their password.

Nextcloud integration

The documentation about which images on Nextcloud need token identification is found in ./nextcloud_integration.md.