Skip to content

Latest commit

 

History

History
473 lines (329 loc) · 33.9 KB

authenticationMechanism.asciidoc

File metadata and controls

473 lines (329 loc) · 33.9 KB
Raw

Authentication Mechanism

This chapter describes the HttpAuthenticationMechanism interface and contract. HttpAuthenticationMechanism is used to authenticate callers of web applications, and is specified only for use in the servlet container. It is explicitly not defined for use with other containers (EJB, JMS, JCA, etc.).

Introduction

A web application consists of resources that can be accessed by any number of callers, who are initially unknown to the application. Callers make themselves known to the application through the process of authentication.

During authentication, the caller presents proof of identity — a token or credential of some kind — which the application (or container) then validates. If the proof is valid, the application (or container) establishes the caller’s identity, then proceeds to the authorization step, in which it determines whether the caller has permission to access the requested resources.

In some cases (for example, username/password authentication) the interaction between the caller and the application is simple. In other cases, a lengthier dialog is required — an application may send a random nonce to the caller, which must then use that nonce in the construction of an authentication token, or there may be interactions with a third party that vouches for the caller’s identity, or the authenticity of the provided credential.

The Jakarta EE Platform already specifies mechanisms for authenticating users of web applications. JSR-340, "Java Servlet Specification", version 3.1 [SERVLET31] specifies a declarative mechanism for configuring an application to provide BASIC, DIGEST, FORM, or CERT authentication, with authentication performed automatically by the container based on the application’s configuration, which, in the case of FORM authentication, can include custom form pages.

In addition, [JASPIC] specifies a general-purpose mechanism for securing messages sent between Jakarta EE clients and servers. JASPIC defines an SPI called ServerAuthModule, which enables development of authentication modules to handle any credential type, or engage in interaction of arbitrary complexity with clients and third parties. [JASPIC] also defines the Servlet Container Profile, which specifies how JASPIC mechanisms, including ServerAuthModules, are integrated with the servlet container.

While both existing mechanisms are important and useful, each has limitations from the point of view of an application developer. The servlet container’s login-config mechanism is limited to the auth-method types defined by [SERVLET31] — it doesn’t support other credential types, or complex interactions with callers. It also relies on unspecified container mechanisms to associate identity stores with applications. There is no way for an application to ensure that callers are authenticated against the desired identity store, or, indeed, against any identity store.

JASPIC, by way of contrast, is extremely flexible and powerful, but is also complex. Writing an AuthModule, and arranging for the web container to use it for authentication, is a non-trivial exercise. Additionally, there is no declarative configuration syntax for JASPIC, and there is no well-defined mechanism for a container to override an application’s programmatically-registered AuthModule. A container can choose to register its own AuthModule, or to remove one registered by an application, but JASPIC will always use the most-recently-registered module — the outcome is dependent on the order in which the application and the container attempt to register their respective modules.

The HttpAuthenticationMechanism interface is designed to capitalize on the strengths of existing authentication mechanisms, while mitigating the corresponding limitations. It is essentially a simplified, servlet-container-specific version of the JASPIC ServerAuthModule interface, retaining that interface’s flexibility and power, but reducing the cost of implementation. An HttpAuthenticationMechanism is a CDI bean, and is therefore made available to the container automatically by CDI. The container is responsible for placing the HttpAuthenticationMechanism in service.

An application MAY supply its own HttpAuthenticationMechanism, if desired. The servlet container MUST provide several default HttpAuthenticationMechanism implementations, which an application can select and configure via standard annotations. The container MAY also provide additional mechanisms beyond those required by this specification. The rules governing how the container selects an HttpAuthenticationMechanism, and how it is placed in service, are described in the "Installation and Configuration" section of this chapter. The required default mechanisms, and corresponding annotations, are described in the "Annotations and Built-In HttpAuthenticationMechanism Beans" section.

Interface and Theory of Operation

