Fixing 400 Bad Request in Quarkus Keycloak Admin Client When Using Declarative User Profile

If you’ve been integrating Keycloak with your Quarkus application, chances are you’ve encountered a mysterious 400 Bad Request error when using Declarative User Profiles with the Quarkus Keycloak Admin Client. This can be frustrating, especially if everything else seems correctly configured and functional.

Resolving this issue isn’t just about fixing an annoyance—it’s crucial for ensuring your application’s identity and access management remains seamless. A stable integration between Keycloak and Quarkus ensures effective user management, robust security, and a smooth user experience.

Let’s go step by step to see what’s happening, troubleshoot the problem, and get your 400 Bad Request issue resolved.

Setting Up Keycloak Dev Service Integration in a Quarkus App

First, let’s make sure your setup is on point. To integrate Quarkus with Keycloak’s development services, you need the right dependencies.

1. In your Quarkus project’s pom.xml, add these necessary dependencies:

<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-oidc</artifactId>
</dependency>
<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-keycloak-admin-client-reactive</artifactId>
</dependency>

• The quarkus-oidc dependency provides OpenID Connect integration for user authentication.
• The admin-client-reactive allows programmatic interaction with Keycloak to perform admin tasks.

Next, configure your application.properties to enable Keycloak dev services for local testing:

quarkus.keycloak.devservices.enabled=true
quarkus.keycloak.devservices.realm-path=quarkus-realm.json

The quarkus-realm.json sets the realm, users, and clients. Here’s a minimal working example:

{
  "realm": "quarkus",
  "enabled": true,
  "clients": [{
    "clientId": "frontend",
    "enabled": true,
    "publicClient": true
  }],
  "users": [{
    "username": "testuser",
    "enabled": true,
    "credentials": [{
      "type": "password",
      "value": "testpass"
    }]
  }]
}

Working Functionality and the Problem with Managed Attributes

When you initially integrate Quarkus and Keycloak, you’ll find that user login, authorization, and API access via Keycloak Admin Client usually work without issues. But once you introduce managed attributes by enabling Declarative User Profile, you might start witnessing unexpected 400 Bad Request errors.

The real trouble starts when you’re trying to add additional attributes or metadata to user profiles via the Keycloak Admin API—through the Quarkus admin client. Suddenly, responses from the admin client API become unpredictable. What exactly is happening under the hood?

Understanding the Root Cause of the Bad Request Error

Keycloak uses a declarative approach to user profiles to enforce schema rules and validations. When you activate managed attributes declaratively, Keycloak enforces strict validations on profiles at runtime.

Commonly, this error arises when the payload in your API call doesn’t align exactly with the defined user profile schema. Even minor mismatches—like missing attribute definitions, unknown attributes, data format mismatches, or attribute conflicts—can lead to the ambiguous “400 Bad Request” response.

Troubleshooting the 400 Bad Request

To pinpoint the Root cause, follow these troubleshooting steps:

• Check the request details: Review the API request payload carefully from your Quarkus app.
• Inspect Keycloak logs: Keycloak provides detailed server logs usually available at keycloak.log. Activate debug logging if required, to see detailed error reasons. Logs often reveal specific attribute or validation errors.
• Trace HTTP traffic: Consider tools like Wireshark or simple logging interceptors to see exactly what’s sent and received.

Analyze logs carefully. Typically, you’ll discover something like: “invalid attribute value”, “Undefined attribute”, or similar clues that narrow down your issue.

Resolving the Issue Once and for All

After diagnosing the exact issue, resolve it by ensuring your declarative user profile schema matches the attributes you’re managing through the admin client. Make sure:

• Every attribute added via the admin client is properly enabled in the Keycloak Declarative User Profile configuration.
• Required attributes are clearly defined with appropriate validations, and optional attributes don’t conflict.

For example, if your admin client sends attributes like “department” or “subscription-level”, you should explicitly define these attributes in the Keycloak User Profile config:

{
  "attributes": [
    {
      "name": "department",
      "type": "string",
      "required": { "roles": ["user"] },
      "permissions": {
        "view": ["admin", "user"],
        "edit": ["admin"]
      }
    }
  ]
}

This approach eliminates 400 Bad Request issues by validating attributes against a known schema explicitly defined within Keycloak.

Implementing Predefined Attributes in quarkus-realm.json

A better long-term solution is to define your required user attributes right from the start in your quarkus-realm.json file. Predefined attributes provide clarity and enforce standards consistently across your teams.

Here’s a structured approach:

1. Clearly define attributes and standards in your realm file.
2. Distribute clear documentation or schema definitions among team members to maintain consistency.
3. Monitor schema evolution, ensuring all changes are synchronized smoothly.

A sample snippet might look like this:

"users": [{
  "username": "testuser",
  "enabled": true,
  "attributes": {
    "department": ["Engineering"],
    "subscription-level": ["premium"]
  },
  "credentials": [{"type": "password", "value": "password"}]
}]

Optimizing Keycloak and Quarkus Integration

The synergy between Keycloak and Quarkus becomes powerful when configured seamlessly. Always:

• Proactively define all user attributes declaratively.
• Validate payloads thoroughly to avoid runtime surprises.
• Regularly update and refine your integration based on real-world use and testing.

Quarkus and Keycloak offer powerful features, and clear attribute management leverages these effectively, ensuring your identity management workflows scale smoothly.

Have you faced other issues integrating Quarkus and Keycloak or is there an insightful strategy you’ve employed? Let’s discuss and share experiences.