Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update references to other Jakarta specifications #216

Merged
merged 1 commit into from
Mar 23, 2022
Merged

Update references to other Jakarta specifications #216

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 14 additions & 14 deletions spec/src/main/asciidoc/authenticationMechanism.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,11 @@ During authentication, the caller presents proof of identity -- a token or crede

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. The Jakarta Servlet Specification, version 4.0 [https://jakarta.ee/specifications/servlet/4.0/[SERVLET40]] 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.
The Jakarta EE Platform already specifies mechanisms for authenticating users of web applications. The Jakarta Servlet Specification, version 4.0 [https://jakarta.ee/specifications/servlet/6.0/[SERVLET60]] 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, The Jakarta Authentication Specification, version 1.1 [https://jakarta.ee/specifications/authentication/1.1/[AUTHENTICATION11]] specifies a general-purpose mechanism for securing messages sent between Jakarta EE clients and servers. Jakarta Authentication 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. [https://jakarta.ee/specifications/authentication/1.1/[AUTHENTICATION11]] also defines the Servlet Container Profile, which specifies how Jakarta Authentication mechanisms, including _ServerAuthModules_, are integrated with the servlet container.
In addition, The Jakarta Authentication Specification, version 3.0 [https://jakarta.ee/specifications/authentication/3.0/[AUTHENTICATION30]] specifies a general-purpose mechanism for securing messages sent between Jakarta EE clients and servers. Jakarta Authentication 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. [https://jakarta.ee/specifications/authentication/3.0/[AUTHENTICATION30]] also defines the Servlet Container Profile, which specifies how Jakarta Authentication 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 [https://jakarta.ee/specifications/servlet/4.0/[SERVLET40]] -- 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.
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 [https://jakarta.ee/specifications/servlet/6.0/[SERVLET60]] -- 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.

Jakarta Authentication, 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 Jakarta Authentication, 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 Jakarta Authentication 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.

Expand Down Expand Up @@ -93,9 +93,9 @@ When an _HttpAuthenticationMechanism_ is placed in service, the container MUST N

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 [https://jakarta.ee/specifications/servlet/4.0/[SERVLET40]]. See also RFC 7617, "The 'Basic' HTTP Authentication Scheme" [https://tools.ietf.org/html/rfc7617[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 [https://jakarta.ee/specifications/servlet/4.0/[SERVLET40]]. 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 [https://jakarta.ee/specifications/servlet/4.0/[SERVLET40]], 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.
* BASIC - Authenticates according to the mechanism as described in 13.6.1, "HTTP Basic Authentication", in [https://jakarta.ee/specifications/servlet/6.0/[SERVLET60]]. See also RFC 7617, "The 'Basic' HTTP Authentication Scheme" [https://tools.ietf.org/html/rfc7617[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 [https://jakarta.ee/specifications/servlet/6.0/[SERVLET60]]. 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 [https://jakarta.ee/specifications/servlet/6.0/[SERVLET60]], 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.

Expand Down Expand Up @@ -163,7 +163,7 @@ See also the "<<LoginToContinue Annotation>>" and "<<Custom FORM Notes>>" sectio

==== 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 [https://jakarta.ee/specifications/servlet/4.0/[SERVLET40]], Section 13.6.3, "Form Based Authentication".
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 [https://jakarta.ee/specifications/servlet/6.0/[SERVLET60]], 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).

Expand Down Expand Up @@ -307,7 +307,7 @@ See also the description of _RememberMeIdentityStore_ in Chapter 3, "<<identityS

The _AutoApplySession_ annotation provides a way to declaratively enable Jakarta Authentication _jakarta.servlet.http.registerSession_ behavior for an authentication mechanism, and automatically apply it for every request.

The _jakarta.servlet.http.registerSession_ property is described in Section 3.8.4 of [https://jakarta.ee/specifications/authentication/1.1/[AUTHENTICATION11]].
The _jakarta.servlet.http.registerSession_ property is described in Section 3.8.4 of [https://jakarta.ee/specifications/authentication/3.0/[AUTHENTICATION30]].

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.

Expand Down Expand Up @@ -345,7 +345,7 @@ See also the <<AutoApplySession Notes>> section below.

==== Implementation Notes ====

Section 14.4, item 18, of [https://jakarta.ee/specifications/servlet/4.0/[SERVLET40]] 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.
Section 14.4, item 18, of [https://jakarta.ee/specifications/servlet/6.0/[SERVLET60]] 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.

Expand Down Expand Up @@ -430,7 +430,7 @@ public class LoginBacking {

==== 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 [https://jakarta.ee/specifications/servlet/4.0/[SERVLET40]], but has been extended to support additional functionality defined by the Servlet Container Profile of [https://jakarta.ee/specifications/authentication/1.1/[AUTHENTICATION11]].
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 [https://jakarta.ee/specifications/servlet/6.0/[SERVLET60]], but has been extended to support additional functionality defined by the Servlet Container Profile of [https://jakarta.ee/specifications/authentication/3.0/[AUTHENTICATION30]].

The extended behavior is facilitated by the _AuthenticationParameters_ parameter passed to _SecurityContext.authenticate()_. _AuthenticationParameters_ includes a _newAuthentication_ field.

Expand Down Expand Up @@ -462,12 +462,12 @@ httpMessageContext.getHandler().handle(new Callback[] {

=== Relationship to other specifications

An _HttpAuthenticationMechanism_ is a CDI bean, as defined by Jakarta Contexts and Dependency Injection spec, version 2.0 [https://jakarta.ee/specifications/cdi/2.0/[CDI20]].
An _HttpAuthenticationMechanism_ is a CDI bean, as defined by Jakarta Contexts and Dependency Injection spec, version 4.0 [https://jakarta.ee/specifications/cdi/4.0/[CDI40]].

The methods defined by the _HttpAuthenticationMechanism_ closely map to the methods and semantics of a _ServerAuthModule_, as defined by the Servlet Container Profile of [https://jakarta.ee/specifications/authentication/1.1/[AUTHENTICATION11]]. (But an _HttpAuthenticationMechanism_ is itself not a _ServerAuthModule_.) The servlet container MUST use Jakarta Authentication mechanisms to arrange for an _HttpAuthenticationMechanism_ to be placed in service.
The methods defined by the _HttpAuthenticationMechanism_ closely map to the methods and semantics of a _ServerAuthModule_, as defined by the Servlet Container Profile of [https://jakarta.ee/specifications/authentication/3.0/[AUTHENTICATION30]]. (But an _HttpAuthenticationMechanism_ is itself not a _ServerAuthModule_.) The servlet container MUST use Jakarta Authentication 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 [https://jakarta.ee/specifications/servlet/4.0/[SERVLET40]] (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 [https://jakarta.ee/specifications/servlet/4.0/[SERVLET40]].
An _HttpAuthenticationMechanism_ implementation is logically equivalent to a built-in authentication mechanism as defined by [https://jakarta.ee/specifications/servlet/6.0/[SERVLET60]] (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 [https://jakarta.ee/specifications/servlet/6.0/[SERVLET60]].

The BASIC and FORM authentication mechanisms as defined by this specification are logically equivalent to the similarly named authentication mechanisms in [https://jakarta.ee/specifications/servlet/4.0/[SERVLET40]], respectively sections 13.6.1, "HTTP Basic Authentication", and 13.6.3, "Form Based Authentication".
The BASIC and FORM authentication mechanisms as defined by this specification are logically equivalent to the similarly named authentication mechanisms in [https://jakarta.ee/specifications/servlet/6.0/[SERVLET60]], respectively sections 13.6.1, "HTTP Basic Authentication", and 13.6.3, "Form Based Authentication".
34 changes: 17 additions & 17 deletions spec/src/main/asciidoc/bibliography.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,25 +7,25 @@

The following documents are referenced by this specification.

[CDI20]::
Jakarta Contexts and Dependency Injection, version 2.0 +
https://jakarta.ee/specifications/cdi/2.0/
[CDI40]::
Jakarta Contexts and Dependency Injection, version 4.0 +
https://jakarta.ee/specifications/cdi/4.0/

[JEB32]::
Jakarta Enterprise Beans, version 3.2 +
https://jakarta.ee/specifications/enterprise-beans/3.2/

[EL30]::
Jakarta Expression Language, version 3.0 +
https://jakarta.ee/specifications/expression-language/3.0/
[EL50]::
Jakarta Expression Language, version 5.0 +
https://jakarta.ee/specifications/expression-language/5.0/

[AUTHORIZATION15]::
Jakarta Authorization, version 1.5 +
https://jakarta.ee/specifications/authorization/1.5/
[AUTHORIZATION21]::
Jakarta Authorization, version 2.1 +
https://jakarta.ee/specifications/authorization/2.1/

[AUTHENTICATION11]::
Jakarta Authentication, version 1.1 +
https://jakarta.ee/specifications/authentication/1.1/
[AUTHENTICATION30]::
Jakarta Authentication, version 3.0 +
https://jakarta.ee/specifications/authentication/3.0/

[RFC2119]::
RFC 2119, "Key words for use in RFCs to Indicate Requirement Level" +
Expand All @@ -36,12 +36,12 @@ RFC 7617, "The 'Basic' HTTP Authentication Scheme" +
https://tools.ietf.org/html/rfc7617

[SECAPI]::
Jakarta Security, version 1.0 +
https://jakarta.ee/specifications/security/1.0/
Jakarta Security, version 3.0 +
https://jakarta.ee/specifications/security/3.0/

[SERVLET40]::
Jakarta Servlet, version 3.0 +
https://jakarta.ee/specifications/servlet/4.0/
[SERVLET60]::
Jakarta Servlet, version 6.0 +
https://jakarta.ee/specifications/servlet/6.0/

[SHIROTERM]::
"Apache Shiro Terminology" +
Expand Down
Loading