The HttpAuthenticationMechanism interface defines three methods that align closely with the methods defined by the JASPIC ServerAuth interface. The primary distinction is syntactic; unlike JASPIC, HttpAuthenticationMechanism is specified for the servlet container only, and can therefore reference servlet types in its method signatures. Only the validateRequest() method must be implemented; default behaviors are specified for the other two methods.

AuthenticationStatus validateRequest(HttpServletRequest request,
                                     HttpServletResponse response,
                                     HttpMessageContext httpMessageContext
                                    ) throws AuthenticationException;

AuthenticationStatus secureResponse(HttpServletRequest request,
                                    HttpServletResponse response,
                                    HttpMessageContext httpMessageContext
                                   ) throws AuthenticationException;

void cleanSubject(HttpServletRequest request,
                  HttpServletResponse response,
                  HttpMessageContext httpMessageContext);

Each method performs the same function as the corresponding ServerAuth method. At runtime, the methods will be invoked by a container-supplied ServerAuthModule that serves as a wrapper, or container, for the HttpAuthenticationMechanism. The container-supplied ServerAuthModule translates the method parameters passed to it, invokes the HttpAuthenticationMechanism method, and returns the resulting status to its caller. The behavior of the HttpAuthenticationMechanism methods should therefore be functionally equivalent to the behavior specified by the JASPIC Servlet Container Profile for the equivalent ServerAuthModule methods.

Summarized, this means:

  • validateRequest() will be invoked before the doFilter() method of any servlet filter or the service() method of any servlet in the application for requests to constrained as well as to unconstrained resources, and, in addition, in response to application code calling the authenticate() method on the HttpServletRequest.

  • secureResponse() will be invoked after the doFilter() method of any servlet filter or the service() method of any servlet in the application for requests to constrained as well as to unconstrained resources, but only if any of these two methods have indeed been invoked.

  • cleanSubject() will be invoked in response to the application calling the logout() method on the HttpServletRequest.

The validateRequest() method is provided to allow a caller to authenticate. An implementation of this method can inspect the HTTP request to extract a credential or other information, or it can write to the HTTP response to, for example, redirect a caller to an OAuth provider, or return an error response. After a credential has been obtained and validated, the result of the validation can be communicated to the container using the HttpMessageContext parameter, which is described in more detail below.

The secureResponse() method is provided to allow post processing on the response generated by a servlet and/or servlet filter, such as encrypting it.

The cleanSubject() is provided to allow for cleanup after a caller is logged out. For example, an authentication mechanism that stores state within a cookie can remove that cookie here.

The HttpMessageContext interface defines methods that an HttpAuthenticationMechanism can invoke to communicate with the JASPIC ServerAuthModule (bridge module) that invokes it. The container MUST provide an implementation of the interface that supports the necessary container integrations.

The HttpMessageContextWrapper class implements a wrapper can be used, in a manner similar to HttpServletRequestWrapper, to provide custom behavior.

See javadoc for a detailed description of HttpMessageContext and HttpMessageContextWrapper. See below for more on the JASPIC bridge module.

Installation and Configuration

An HttpAuthenticationMechanism must be a CDI bean, and is therefore visible to the container through CDI if it is packaged in a bean archive, which generally includes Jakarta EE modules and application archives, as well as other archives and classes that are not part of an application, but are required by the Java EE specification to be visible to applications. See the CDI specification for details on bean archives and bean discovery. An HttpAuthenticationMechanism is assumed to be normal scoped.

It MUST be possible for the definition of an HttpAuthenticationMechanism to exist within the application archive. Alternatively such definition MAY also exists outside the application archive, for example in a jar added to the classpath of an application server.

An application packages its own HttpAuthenticationMechanism by including in a bean archive that is part of the application. Alternatively, it may select and configure one of the container’s built-in mechanisms using the corresponding annotation, as described in the "Annotations and Built-In HttpAuthenticationMechanism Beans" section below.

