diff --git a/spec/src/main/asciidoc/authenticationMechanism.asciidoc b/spec/src/main/asciidoc/authenticationMechanism.asciidoc index 7754a4e..20fa6d0 100644 --- a/spec/src/main/asciidoc/authenticationMechanism.asciidoc +++ b/spec/src/main/asciidoc/authenticationMechanism.asciidoc @@ -2,7 +2,7 @@ == 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.). +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 (enterprise beans, messaging, connectors, etc.). === Introduction @@ -12,21 +12,21 @@ 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. JSR-340, "Java Servlet Specification", version 3.1 [https://jcp.org/aboutJava/communityprocess/final/jsr340/index.html[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. +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. -In addition, [https://jcp.org/aboutJava/communityprocess/mrel/jsr196/index2.html[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. [https://jcp.org/aboutJava/communityprocess/mrel/jsr196/index2.html[JASPIC]] also defines the Servlet Container Profile, which specifies how JASPIC mechanisms, including _ServerAuthModules_, are integrated with the servlet container. +In addition, [https://jakarta.ee/specifications/authentication/1.1/[JASPIC]] 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/[JASPIC]] also defines the Servlet Container Profile, which specifies howJakarta 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://jcp.org/aboutJava/communityprocess/final/jsr340/index.html[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. +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. -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. +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. -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. +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 Jakarta Authentication _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 "<>" section of this chapter. The required default mechanisms, and corresponding annotations, are described in the "<>" 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. +The _HttpAuthenticationMechanism_ interface defines three methods that align closely with the methods defined by the Jakarta Authentication _ServerAuth_ interface. The primary distinction is syntactic; unlike Jakarta Authentication, _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. [source,java] ---- @@ -45,7 +45,7 @@ void cleanSubject(HttpServletRequest request, 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. +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 theJakarta Authentication Servlet Container Profile for the equivalent _ServerAuthModule_ methods. Summarized, this means: @@ -61,11 +61,11 @@ The _secureResponse()_ method is provided to allow post processing on the respon 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 _HttpMessageContext_ interface defines methods that an _HttpAuthenticationMechanism_ can invoke to communicate with theJakarta Authentication _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. +See javadoc for a detailed description of _HttpMessageContext_ and _HttpMessageContextWrapper_. See below for more on theJakarta Authentication bridge module. === Installation and Configuration @@ -83,19 +83,19 @@ The container decides which _HttpAuthenticationMechanism_ to place in service us * 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. +The container MUST useJakarta Authentication when placing an _HttpAuthenticationMechanism_ in service. The container MUST supply a "bridge" _ServerAuthModule_ that integrates _HttpAuthenticationMechanism_ withJakarta Authentication. 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 supply a bridge _ServerAuthModule_ and the necessary supporting modules (_AuthContext_, _AuthConfig_, _AuthConfigProvider_), and arrange for the _AuthConfigProvider_ to be registered with theJakarta Authentication _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. +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 ofJakarta Authentication, 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 [https://jcp.org/aboutJava/communityprocess/final/jsr340/index.html[SERVLET31]]. 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://jcp.org/aboutJava/communityprocess/final/jsr340/index.html[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 [https://jcp.org/aboutJava/communityprocess/final/jsr340/index.html[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. +* 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. All of these beans MUST have the qualifier @Default and the scope @ApplicationScoped, as defined by the CDI specification. @@ -163,7 +163,7 @@ See also the "<>" and "<>" 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://jcp.org/aboutJava/communityprocess/final/jsr340/index.html[SERVLET31]], 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/4.0/[SERVLET40]], 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). @@ -305,9 +305,9 @@ See also the description of _RememberMeIdentityStore_ in Chapter 3, "<> section below. ==== Implementation Notes ==== -Section 14.4, item 18, of [https://jcp.org/aboutJava/communityprocess/final/jsr340/index.html[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. +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. 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. @@ -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://jcp.org/aboutJava/communityprocess/final/jsr340/index.html[SERVLET31]], but has been extended to support additional functionality defined by the Servlet Container Profile of [https://jcp.org/aboutJava/communityprocess/mrel/jsr196/index2.html[JASPIC]]. +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/[JASPIC]]. The extended behavior is facilitated by the _AuthenticationParameters_ parameter passed to _SecurityContext.authenticate()_. _AuthenticationParameters_ includes a _newAuthentication_ field. @@ -462,12 +462,12 @@ httpMessageContext.getHandler().handle(new Callback[] { === 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 [https://jcp.org/aboutJava/communityprocess/mrel/jsr346/index.html[CDI12]]. +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]]. -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://jcp.org/aboutJava/communityprocess/mrel/jsr196/index2.html[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. +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/[JASPIC]]. (But an _HttpAuthenticationMechanism_ is itself not a _ServerAuthModule_.) The servlet container MUST useJakarta 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://jcp.org/aboutJava/communityprocess/final/jsr340/index.html[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 [https://jcp.org/aboutJava/communityprocess/final/jsr340/index.html[SERVLET31]]. +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]]. -The BASIC and FORM authentication mechanisms as defined by this specification are logically equivalent to the similarly named authentication mechanisms in [https://jcp.org/aboutJava/communityprocess/final/jsr340/index.html[SERVLET31]], 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/4.0/[SERVLET40]], respectively sections 13.6.1, "HTTP Basic Authentication", and 13.6.3, "Form Based Authentication". diff --git a/spec/src/main/asciidoc/bibliography.asciidoc b/spec/src/main/asciidoc/bibliography.asciidoc index 454fdc8..e95bac0 100644 --- a/spec/src/main/asciidoc/bibliography.asciidoc +++ b/spec/src/main/asciidoc/bibliography.asciidoc @@ -7,25 +7,25 @@ The following documents are referenced by this specification. -[CDI12]:: -JSR-346, "Contexts and Dependency Injection for the Java EE platform", version 1.2, Maintenance Release + -https://jcp.org/aboutJava/communityprocess/mrel/jsr346/index.html +[CDI20]:: +Jakarta Contexts and Dependency Injection, version 2.0 + +https://jakarta.ee/specifications/cdi/2.0/ -[EJB32]:: -JSR-345, "Enterprise JavaBeans", version 3.2 + -https://jcp.org/aboutJava/communityprocess/final/jsr345/index.html +[JEB32]:: +Jakarta Enterprise Beans, version 3.2 + +https://jakarta.ee/specifications/enterprise-beans/3.2/ [EL30]:: -JSR-341, "Expression Language", version 3.0 + -https://jcp.org/aboutJava/communityprocess/final/jsr341/index.html +Jakarta Expression Language, version 3.0 + +https://jakarta.ee/specifications/expression-language/3.0/ [JACC]:: -JSR-115, "Java Authorization Contract for Containers", version 1.5, Maintenance Release 3 + -https://jcp.org/aboutJava/communityprocess/mrel/jsr115/index3.html +Jakarta Authorization, version 1.5 + +https://jakarta.ee/specifications/authorization/1.5/ [JASPIC]:: -JSR-196, "Java Authentication SPI for Containers", version 1.1, Maintenance Release B + -https://jcp.org/aboutJava/communityprocess/mrel/jsr196/index2.html +Jakarta Authentication, version 1.1 + +https://jakarta.ee/specifications/authentication/1.1/ [RFC2119]:: RFC 2119, "Key words for use in RFCs to Indicate Requirement Level" + @@ -36,12 +36,12 @@ RFC 7617, "The 'Basic' HTTP Authentication Scheme" + https://tools.ietf.org/html/rfc7617 [SECAPI]:: -JSR-375, "Java EE Security API", version 1.0 + -https://jcp.org/en/jsr/detail?id=375 +Jakarta Security, version 1.0 + +https://jakarta.ee/specifications/security/1.0/ -[SERVLET31]:: -JSR-340, "Java Servlet Specification", version 3.1 + -https://jcp.org/aboutJava/communityprocess/final/jsr340/index.html +[SERVLET40]:: +Jakarta Servlet, version 3.0 + +https://jakarta.ee/specifications/servlet/4.0/ [SHIROTERM]:: "Apache Shiro Terminology" + diff --git a/spec/src/main/asciidoc/concepts.asciidoc b/spec/src/main/asciidoc/concepts.asciidoc index 1cc9c36..6a27860 100644 --- a/spec/src/main/asciidoc/concepts.asciidoc +++ b/spec/src/main/asciidoc/concepts.asciidoc @@ -20,14 +20,8 @@ Abbreviation for _HttpAuthenticationMechanism_, an interface defined by this spe Identity Store:: An Identity Store is a component that can access application-specific security data such as users, groups, roles, and permissions. It can be thought of as a security-specific DAO (Data Access Object). Synonyms: security provider, repository, store, login module (JAAS), identity manager, service provider, relying party, authenticator, user service. Identity Stores usually have a 1-to-1 correlation with a data source such as a relational database, LDAP directory, file system, or other similar resource. As such, implementations of the _IdentityStore_ interface use data source-specific APIs to discover authorization data (roles, permissions, etc), such as JDBC, File IO, Hibernate or JPA, or any other Data Access API. -JACC:: -JSR-115, "Java Authorization Contract for Containers", version 1.5 [https://jcp.org/aboutJava/communityprocess/mrel/jsr115/index3.html[JACC]]. - -JASPIC:: -JSR-196, "Java Authentication SPI for Containers", version 1.1 [https://jcp.org/aboutJava/communityprocess/mrel/jsr196/index2.html[JASPIC]]. - SAM:: -Abbreviation for _ServerAuthModule_, an interface defined by JASPIC. +Abbreviation for _ServerAuthModule_, an interface defined by Jakarta Authentication. === General Requirements @@ -43,7 +37,7 @@ An application server MAY provide a default mapping from caller principal names ==== Caller Principal Types -This specification defines a principal type called _CallerPrincipal_ to represent the identity of an application caller. Historically, application servers have used different principal types to represent an application's callers, and various Jakarta EE specifications (e.g., JASPIC), provide abstractions to accommodate, "the container's representation of the caller principal". +This specification defines a principal type called _CallerPrincipal_ to represent the identity of an application caller. Historically, application servers have used different principal types to represent an application's callers, and various Jakarta EE specifications (e.g., Jakarta Authentication), provide abstractions to accommodate, "the container's representation of the caller principal". This specification RECOMMENDS that Jakarta EE application servers that rely on container-specific caller principal types derive those types by extending _CallerPrincipal_, so that portable applications can rely on a consistent representation of the caller principal. @@ -80,4 +74,4 @@ Attributes on these annotations can be provided either as actual values, or as E For more information, see the package javadoc for the javax.security.enterprise package. -Expression Language 3.0 is specified by JSR-341, "Expression Language", version 3.0 [https://jcp.org/aboutJava/communityprocess/final/jsr341/index.html[EL30]] +Jakarta Expression Language, version 3.0 [https://jakarta.ee/specifications/expression-language/3.0/[EL30]] is a Jakarta EE specification. diff --git a/spec/src/main/asciidoc/identityStore.asciidoc b/spec/src/main/asciidoc/identityStore.asciidoc index 7b2e39f..831c569 100644 --- a/spec/src/main/asciidoc/identityStore.asciidoc +++ b/spec/src/main/asciidoc/identityStore.asciidoc @@ -10,7 +10,7 @@ _IdentityStore_ provides an abstraction of an identity store, which is a databas Implementations of the _IdentityStore_ interface are used to interact with identity stores to authenticate users (i.e., validate their credentials), and to retrieve caller groups. _IdentityStore_ is roughly analogous to the JAAS _LoginModule_ interface, which is often integrated into Jakarta EE products (albeit in vendor-specific ways). Unlike _LoginModule_, _IdentityStore_ is intended specifically for Java EE, and provides only credential validation and group retrieval functions (i.e., functions that require interaction with an identity store). An _IdentityStore_ does not collect caller credentials, or manipulate __Subject__s. -_IdentityStore_ is intended primarily for use by _HttpAuthenticationMechanism_ implementations, but could in theory be used by other types of authentication mechanisms (e.g., a JASPIC _ServerAuthModule_, or a container's built-in authentication mechanisms). _HttpAuthenticationMechanism_ implementations are not required to use _IdentityStore_ -- they can authenticate users in any manner they choose -- but _IdentityStore_ will often be a useful and convenient mechanism. +_IdentityStore_ is intended primarily for use by _HttpAuthenticationMechanism_ implementations, but could in theory be used by other types of authentication mechanisms (e.g., a Jakarta Authentication _ServerAuthModule_, or a container's built-in authentication mechanisms). _HttpAuthenticationMechanism_ implementations are not required to use _IdentityStore_ -- they can authenticate users in any manner they choose -- but _IdentityStore_ will often be a useful and convenient mechanism. A significant advantage of using _HttpAuthenticationMechanism_ and _IdentityStore_ over container-provided BASIC or FORM implementations is that it allows an application to control the identity stores it will authenticate against, in a standard, portable way. @@ -383,4 +383,4 @@ See javadoc for further details on _PasswordHash_ and the _DatabaseIdentityStore === Relationship to Other Specifications -_IdentityStore_ and _IdentityStoreHandler_ implementations are CDI beans, as defined by [https://jcp.org/aboutJava/communityprocess/mrel/jsr346/index.html[CDI12]]. +_IdentityStore_ and _IdentityStoreHandler_ implementations are CDI beans, as defined by [https://jakarta.ee/specifications/cdi/2.0/[CDI20]]. diff --git a/spec/src/main/asciidoc/license.asciidoc b/spec/src/main/asciidoc/license.asciidoc index 79db3e8..b8b374e 100644 --- a/spec/src/main/asciidoc/license.asciidoc +++ b/spec/src/main/asciidoc/license.asciidoc @@ -5,7 +5,7 @@ == License -Specification: JSR-375 Java EE Security API ("Specification") +Specification: Jakarta Security Version: 1.0 diff --git a/spec/src/main/asciidoc/preface.asciidoc b/spec/src/main/asciidoc/preface.asciidoc index 4388481..7c108be 100644 --- a/spec/src/main/asciidoc/preface.asciidoc +++ b/spec/src/main/asciidoc/preface.asciidoc @@ -5,7 +5,7 @@ == Preface -This document is the Jakarta EE Security API Specification, version 1.0. +This document is the Jakarta Security Specification, version 1.0. === Notational Conventions @@ -15,11 +15,11 @@ Other documents referenced by this specification are identified by name on first === Acknowledgments -The authors would like to thank the JSR-375 Expert Group and Contributors, and, in particular, Arjan Tijms, whose contributions were critical to the success of the JSR. +The authors would like to thank the JSR-375 Expert Group and Contributors, and, in particular, Arjan Tijms, whose contributions were critical to the success of the JCP JSR. We would also like to thank Alex Kosowski for his work putting together the original JSR-375 proposal, submitting it to the JCP, recruiting a diverse and highly-qualified expert group, and leading the initial development and specification efforts. Without Alex, there would be no JSR-375. -Lastly, we would like to acknowledge Ron Monzillo, and the various expert groups he has led or worked with over the years, for putting in place the foundational security APIs and SPIs upon which JSR-375 is built. +Lastly, we would like to acknowledge Ron Monzillo, and the various expert groups he has led or worked with over the years, for putting in place the foundational security APIs and SPIs upon which JSR-375 was built. ==== Specification Lead diff --git a/spec/src/main/asciidoc/security-spec.adoc b/spec/src/main/asciidoc/security-spec.adoc index fadaf47..daa3cf8 100644 --- a/spec/src/main/asciidoc/security-spec.adoc +++ b/spec/src/main/asciidoc/security-spec.adoc @@ -3,8 +3,8 @@ // = Jakarta Security -:authors: Jakarta Security Team, https://projects.eclipse.org/projects/ee4j.es -:email: https://dev.eclipse.org/mailman/listinfo/security.enterprise-api-dev +:authors: Jakarta Security Community, https://projects.eclipse.org/projects/ee4j.es +:email: https://dev.eclipse.org/mailman/listinfo/es-dev :version-label!: :doctype: book :license: Eclipse Foundation Specification License v1.0 diff --git a/spec/src/main/asciidoc/securityContext.asciidoc b/spec/src/main/asciidoc/securityContext.asciidoc index b8769d6..193b57b 100644 --- a/spec/src/main/asciidoc/securityContext.asciidoc +++ b/spec/src/main/asciidoc/securityContext.asciidoc @@ -10,7 +10,7 @@ The Jakarta EE platform defines a declarative security model for protecting appl This specification provides an access point for programmatic security -- a security context -- represented by the _SecurityContext_ interface. -In this version of the specification, the _SecurityContext_ MUST be available in the Servlet container and the EJB container. Application servers MAY make _SecurityContext_ available in other containers, but are NOT REQUIRED to. +In this version of the specification, the _SecurityContext_ MUST be available in the Servlet container and the enterprise beans container. Application servers MAY make _SecurityContext_ available in other containers, but are NOT REQUIRED to. === Retrieving and Testing for Caller Data @@ -25,7 +25,7 @@ Principal getCallerPrincipal(); boolean isCallerInRole(String role); ---- -The _getCallerPrincipal()_ method retrieves the _Principal_ representing the caller. This is the container-specific representation of the caller principal, and the type may differ from the type of the caller principal originally established by an _HttpAuthenticationMechanism_. This method returns null for an unauthenticated caller. (Note that this behavior differs from the behavior of _EJBContext.getCallerPrincipal()_, which, per JSR-345, "Enterprise JavaBeans", version 3.2 [https://jcp.org/aboutJava/communityprocess/final/jsr345/index.html[EJB32]], returns a principal with a "product-specific unauthenticated principal name" to represent an unauthenticated caller.) +The _getCallerPrincipal()_ method retrieves the _Principal_ representing the caller. This is the container-specific representation of the caller principal, and the type may differ from the type of the caller principal originally established by an _HttpAuthenticationMechanism_. This method returns null for an unauthenticated caller. (Note that this behavior differs from the behavior of _EJBContext.getCallerPrincipal()_, which, per Jakarta Enterprise Beans spec, version 3.2 [https://jakarta.ee/specifications/enterprise-beans/3.2/[JEB32]], returns a principal with a "product-specific unauthenticated principal name" to represent an unauthenticated caller.) The _getPrincipalsByType()_ method retrieves all principals of the given type. This method can be used to retrieve an application-specific caller principal established during authentication. This method is primarily useful in the case that the container's caller principal is a different type than the application caller principal, and the application needs specific information behavior available only from the application principal. This method returns an empty _Set_ if the caller is unauthenticated, or if the requested type is not found. @@ -44,7 +44,7 @@ The _SecurityContext_ interface defines a method for programmatically testing ac boolean hasAccessToWebResource(String resource, String... methods); ---- -The _hasAccessToWebResource()_ method determines if the caller has access to the specified web resource for the specified HTTP methods, as determined by the security constraints configured for the application. See section 13.8 of [https://jcp.org/aboutJava/communityprocess/final/jsr340/index.html[SERVLET31]] for a description of web application security constraints. +The _hasAccessToWebResource()_ method determines if the caller has access to the specified web resource for the specified HTTP methods, as determined by the security constraints configured for the application. See section 13.8 of [https://jakarta.ee/specifications/servlet/4.0/[SERVLET40]] for a description of web application security constraints. The resource parameter is an _URLPatternSpec_ that identifies an application-specific web resource. See the javadoc for more detail. @@ -85,14 +85,14 @@ The _authenticate()_ method allows an application to signal to the container tha === Relationship to Other Specifications -The _SecurityContext_ implementation is a CDI bean, as defined by [https://jcp.org/aboutJava/communityprocess/mrel/jsr346/index.html[CDI12]]. +The _SecurityContext_ implementation is a CDI bean, as defined by [https://jakarta.ee/specifications/cdi/2.0/[CDI20]]. Various specifications in Jakarta EE provide similar or even identical methods to those provided be the _SecurityContext_. It is the intention of this specification to eventually supersede those methods and provide a cross-specification, platform alternative. The following gives an overview: * Servlet - _HttpServletRequest#getUserPrincipal_, _HttpServletRequest#isUserInRole_ -* EJB - _EJBContext#getCallerPrincipal_, _EJBContext#isCallerInRole_ -* JAX-WS - _WebServiceContext#getUserPrincipal_, _WebServiceContext#isUserInRole_ -* JAX-RS - _SecurityContext#getUserPrincipal_, _SecurityContext#isUserInRole_ -* JSF - _ExternalContext#getUserPrincipal_, _ExternalContext#isUserInRole_ -* CDI - _@Inject Principal_ -* WebSockets - _Session#getUserPrincipal_ +* Enterprise Beans - _EJBContext#getCallerPrincipal_, _EJBContext#isCallerInRole_ +* XML Web Services - _WebServiceContext#getUserPrincipal_, _WebServiceContext#isUserInRole_ +* RESTful Web Services - _SecurityContext#getUserPrincipal_, _SecurityContext#isUserInRole_ +* Server Faces - _ExternalContext#getUserPrincipal_, _ExternalContext#isUserInRole_ +* Contexts and Dependency Injection - _@Inject Principal_ +* WebSocket - _Session#getUserPrincipal_