Introduce 419 AuthenticationTimeoutResponse instead of using 401 UnauthorizedResponse on token expiration

[sungwy]

Describe the bug

Iceberg clients rely on the distinction between status code values to refresh the token when AuthenticationTimeoutResponse is issued for expired tokens.

Currently, polaris returns a 401 UnauthorizedResponse which isn't conformant to the REST Catalog Spec.

polaris/integration-tests/src/main/java/org/apache/polaris/service/it/test/PolarisManagementServiceIntegrationTest.java

Lines 1993 to 2011 in 49a93f8

	public void testTokenExpiry() {
	// TokenExpiredException - if the token has expired.
	String newToken =
	defaultJwt()
	.withExpiresAt(Instant.now().plus(1, ChronoUnit.SECONDS))
	.sign(Algorithm.HMAC256("polaris"));
	Awaitility.await("expected list of records should be produced")
	.atMost(Duration.ofSeconds(20))
	.pollDelay(Duration.ofSeconds(1))
	.pollInterval(Duration.ofSeconds(1))
	.untilAsserted(
	() -> {
	try (Response response =
	client.managementApi(newToken).request("v1/principals").get()) {
	assertThat(response)
	.returns(Response.Status.UNAUTHORIZED.getStatusCode(), Response::getStatus);
	}
	});
	}

To Reproduce

Use an expired token to make a request against polaris catalog

Actual Behavior

Currently, polaris returns a 401 UnauthorizedResponse which isn't conformant to the REST Catalog Spec.

Expected Behavior

419 AuthenticationTimeoutResponse should be returned

Additional context

No response

System information

No response

[flyrain]

Thanks @sungwy for reporting this. +1 on fixing it.

[liamzwbao]

Hi @flyrain, I'm interested in fixing this bug. Could you please assign it to me?

As 419 does not exist in the standard jakarta library, I'm considering adding a customized PolarisStatus enum to implement the interface Response.StatusType. In addition, we can throw customized exception when the JWTVerificationException is TokenExpiredException.

What do you think?

[flyrain]

Hi @liamzwbao , thanks for picking this up. Assigned it to you.
The approach you describe sounds good to me.

[dimas-b]

Currently, polaris returns a 401 UnauthorizedResponse which isn't conformant to the REST Catalog Spec.

AFAIK, The 419 response code in question relates only to the /token endpoint. No other well-known OIDC Server (or IdP) uses the 419 response code.

However, Iceberg's /token endpoint is deprecated per apache/iceberg#10603

[dimas-b]

Iceberg clients rely on the distinction between status code values to refresh the token when AuthenticationTimeoutResponse is issued for expired tokens.

Where is this aspect of the client's behaviour specified?

[liamzwbao]

AFAIK, The 419 response code in question relates only to the /token endpoint. No other well-known OIDC Server (or IdP) uses the 419 response code.

However, Iceberg's /token endpoint is deprecated per apache/iceberg#10603

From the spec, I have noticed that 419 is used in several places, such as this namespace endpoint. It seems likely that it will continue to be used even after the deprecation of /token.

[flyrain]

I think what @dimas-b said is that only token generated by /token will potentially emit 419. Polaris couldn't emit 419 when it works with any other IDPs.

[dimas-b]

My reading of the Iceberg REST API spec is that clients should be able to deal with 419 responses. Some servers may use that status code.

I do not think the spec requires all servers to use 419 for expired tokens.

I do not think clients can rely on servers to use 419 for expired tokens.

[flyrain]

The RFC(https://www.rfc-editor.org/rfc/rfc6750) recommends to use 401.

invalid_token
The access token provided is expired, revoked, malformed, or
invalid for other reasons. The resource SHOULD respond with
the HTTP 401 (Unauthorized) status code. The client MAY
request a new access token and retry the protected resource
request.

I don't have the context why Iceberg REST spec introduced 419, but it seems not quite useful based on the following statements:

1. The RFC recommend 401 for expiration
2. It's not a good practice of leaking the information of a token is expired.
3. Most well known IDPs don't leak the information of a token is expired.
4. Iceberg REST endpoint /token was deprecated.