The container decides which HttpAuthenticationMechanism to place in service using the following rules:

  • The container MAY override an application’s chosen HttpAuthenticationMechanism with one selected by the container, but SHOULD do so only if explicitly configured to.

  • If the container does not override the application, it MUST place in service any HttpAuthenticationMechanism that is provided, either directly or via annotation, by the application.

  • If the application makes more than one HttpAuthenticationMechanism available, either directly or via annotation or both, the results are undefined by this specification.

  • If the application does not supply an HttpAuthenticationMechanism, or select one of the built-in mechanisms, the container MAY choose an HttpAuthenticationMechanism to place in service, but is NOT REQUIRED to do so.

  • If the application does not make an HttpAuthenticationMechanism available, and the container does not choose one to place in service, then HttpAuthenticationMechanism is not used.

The container MUST use JASPIC when placing an HttpAuthenticationMechanism in service. The container MUST supply a "bridge" ServerAuthModule that integrates HttpAuthenticationMechanism with JASPIC. The bridge module MUST look up the correct HttpAuthenticationMechanism using CDI, then delegate to the HttpAuthenticationMechanism when the bridge module’s methods are invoked. Since the method signatures and return values of the two interfaces are similar, but not the same, the bridge module MUST convert back and forth.

When an HttpAuthenticationMechanism is placed in service, the container MUST supply a bridge ServerAuthModule and the necessary supporting modules (AuthContext, AuthConfig, AuthConfigProvider), and arrange for the AuthConfigProvider to be registered with the JASPIC AuthConfigFactory, such that the bridge module is registered for the application context.

When an HttpAuthenticationMechanism is placed in service, the container MUST NOT register any AuthConfigProvider other than the one corresponding to the bridge ServerAuthModule. Given the nature of JASPIC, however, it’s possible that some other entity could register a different AuthConfigProvider after the container has registered the bridge module’s AuthConfigProvider. The container is NOT REQUIRED to prevent this.

Annotations and Built-In HttpAuthenticationMechanism Beans

A Jakarta EE container MUST support built-in beans for the following HttpAuthenticationMechanism types, to be made available via configuration:

  • BASIC - Authenticates according to the mechanism as described in 13.6.1, "HTTP Basic Authentication", in [SERVLET31]. See also RFC 7617, "The 'Basic' HTTP Authentication Scheme" [RFC7617]. This bean is activated and configured via the @BasicAuthenticationMechanismDefinition annotation.

  • FORM - Authenticates according to the mechanism as described in 13.6.3, "Form Based Authentication", in [SERVLET31]. This bean is activated and configured via the @FormAuthenticationMechanismDefinition annotation.

  • Custom FORM - A variant on FORM, with the difference that continuing the authentication dialog as described in [SERVLET31], section 13.6.3, step 3, and further clarified in section 13.6.3.1, does not happen by posting back to j_security_check, but by invoking SecurityContext.authenticate() with the credentials the application collected. This bean is activated and configured via the @CustomFormAuthenticationMechanismDefinition annotation.

All of these beans MUST have the qualifier @Default and the scope @ApplicationScoped, as defined by the CDI specification.

All of the built-in beans MUST support authentication using IdentityStore, described in Chapter 3, "Identity Store", but MAY fall-back to container-specific methods if no IdentityStore is available.

See also the "Implementation Notes" section of this chapter.

The annotations are defined as shown in the following sections.

BASIC Annotation

The following annotation is used to configure the built-in BASIC authentication mechanism.

@Retention(RUNTIME)
@Target(TYPE)
public @interface BasicAuthenticationMechanismDefinition {

    /**
     * Name of realm that will be sent via the <code>WWW-Authenticate</code> header.
     * <p>
     * Note that this realm name <b>does not</b> couple a named identity store
     * configuration to the authentication mechanism.
     *
     * @return Name of realm
     */
    String realmName() default "";
}

FORM Annotation

The following annotation is used to configure the built-in FORM authentication mechanism.

@Retention(RUNTIME)
@Target(TYPE)
public @interface FormAuthenticationMechanismDefinition {

    @Nonbinding
    LoginToContinue loginToContinue();
}

