Repository navigation
Conversation
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
JAX-RS 409 exceptions receive an inconsistent problem type, and paths containing matrix parameters can incorrectly fall back to legacy error responses.
2 open issues
What changed in this PR
Introduces RFC 9457 Problem Details for Admin API v2, addressing #50671 by giving clients a consistent error format and stable problem identifiers.
Changes:
- Adds centralized error formatting, structured validation violations, and problem-type mappings.
- Updates the admin CLI, OpenAPI schema, and documentation for the new format.
- Adds error-response tests and migrates existing validation and authorization assertions.
| File | Description |
|---|---|
| services/src/main/java/org/keycloak/services/error/KeycloakErrorHandler.java | Routes v2 errors to the optional formatter. |
| services/src/main/java/org/keycloak/services/error/AdminApiV2ErrorFormatter.java | Defines the formatter interface. |
| rest/admin-v2/tests/src/test/java/org/keycloak/tests/admin/client/v2/validation/PutClientValidationTest.java | Checks structured PUT errors and UUID conflicts. |
| rest/admin-v2/tests/src/test/java/org/keycloak/tests/admin/client/v2/validation/PostClientValidationTest.java | Checks structured POST validation errors. |
| rest/admin-v2/tests/src/test/java/org/keycloak/tests/admin/client/v2/validation/PatchClientValidationTest.java | Checks validation and invalid-patch problem types. |
| rest/admin-v2/tests/src/test/java/org/keycloak/tests/admin/client/v2/validation/AbstractClientValidationTest.java | Adds violation matchers and updates shared assertions. |
| rest/admin-v2/tests/src/test/java/org/keycloak/tests/admin/client/v2/ClientApiV2Test.java | Migrates client API error assertions. |
| rest/admin-v2/tests/src/test/java/org/keycloak/tests/admin/client/v2/ClientApiV2ErrorResponsesTest.java | Adds HTTP error-format integration coverage. |
| rest/admin-v2/tests/src/test/java/org/keycloak/tests/admin/client/v2/ClientApiV2AuthorizationTest.java | Verifies forbidden problem responses. |
| rest/admin-v2/tests/src/test/java/org/keycloak/tests/admin/cli/v2/KcAdmV2ClientCLITest.java | Adjusts CLI authentication-error expectations. |
| rest/admin-v2/services/src/test/java/org/keycloak/services/error/ProblemDetailErrorFormatterTest.java | Tests classification, serialization, and message protection. |
| rest/admin-v2/services/src/test/java/org/keycloak/rest/admin/api/client/DefaultClientsApiTest.java | Updates sort-validation exception expectations. |
| rest/admin-v2/services/src/main/resources/META-INF/services/org.keycloak.services.error.AdminApiV2ErrorFormatter | Registers the formatter through ServiceLoader. |
| rest/admin-v2/services/src/main/java/org/keycloak/services/ServiceExceptionMapper.java | Removes the legacy service-exception mapper. |
| rest/admin-v2/services/src/main/java/org/keycloak/services/ServiceException.java | Carries problem types and structured violations. |
| rest/admin-v2/services/src/main/java/org/keycloak/services/error/ViolationExceptionResponse.java | Removes the previous validation-response model. |
| rest/admin-v2/services/src/main/java/org/keycloak/services/error/ValidationExceptionHandler.java | Delegates validation errors to centralized handling. |
| rest/admin-v2/services/src/main/java/org/keycloak/services/error/ProblemDetailErrorFormatter.java | Classifies and serializes problem responses. |
| rest/admin-v2/services/src/main/java/org/keycloak/services/client/scim/OIDCClientModelSchema.java | Handles null web origins during model mapping. |
| rest/admin-v2/services/src/main/java/org/keycloak/services/client/scim/ClientResourceTypeProvider.java | Converts service failures into typed problems. |
| rest/admin-v2/services/src/main/java/org/keycloak/services/client/scim/BaseClientModelSchema.java | Handles null redirect URIs during model mapping. |
| rest/admin-v2/services/src/main/java/org/keycloak/rest/admin/api/DefaultAdminRootV2.java | Reports the disabled API with a dedicated problem type. |
| rest/admin-v2/services/src/main/java/org/keycloak/rest/admin/api/DefaultAdminApi.java | Reports missing realms through ServiceException. |
| rest/admin-v2/services/src/main/java/org/keycloak/rest/admin/api/client/DefaultClientsApi.java | Standardizes list and creation errors. |
| rest/admin-v2/services/src/main/java/org/keycloak/rest/admin/api/client/DefaultClientApi.java | Standardizes individual-client operation errors. |
| rest/admin-v2/services/src/main/java/org/keycloak/admin/internal/openapi/OASModelFilter.java | Adds problem schemas and error responses to OpenAPI. |
| rest/admin-v2/services/pom.xml | Adds RESTEasy support for response-building unit tests. |
| rest/admin-v2/api/src/main/java/org/keycloak/services/error/ProblemType.java | Defines stable problem identifiers and statuses. |
| rest/admin-v2/api/src/main/java/org/keycloak/services/error/ProblemDetail.java | Defines the shared problem and violation models. |
| js/libs/keycloak-admin-client/openapi.json | Updates the generated API error contract. |
| integration/client-cli/admin-cli/src/main/java/org/keycloak/client/cli/util/HeadersBodyStatus.java | Displays problem details and structured violations. |
| docs/guides/admin-api/admin-api-v2.adoc | Documents the error format and problem catalogue. |
| docs/documentation/upgrading/topics/changes/changes-27_0_0.adoc | Explains error-format and conflict-status migration changes. |
Review effort: Balanced
Unreported flaky test detectedIf the flaky tests below are affected by the changes, please review and update the changes accordingly. Otherwise, a maintainer should report the flaky tests prior to merging the PR. org.keycloak.testsuite.model.infinispan.EmbeddedInfinispanSplitBrainTest#testRevokedTokensReloadedOnMergeEventKeycloak CI - Store Model Tests |
Closes: keycloak#50671 Signed-off-by: Steve Hawkins <shawkins@redhat.com>
Comment on lines
+58
to
+60
| Response.ResponseBuilder response = Response.status(problem.status()) | ||
| .type(ProblemDetail.MEDIA_TYPE) | ||
| .entity(body); |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes: #50671
Standardizes all error responses from Admin API v2 (
/admin/api/**) on the RFC 9457 Problem Details specification (application/problem+json), replacing previously inconsistent error shapes (OAuth 2.0 error JSON, plain string messages, and HTML error pages).Given the increasing usage of RFC 9457 within the quarkus ecosystem, that seems to be a good choice. But we can of course consider using scim or oauth style.
URNs in the
urn:keycloak:admin-api:v2:problem:namespace are used for thetypeURI reference rather than HTTP URLs (about:blankor hosted URLs) to provide stable, unambiguous, and self-contained identifiers scoped directly to Keycloak Admin API v2 without requiring dedicated external hosting or documentation infrastructure. Clients can reliably branch on thetypeURN rather than parsing human-readable error messages. Please review the types for granularity and if URLs would be preferred instead.