Should the default getVirtualServerName() return value agree with what JaspiAuthenticatorFactory looks for?

[lrasku]

Jetty version(s)
12.1.5

Jetty Environment
ee9 through ee11 by a quick grep of the codebase

HTTP version
Shouldn't matter

Java version/vendor (use: java -version)
openjdk version "21.0.9" 2025-10-21 LTS
OpenJDK Runtime Environment (Red_Hat-21.0.9.0.10-1) (build 21.0.9+10-LTS)
OpenJDK 64-Bit Server VM (Red_Hat-21.0.9.0.10-1) (build 21.0.9+10-LTS, mixed mode, sharing)

OS type/version
AlmaLinux 9.6

Description
The Jakarta Authentication spec says:

A Jakarta Servlet container that implements a version of the Jakarta Servlet specification that defines the getVirtualServerName method on the ServletContext interface, must construct its application context identifiers using a value for hostname that is equivalent to the value returned by calling getVirtualServerName on the ServletContext corresponding to the web application.

So it is indeed tempting to construct the app context identifiers using code like ctx.getVirtualServerName() + " /some/context/path", but unfortunately this won't work on Jetty if the servlet was installed without an explicit virtual host name, because in this scenario getVirtualServerName() returns null, but JaspiAuthenticatorFactory looks for "server".

The easy and obvious fix would be to have getVirtualServerName() return "server" too, but I suspect that would be overturning a lot of precedent and be perhaps misleading besides, but I'm not sure what the alternative would be. Have the docs stress that servlets must be installed with explicit virtual host names?

How to reproduce?
The example project from #14165 can be repurposed for this by changing the "server /" at src/main/java/example/TestServlet.java:49 into ctx.getVirtualServerName()+" /" and observe that authentication fails at http://localhost:9000/test like so:

2025-12-11 01:27:52.378:WARN :oeje10s.ServletChannel:qtp1690716179-95: /test
jakarta.servlet.ServletException: Authentication failed
at org.eclipse.jetty.ee10.servlet.ServletApiRequest.authenticate(ServletApiRequest.java:628)
at example.TestServlet.doGet(TestServlet.java:96)
at jakarta.servlet.http.HttpServlet.service(HttpServlet.java:527)
at jakarta.servlet.http.HttpServlet.service(HttpServlet.java:614)
at org.eclipse.jetty.ee10.servlet.ServletHolder.handle(ServletHolder.java:752)
at org.eclipse.jetty.ee10.servlet.ServletHandler$ChainEnd.doFilter(ServletHandler.java:1620)
at org.eclipse.jetty.ee10.servlet.ServletHandler$MappedServlet.handle(ServletHandler.java:1554)
at org.eclipse.jetty.ee10.servlet.ServletChannel.dispatch(ServletChannel.java:868)
at org.eclipse.jetty.ee10.servlet.ServletChannel.handle(ServletChannel.java:449)
at org.eclipse.jetty.ee10.servlet.ServletHandler.handle(ServletHandler.java:469)
at org.eclipse.jetty.security.SecurityHandler.handle(SecurityHandler.java:546)
at org.eclipse.jetty.ee10.servlet.SessionHandler.handle(SessionHandler.java:719)
at org.eclipse.jetty.server.handler.ContextHandler.handle(ContextHandler.java:1224)
at org.eclipse.jetty.server.Server.handle(Server.java:197)
at org.eclipse.jetty.server.internal.HttpChannelState$HandlerInvoker.run(HttpChannelState.java:720)
at org.eclipse.jetty.server.internal.HttpConnection.onFillable(HttpConnection.java:412)
at org.eclipse.jetty.server.internal.HttpConnection$FillableCallback.succeeded(HttpConnection.java:1810)
at org.eclipse.jetty.io.FillInterest.fillable(FillInterest.java:105)
at org.eclipse.jetty.io.SelectableChannelEndPoint$1.run(SelectableChannelEndPoint.java:54)
at org.eclipse.jetty.util.thread.QueuedThreadPool.runJob(QueuedThreadPool.java:1009)
at org.eclipse.jetty.util.thread.QueuedThreadPool$Runner.doRunJob(QueuedThreadPool.java:1239)
at org.eclipse.jetty.util.thread.QueuedThreadPool$Runner.run(QueuedThreadPool.java:1194)
at java.base/java.lang.Thread.run(Thread.java:1583)

Due to context path no longer matching.

[lorban]

My reading of the Jakarta Authentication Specification makes me think that "logical host" (as referred to by the ServletContext.getVirtualServerName() javadoc) is vaguely defined.

IMHO when no virtual host is configured, the name returned by ServletContext.getVirtualServerName() should be oejs.Server.getName() if not null, and InetAddress.getLocalHost().getHostName() at last resort.

@joakime @janbartel @olamy What do you think?

[janbartel]

@lrasku we do try and use the getVirtualServerName(), but if it's null then we revert to server. It seems to me that you're saying we shouldn't do that and it is more correct to simply use null instead?

[janbartel]

My reading of the Jakarta Authentication Specification makes me think that "logical host" (as referred to by the ServletContext.getVirtualServerName() javadoc) is vaguely defined.