See also the "LoginToContinue Annotation" section below.

Custom FORM Annotation

The following annotation is used to configure the built-in Custom FORM authentication mechanism.

@Retention(RUNTIME)
@Target(TYPE)
public @interface CustomFormAuthenticationMechanismDefinition {

    @Nonbinding
    LoginToContinue loginToContinue();
}

See also the "LoginToContinue Annotation" and "Custom FORM Notes" sections below.

LoginToContinue Annotation

The LoginToContinue annotation provides an application with the ability to declaratively add "login to continue" functionality to an authentication mechanism. "Login to continue" conceptually refers to the algorithm (flow) described by the numbered steps in [SERVLET31], Section 13.6.3, "Form Based Authentication".

The annotation is also used to configure the login page, error page, and redirect/forward behavior for the built-in form-based authentication mechanisms (implicitly suggesting, but not requiring, that those authentication mechanisms use the backing interceptor for this annotation, which is described below).

@Inherited
@InterceptorBinding
@Retention(RUNTIME)
@Target(TYPE)
public @interface LoginToContinue {

    @Nonbinding
    String loginPage() default "/login";

    @Nonbinding
    boolean useForwardToLogin() default true;

    @Nonbinding
    String useForwardToLoginExpression() default "";

    @Nonbinding
    String errorPage() default "/login-error";
}

The container MUST provide an interceptor implementation, at priority PLATFORM_BEFORE + 220, that backs the LoginToContinue annotation and intercepts calls to the configured HttpAuthenticationMechanism. The interceptor MUST behave as follows when intercepting calls to the HttpAuthenticationMechanism:

Intercepting validateRequest()

  • Determine if there is any stale state in the request context, due to a previously aborted flow involving "login to continue". If so, clear the stale state.

  • Determine if this request is a new caller-initiated authentication, by calling isNewAuthentication() on the AuthenticationParameters object available from HttpMessageContext.

    • If isNewAuthentication() returns true, update the request state to indicate that this is a caller-initiated authentication.

  • If the request is a caller-initiated authentication, continue with flow processCallerInitiatedAuthentication.

  • Otherwise, if the request is not a caller-initiated authentication, continue with flow processContainerInitiatedAuthentication.

Flow processCallerInitiatedAuthentication

  • Call the next Interceptor, and remember the resulting AuthenticationStatus.

  • If the result was AuthenticationStatus.SUCCESS, and HttpMessageContext.getCallerPrincipal() returns a non-null principal, clear all state.

  • Return the AuthenticationStatus.

Flow processContainerInitiatedAuthentication

  • Determine how far the caller is in the "login to continue" flow by comparing the request and state against the following numbered and named steps:

    1. OnInitialProtectedURL: Protected resource requested and no saved request state.

    2. OnLoginPostback: A postback after redirecting the caller in Step 1. (Note: this is not necessarily the resource the caller was redirected to — for example, a redirect to /login could result in a postback to j_security_check, or to /login2.)

    3. OnOriginalURLAfterAuthenticate: A request on the original, protected URL from Step 1, with authentication data and saved request state.

  • If the step, as described above, can be determined, continue with the flow having the same name as that step, otherwise return the result of calling the next Interceptor.

Flow OnInitialProtectedURL

  • Save all request details (URI, headers, body, etc.) to the state.

  • Redirect or forward to LoginToContinue.loginPage(), depending on the value of the useForwardToLogin() attribute.

Flow OnLoginPostback

  • Call the next Interceptor, and remember the resulting AuthenticationStatus.

  • If the result was AuthenticationStatus.SUCCESS:

    • If HttpMessageContext.getCallerPrincipal() returns null, return AuthenticationStatus.SUCCESS

    • If the current request matches the saved request state (same URI, headers, etc.), return AuthenticationStatus.SUCCESS

    • If the current request does not match the saved request state, save the authentication state (minimally, the caller principal and groups from the HttpMessageContext) and redirect to the full request URL as stored in the saved request state.

  • If the result was AuthenticationStatus.SEND_FAILURE:

    • If LoginToContinue.errorPage() is non-null and non-empty, redirect to LoginToContinue.errorPage().

  • Return the AuthenticationStatus.

