Skip to content

enhance: standardize v2 error reporting on RFC 9457 - #55251

Draft
shawkins wants to merge 1 commit into
keycloak:mainfrom
shawkins:iss50671
Draft

shawkins wants to merge 1 commit into
keycloak:mainfrom
shawkins:iss50671

Conversation

@shawkins

@shawkins shawkins commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

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 the type URI reference rather than HTTP URLs (about:blank or 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 the type URN rather than parsing human-readable error messages. Please review the types for granularity and if URLs would be preferred instead.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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

@keycloak-github-bot keycloak-github-bot Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unreported flaky test detected, please review

@keycloak-github-bot

Copy link
Copy Markdown

Unreported flaky test detected

If 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#testRevokedTokensReloadedOnMergeEvent

Keycloak CI - Store Model Tests

java.lang.AssertionError: Execution didn't complete: java.lang.RuntimeException: org.awaitility.core.ConditionTimeoutException: Condition with alias 'Persisted revocation was not restored after the view merge' didn't complete within 30 seconds because condition with Lambda expression in org.keycloak.testsuite.model.infinispan.EmbeddedInfinispanSplitBrainTest was not fulfilled.
	at org.junit.Assert.fail(Assert.java:89)
	at org.keycloak.testsuite.model.KeycloakModelTest.inIndependentFactories(KeycloakModelTest.java:448)
	at org.keycloak.testsuite.model.infinispan.EmbeddedInfinispanSplitBrainTest.testRevokedTokensReloadedOnMergeEvent(EmbeddedInfinispanSplitBrainTest.java:125)

Report flaky test

Closes: keycloak#50671

Signed-off-by: Steve Hawkins <shawkins@redhat.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Rebuilding the error response discards the Allow header from NotAllowedException, producing 405 responses without the method list required by RFC 9110.

1 open issue
2 resolved since last review

Review effort: Balanced

Comment on lines +58 to +60
Response.ResponseBuilder response = Response.status(problem.status())
.type(ProblemDetail.MEDIA_TYPE)
.entity(body);
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Define error response handling for admin api v2

2 participants