IMHO when no virtual host is configured, the name returned by ServletContext.getVirtualServerName() should be oejs.Server.getName() if not null, and InetAddress.getLocalHost().getHostName() at last resort.

@joakime @janbartel @olamy What do you think?

@lorban I don't think it would be correct to return anything other than null for getVirtualServerName() if no virtual hosts have been configured. Also, I don't think we routinely set the name of the server do we? So it would generally be null anyway?

It seems to me that the value returned is highly container-specific, and null should be an acceptable value in the case where the user hasn't configured anything.

[joakime]

This is a poorly defined part of Jakarta Authentication.

It was first brought up in

• AppContextID of Servlet profile includes name of virtual host; for which Servlet provides no portable api jakartaee/authentication#1

But there's been no further discussion, and there's no TCK tests in Jakarta Authentication for this behavior as well.

• https://github.com/search?q=repo%3Ajakartaee%2Fauthentication%20getVirtualServerName&type=code

Glassfish's implementation (based on Apache Tomcat/Catalina) is super simple ...

See:

• https://github.com/eclipse-ee4j/glassfish/blob/7.1.0/appserver/web/web-core/src/main/java/org/apache/catalina/core/StandardContext.java#L2573
• https://github.com/eclipse-ee4j/glassfish/blob/7.1.0/appserver/web/web-core/src/main/java/org/apache/catalina/Container.java#L235

The testcase is also stupidly simple, and has no relationship with the virtual host name.

• https://github.com/eclipse-ee4j/glassfish/tree/7.1.0/appserver/tests/appserv-tests/devtests/web/servlet-3.1/servletContextGetVirtualServerName

[joakime]

I'm in favor of not changing this in Jetty for ee11 or older.
If Jakarta Authentication wants it to be a specific way, then they need to ...

1. Better define what they need/want.
2. Introduce TCK tests in Jakarta Servlet for the behavior.
3. Introduce TCK tests in Jakarta Authentication for the behavior.

[lrasku]

@lrasku we do try and use the getVirtualServerName(), but if it's null then we revert to server. It seems to me that you're saying we shouldn't do that and it is more correct to simply use null instead?

I hadn't actually thought of that, since it would mean concatenating with a null String object in JaspiAuthenticatorFactory.getAuthenticator, which I assumed would throw an NPE - but today I learned that Java then treats the null reference as the string "null", which would solve this problem exactly.

Admittedly it is a smelly solution, relying on this bizarre behavior, but it would be a nice fallback in the absence of better specification from Jakarta Authentication.

[lorban]

Glassfish's implementation (based on Apache Tomcat/Catalina) is super simple ...

See:

* https://github.com/eclipse-ee4j/glassfish/blob/7.1.0/appserver/web/web-core/src/main/java/org/apache/catalina/core/StandardContext.java#L2573

* https://github.com/eclipse-ee4j/glassfish/blob/7.1.0/appserver/web/web-core/src/main/java/org/apache/catalina/Container.java#L235

And here is how WildFly does it:

If the name attribute is not set, the default name for the host will be the value of the jboss.host.name system property. If that is not set, the value of the HOSTNAME or COMPUTERNAME environment variable will be used, one of which will be set on most operating systems. If neither is set the name will be the value of InetAddress.getLocalHost().getHostName().

See: https://docs.wildfly.org/24/Admin_Guide.html#host-controller-configuration

which is why I suggested relying on Server.getName() to make the default logical name configurable. But I do agree that Jakarta Authentication has not clearly specified what that's supposed to mean so my suggestion would be more of a stopgap rather than a clean solution.

[arjantijms]

It’s interesting that so many years after defining it in Jakarta Authentication (and by extension in the Servlet spec) this comes up as a problem here.

One of the things we were thinking about back then is moving the entire getContextId to the Servlet spec, so we don’t have to explicitly construct it using the definition in the authentication spec.

I’m sure if we search hard enough that discussion should be findable still.

Would love to tighten this one way or the other; either in the security / authentication spec or on the servlet spec.

[joakime]

@arjantijms things to consider for a well defined spec ..

• What is allowed in that string?
• What is not allowed in that string?
• What is required to be there?
• What is optional / nice to have?
• Is there a syntax?

So answering things like ...

• If there is a virtual host configuration, does it matter for the purposes of the value in getVirtualServerName()?
• What if there are multiple virtual host configurations?
• What is an example lookup sequence?
• Is there a Jakarta Authentication context attribute or environment variable we should fall back to?
• What is the encoding for this value? Is UTF-8 allowed?
• Is whitespace allowed? (at the start? end? in the middle?)
• Are control characters allowed?
• Do sequences need to be percent encoded? (%2F, %25`) - what would happen if a percent encoded sequence exists?
• Of the usual gambit of delimiters, are any of them allowed? (eg: /, ,, ;, :, etc. See the HTTP delimiters for more examples). If they are allowed, do they have restrictions on where in the resulting string they appear? (eg: the / is not allowed to be the first character)
• What about the typical action characters or sequences? (eg: ${foo}, @{foo}, [foo], @foo@) these are the kinds of things that various other 3rd party libraries will cause actions or resolving against.