Flow OnOriginalURLAfterAuthenticate

  • Retrieve the saved request and authentication details.

  • Clear all state related to "login to continue".

  • Set a wrapped request into HttpMessageContext that provides all the original request details (headers, body, method, etc.) from the saved request state.

  • Call the HttpMessageContext.notifyContainerAboutLogin() method with the caller principal and groups from the saved authentication state.

  • Return AuthenticationStatus.SUCCESS.

Intercepting secureResponse()

  • The secureResponse() method SHOULD NOT be intercepted.

Intercepting cleanSubject()

  • The cleanSubject() method SHOULD NOT be intercepted.

See also the SecurityContext.authenticate() Notes section below.

RememberMe Annotation

The RememberMe annotation is used to configure a RememberMeIdentityStore, which must be provided by the application. To use RememberMe, the application must provide an HttpAuthenticationMechanism and annotate the HttpAuthenticationMechanism with the RememberMe annotation.

@Inherited
@InterceptorBinding
@Retention(RUNTIME)
@Target(TYPE)
public @interface RememberMe {

    @Nonbinding
    int cookieMaxAgeSeconds() default 86400; // 1 day

    @Nonbinding
    String cookieMaxAgeSecondsExpression() default "";

    @Nonbinding
    boolean cookieSecureOnly() default true;

    @Nonbinding
    String cookieSecureOnlyExpression() default "";

    @Nonbinding
    boolean cookieHttpOnly() default true;

    @Nonbinding
    String cookieHttpOnlyExpression() default "";

    @Nonbinding
    String cookieName() default "JREMEMBERMEID";

    @Nonbinding
    boolean isRememberMe() default true;

    @Nonbinding
    String isRememberMeExpression() default "";
}

The container MUST provide an interceptor implementation at priority PLATFORM_BEFORE + 210 that backs the RememberMe annotation and intercepts calls to the configured HttpAuthenticationMechanism. The interceptor MUST behave as follows when intercepting calls to the HttpAuthenticationMechanism:

Intercepting validateRequest()

  • Determine whether there is a RememberMe cookie in the request.

  • If the cookie is present:

    • Use it to construct a RememberMeCredential and call the validate() method of the RememberMeIdentityStore.

    • If the validate succeeds, call HttpMessageContext.notifyContainerAboutLogin(), passing the CallerPrincipal and CallerGroups returned by validate().

    • If the validate fails, remove the cookie from the request.

  • If no cookie is present, or if the attempt to validate a cookie failed, authenticate the caller normally by calling proceed() on the InvocationContext.

  • If authentication succeeds, and the caller has requested to be remembered, as determined by evaluating the isRememberMeExpression(), then:

    • Call the generateLoginToken() method of the RememberMeIdentityStore.

    • Set the new cookie with parameters as configured on the RememberMe annotation.

Intercepting secureResponse()

  • The secureResponse() method SHOULD NOT be intercepted.

Intercepting cleanSubject()

  • If there is a RememberMe cookie in the request, then:

    • Remove the cookie.

    • Call the removeLoginToken() method of the RememberMeIdentityStore.

See also the description of RememberMeIdentityStore in Chapter 3, "Identity Store".

AutoApplySession Annotation

The AutoApplySession annotation provides a way to declaratively enable JASPIC javax.servlet.http.registerSession behavior for an authentication mechanism, and automatically apply it for every request.

The javax.servlet.http.registerSession property is described in Section 3.8.4 of [JASPIC].

This annotation embodies the concept of a caller being authenticated over a series of multiple HTTP requests (together, a "session"). The built-in form-based authentication mechanisms use this same concept. It is therefore implicitly suggested, but not required, that the form-based authentication mechanisms use the backing interceptor for this annotation to establish and maintain their sessions.

