Concise Keycloak Realm for Testing

I’ve recently been working on some Quarkus and Angular projects requiring an OIDC provider and I have been using Keycloak. Keycloak is a great implementation for SSO/OAUTH/OIDC for your production applications but it can sometimes be unwieldy for those of us who do not fully grasp every feature or detail as it relates to setting up a Keycloak realm for testing.

In Keycloak, a realm is a deployment or security domain where you manage, organize, and configure identity and access management components. Realms are a way to isolate different applications and their user bases from each other within the Keycloak server.

Here are some key points about Keycloak realms:

1. Isolation: Realms provide a way to isolate different applications and their user bases. Each realm has its own set of users, roles, groups, and configuration settings.
2. Authentication Configuration: Realms allow you to configure authentication settings for the applications within that realm. This includes specifying identity providers, setting up multi-factor authentication, and defining authentication flows.
3. User Management: In a realm, you can define and manage users, roles, and groups. Users within a realm have specific roles and permissions that determine what they can access and do within the applications associated with that realm.
4. Client Applications: Each realm can have multiple client applications. A client in Keycloak represents a web application, mobile app, or service that wants to use Keycloak for authentication and authorization. Clients within a realm can share user accounts and roles.
5. Security Configuration: Realms allow you to configure various security-related settings, such as password policies, session timeouts, and more.
6. Authorization Policies: You can define authorization policies within a realm to control access to specific resources or functionalities based on user roles and permissions.

When you set up a new application or service in Keycloak, you typically create a new realm for it. This way, you can manage the identity and access control for that application independently of other applications. Realms provide a logical separation and organization of security configurations within the Keycloak server.

Testing Realm

Many tutorials out on the interwebs describe the process of creating a test realm by starting a Keycloak server and then manually going through the GUI to create the items. Once the realm is created and configured correctly, then the realm can be exported as a json file. Unfortunately, when Keycloak does this, the realm json does not export a delta change set for the items that are different than the defaults, but rather the entire realm and every setting imaginable. For production configurations, this is nice as it leaves no doubt as to the settings but for simple testing realms, it’s way too much. When you see this in action, you will see what I am talking about.

However, the reasonable defaults do show up if you don’t provide the values in a scaled down json structure. So as part of the testing effort, I spent quite a bit of time to ensure everything works for the testing scope but would stay as minimal as possible in terms of the absolute requirements. Here’s the minimum json setup that I am currently using for some local testing environments.

{
  "realm": "rhenergy-public",
  "enabled": true,
  "clients": [
    {
      "clientId": "rhenergy-public-api",
      "publicClient": true,
      "clientAuthenticatorType": "client-secret",
      "secret": "rhenergy-public-api-secret",
      "directAccessGrantsEnabled": true,
      "redirectUris": [
        "*"
      ],
      "webOrigins": [
        "*"
      ],
      "attributes": {
        "post.logout.redirect.uris": "*"
      }
    }
  ],
  "users": [
    {
      "username": "carl.customer@gmail.com",
      "enabled": true,
      "credentials": [
        {
          "type": "password",
          "value": "Pass123!"
        }
      ],
      "realmRoles": [
        "customer"
      ],
      "clientRoles": {
        "account": [
          "view-profile"
        ],
        "rhenergy-public-api": [
          "customer"
        ]
      }
    }
  ]
}

Notes by line

• 36: If you want access to the user profile, you need to add access to the account client’s view-profile role.