@Inherited
@InterceptorBinding
@Retention(RUNTIME)
@Target(TYPE)
public @interface AutoApplySession {
}

The container MUST provide an interceptor implementation at priority PLATFORM_BEFORE + 200 that backs the AutoApplySession annotation and intercepts calls to the configured HttpAuthenticationMechanism. The interceptor MUST behave as follows when intercepting calls to the HttpAuthenticationMechanism:

Intercepting validateRequest()

  • Get the HttpServletRequest from the HttpMessageContext that is passed as an argument to validateRequest().

  • Get the Principal from the HttpServletRequest (via getUserPrincipal()).

  • If the Principal is null:

    • Call the next Interceptor, and remember the resulting AuthenticationStatus.

      • If the result is AuthenticationStatus.SUCCESS, get the Map object from the MessageInfo in the HttpMessageContext, and add an entry to the Map with key "javax.servlet.http.registerSession" and value "true".

    • Return the AuthenticationStatus.

  • If the Principal is not null:

    • Create a new CallerPrincipalCallback instance, passing the Principal and client subject obtained from HttpMessageContext to the constructor.

    • Obtain the CallbackHandler from HttpMessageContext, and have it handle the CallerPrincipalCallback.

    • Return AuthenticationStatus.SUCCESS.

Intercepting secureResponse()

  • The secureResponse() method SHOULD NOT be intercepted.

Intercepting cleanSubject()

  • The cleanSubject() method SHOULD NOT be intercepted.

See also the AutoApplySession Notes section below.

Implementation Notes

Section 14.4, item 18, of [SERVLET31] describes requirements for supporting BASIC and FORM authentication via the web.xml login-config element. This specification requires that implementations of BASIC and FORM be made available as HttpAuthenticationMechanism CDI beans. The servlet container is NOT REQUIRED to implement separate and independent mechanisms to satisfy each requirement. Instead, the container MAY choose to provide a single mechanism, for each of BASIC and FORM, that meets the requirements of both specifications; i.e., an implementation that can be configured via login-config, but which is also made available as an HttpAuthenticationMechanism if the application uses the corresponding annotation. Equally, the container is NOT REQUIRED to provide a unified implementation, and MAY satisfy the two requirements using separate, independent implementations.

An implementation of BASIC or FORM is NOT REQUIRED to support IdentityStore when configured via login-config, regardless of whether the container has provided a single mechanism or separate mechanisms to satisfy the login-config and HttpAuthenticationMechanism requirements. Implementations MAY support IdentityStore for all configuration methods.

If an application provides an HttpAuthenticationMechanism, and also configures a login-config element in web.xml, the container MAY fail deployment, but is NOT REQUIRED to. If the container does not fail deployment, it MUST use only the HttpAuthenticationMechanism to authenticate the application’s callers (i.e., it MUST ignore the login-config from web.xml).

Custom FORM Notes

The Custom FORM variant is intended to align better with modern Jakarta EE technologies such as CDI, Expression Language, Bean Validation and specifically JSF.

Below is an example showing how the mechanism can be used with those technologies.

Consider the following JSF Facelet:

    <h:messages />

    <body>
        <p>
            Login to continue
        </p>

         <form jsf:id="form">
            <p>
                <strong>Username </strong>
                <input jsf:id="username" type="text"
                    jsf:value="#{loginBacking.username}" />
            </p>
            <p>
                <strong>Password </strong>
                <input jsf:id="password" type="password"
                    jsf:value="#{loginBacking.password}" />
            </p>
            <p>
                <input type="submit" value="Login"
                    jsf:action="#{loginBacking.login}" />
            </p>
        </form>

    </body>

The "Username" and "Password" inputs are bound via expression language to properties of a named CDI bean, and the bean’s login() method is invoked to authenticate the user:

@Named
@RequestScoped
public class LoginBacking {

    @NotNull
    private String username;

    @NotNull
    private String password;

    @Inject
    private SecurityContext securityContext;

    @Inject
    private FacesContext facesContext;

    public void login() {

        Credential credential =
            new UsernamePasswordCredential(username, new Password(password));

        AuthenticationStatus status = securityContext.authenticate(
            getRequest(facesContext),
            getResponse(facesContext),
            withParams()
                .credential(credential));

        if (status.equals(SEND_CONTINUE)) {
            facesContext.responseComplete();
        } else if (status.equals(SEND_FAILURE)) {
            addError(facesContext, "Authentication failed");
        }

    }

SecurityContext.authenticate() Notes

Any LoginToContinue-annotated HttpAuthenticationMechanism, as well as the two built-in FORM authentication mechanisms, can be triggered via a call to the SecurityContext.authenticate() method. This method is based on the HttpServletRequest.authenticate() method, as defined by [SERVLET31], but has been extended to support additional functionality defined by the Servlet Container Profile of [JASPIC].

The extended behavior is facilitated by the AuthenticationParameters parameter passed to SecurityContext.authenticate(). AuthenticationParameters includes a newAuthentication field.

When newAuthentication is set to true, the container MUST discard any state that it holds for an HttpAuthenticationMechanism, and that is associated with the current caller. Specifically, this means that any associated state, such as described for the LoginToContinue Annotation above, MUST be cleared, and the request must proceed as if processing a new request.

When newAuthentication is set to false, the container MUST NOT discard any state that it holds for an HttpAuthenticationMechanism, and that is associated with the current caller. Instead, the container MUST resume the in-progress authentication dialog, based on the associated state. Specifically, the container MUST:

  • Determine how far the caller is in the "login to continue" flow, based on the previously saved state (or lack thereof), and;

  • Continue processing from that point as it would normally do.

AutoApplySession Notes

As an example, idiomatic code for setting the javax.servlet.http.registerSession key as per the requirements is:

httpMessageContext.getMessageInfo().getMap().put("javax.servlet.http.registerSession", TRUE.toString());

As another example, idiomatic code for setting the CallerPrincipalCallback as per the requirements is:

httpMessageContext.getHandler().handle(new Callback[] {
    new CallerPrincipalCallback(httpMessageContext.getClientSubject(), principal) }
);

Relationship to other specifications

An HttpAuthenticationMechanism is a CDI bean, as defined by JSR-346, "Contexts and Dependency Injection for the Jakarta EE platform", version 1.2 [CDI12].

The methods defined by the HttpAuthenticationMechanism closely map to the methods and semantics of a ServerAuthModule, as defined by the Servlet Container Profile of [JASPIC]. (But an HttpAuthenticationMechanism is itself not a ServerAuthModule.) The servlet container MUST use JASPIC mechanisms to arrange for an HttpAuthenticationMechanism to be placed in service.

This specification mandates that when a ServerAuthModule is called by the Servlet container, CDI services (such as the BeanManager) MUST be fully available, and all scopes that are defined to be active during the service() method of a servlet, or during the doFilter() method of a servlet filter, MUST be active. Specifically this means that the request, session, and application scopes MUST be active, and that a ServerAuthModule method such as validateRequest() MUST be able to obtain a reference to the CDI BeanManager programmatically (for example, by doing a JNDI lookup), and MUST be able to use that reference to obtain a valid request-scoped, session-scoped, or application-scoped bean. This specification does not mandate that a ServerAuthModule must itself be a CDI bean, or that a ServerAuthModule must be injectable.

An HttpAuthenticationMechanism implementation is logically equivalent to a built-in authentication mechanism as defined by [SERVLET31] (i.e., HTTP Basic Authentication, HTTP Digest Authentication, Form Based Authentication, and HTTPS Client Authentication); more specifically, it corresponds to an "additional container authentication mechanism", as described in section 13.6.5 of [SERVLET31].

The BASIC and FORM authentication mechanisms as defined by this specification are logically equivalent to the similarly named authentication mechanisms in [SERVLET31], respectively sections 13.6.1, "HTTP Basic Authentication", and 13.6.3, "Form Based Authentication".