First pass at security (#167)

* First pass at security

* applied feedback

Signed-off-by: Guillermo González de Agüero <z06.guillermo@gmail.com>

src/main/jbake/content/security-advanced002.adoc

@@ -49,7 +49,7 @@ deployment descriptor:
     <auth-method>CLIENT-CERT</auth-method>
 </login-config>
 ----
-The Jakarta EE Security API provides an alternative means to configure client authentication
+Jakarta Security provides an alternative means to configure client authentication
 using the `HttpAuthenticationMechanism` interface. This
 interface defines an SPI for writing
 authentication mechanisms that can be provided with an application and

src/main/jbake/content/security-advanced004.adoc

@@ -15,7 +15,7 @@ Securing HTTP Resources
 When a request URI is matched by multiple constrained URL patterns, the
 constraints that apply to the request are those that are associated with
 the best matching URL pattern. The servlet matching rules defined in
-Chapter 12, "Mapping Requests To Servlets," in the Java Servlet 4.0
+Chapter 12, "Mapping Requests To Servlets," in the Jakarta Servlet 4.0
 Specification, are used to determine the best matching URL pattern to
 the request URI. No protection requirements apply to a request URI that
 is not matched by a constrained URL pattern. The HTTP method of the
@@ -33,7 +33,7 @@ methods, including HTTP extension methods.
 When constraints with different protection requirements apply to the
 same combination of URL patterns and HTTP methods, the rules for
 combining the protection requirements are as defined in Section 13.8.1,
-"Combining Constraints," in the Java Servlet 4.0 Specification.
+"Combining Constraints," in the Jakarta Servlet 4.0 Specification.
 
 Follow these guidelines to properly secure a web application.
 

src/main/jbake/content/security-advanced005.adoc

@@ -91,7 +91,7 @@ Using Programmatic Login
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 Programmatic login enables the client code to supply user credentials.
-If you are using an EJB client, you can use the
+If you are using an enterprise bean client, you can use the
 `com.sun.appserv.security.ProgrammaticLogin` class with its convenient
 `login` and `logout` methods. Programmatic login is specific to a
 server.

src/main/jbake/content/security-advanced007.adoc

@@ -79,7 +79,7 @@ it from being read in transit.
 Specifying Non-Default Principal-to-Role Mapping in the Deployment Descriptor
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The Jakarta EE Security API requires that group principal names be mapped to
+Jakarta Security requires that group principal names be mapped to
 roles of the same name by default. GlassFish adheres to this standard, by default,
 and provides group principal to role mapping. Implementations of the standard
 can, however, provide mechanisms to configure a different default.

src/main/jbake/content/security-advanced008.adoc

@@ -17,16 +17,16 @@ see
 
 * Documentation on the `keytool` command:
 +
-`http://docs.oracle.com/javase/7/docs/technotes/tools/solaris/keytool.html`
+`https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html`
 * Java Authentication and Authorization Service (JAAS) Reference Guide:
 +
 `http://docs.oracle.com/javase/7/docs/technotes/guides/security/jaas/JAASRefGuide.html`
 * Java Authentication and Authorization Service (JAAS): LoginModule
 Developer's Guide:
 +
-`http://docs.oracle.com/javase/7/docs/technotes/guides/security/jaas/JAASLMDevGuide.html`
+`https://docs.oracle.com/javase/8/docs/technotes/guides/security/jaas/JAASLMDevGuide.html`
 * Documentation on security policy file syntax:
 +
-`http://docs.oracle.com/javase/7/docs/technotes/guides/security/PolicyFiles.html#FileSyntax`
+`https://docs.oracle.com/javase/8/docs/technotes/guides/security/PolicyFiles.html#FileSyntax`
 
 

src/main/jbake/content/security-api.adoc

@@ -1,26 +1,26 @@
 type=page
 status=published
-title=Using the Jakarta EE Security API
+title=Using Jakarta Security
 next=security-api001.html
 prev=security-jakartaee003.html
 ~~~~~~
-= Using the Jakarta EE Security API
+= Using Jakarta Security
 
 
 
 [[using-the-jakarta-ee-security-api]]
-53 Using the Jakarta EE Security API
-------------------------------------
+53 Using Jakarta Security
+-------------------------
 
 
 This chapter describes the authentication and credential validation
-functionality provided by the Jakarta EE Security API. The API also
+functionality provided by Jakarta Security. The API also
 defines a SecurityContext access point for programmatic security.
 
 
 The following topics are addressed here:
 
-* link:security-api001.html#about-the-jakarta-ee-security-api[About the Jakarta EE Security API]
+* link:security-api001.html#about-the-jakarta-ee-security-api[About Jakarta Security]
 * link:security-api002.html#overview-of-the-http-auth-mech-int[Overview of the HTTP Authentication Mechanism Interface]
 * link:security-api003.html#overview-of-the-identity-store-interfaces[Overview of the Identity Store Interfaces]
 * link:security-api004.html#running-the-built-in-database-identity-store-example[Running the Built-In Database Identity Store Example]

src/main/jbake/content/security-api001.adoc

@@ -1,24 +1,24 @@
 type=page
 status=published
-title=About the Jakarta EE Security API
+title=About Jakarta Security
 next=security-api002.html
 prev=security-api.html
 ~~~~~~
-= About the Jakarta EE Security API
+= About the Jakarta Security
 
 [[about-the-jakarta-ee-security-api]]
-About the Jakarta EE Security API
----------------------------------
+About Jakarta Security
+----------------------
 
-Jakarta EE includes support for JSR 375, which defines portable, plug-in interfaces
+Jakarta EE includes support for Jakarta Security, which defines portable, plug-in interfaces
 for authentication and identity stores, and a new injectable-type SecurityContext
 interface that provides an access point for programmatic security. You can use
 the built-in implementations of these APIs, or define custom
 implementations.
 
-The Jakarta EE Security API contains the following packages:
+Jakarta Security contains the following packages:
 
-* The `javax.security.enterprise` package is the main Jakarta EE security API package
+* The `javax.security.enterprise` package is the main Jakarta Security package
 and contains classes and interfaces that span authentication, authorization, and
 identity concerns. link:#main-classes-and-interfaces-in-enterprise[Table 51-1] lists
 the main class and interfaces in this package.

src/main/jbake/content/security-api002.adoc

@@ -38,21 +38,20 @@ During bean discovery, the servlet container looks for a bean that implements
 `HttpAuthenticationMechanism` -- there should be only one per application -- and,
 if found, arranges for it to be deployed to authenticate the application's callers.
 
-The servlet container leverages JASPIC, the Java Authentication Service
-Provider Interface for Containers, to deploy authentication mechanisms.
-The container provides a JASPIC Server Auth Module (SAM) that can delegate to an
+The servlet container leverages Jakarta Authentication  to deploy authentication mechanisms.
+The container provides a Jakarta Authentication Server Auth Module (SAM) that can delegate to an
 `HttpAuthenticationMechanism`, and arranges for that "bridge" SAM to be registered
-with the JASPIC `AuthConfigFactory`. At runtime, normal JASPIC processing invokes
+with the Jakarta Authentication `AuthConfigFactory`. At runtime, normal Jakarta Authentication processing invokes
 the bridge SAM, which then delegates to the `HttpAuthenticationMechanism` to
 perform the authentication and drive any necessary dialog with the caller, or with
 third parties involved in the authentication protocol flow.
 
 The HttpAuthenticationMechanism interface defines the following three methods,
-which correspond to the three methods defined by the JASPIC ServerAuth interface.
-When one of the JASPIC methods is invoked on the bridge SAM, it delegates to the
+which correspond to the three methods defined by the Jakarta Authentication ServerAuth interface.
+When one of the Jakarta Authentication methods is invoked on the bridge SAM, it delegates to the
 corresponding method of the `HttpAuthenticationMechanism`. Although the method names
 are identical, the method signatures are not; the bridge SAM maps back and forth
-between the parameters passed to it by the JASPIC framework, and the parameters
+between the parameters passed to it by the Jakarta Authentication framework, and the parameters
 expected by an `HttpAuthenticationMechanism`.
 
 * `validateRequest()` -- validate an incoming request and authenticates the caller.
@@ -66,7 +65,7 @@ often be sufficient.
 
 The following annotations can be used to add additional behaviors to an `HttpAuthenticationMechanism`:
 
-* `AutoApplySession` -- indicates that the JASPIC `registerSession` functionality
+* `AutoApplySession` -- indicates that the Jakarta Authentication `registerSession` functionality
 should be enabled such that the the caller's authenticated identity is
 persisted in the caller's servlet session.
 * `LoginToContinue` -- mechanism to specify properties for FORM login --

src/main/jbake/content/security-api003.adoc

@@ -69,7 +69,7 @@ invokes on it. The `IdentityStoreHandler`, in turn, looks up the available Ident
 and invokes on them to determine the aggregate result.
 
 There is a built-in `IdentityStoreHandler` that implements a standard algorithm
-defined by JSR-375. The JSR-375 specification provides a full description of
+defined by Jakarta Security. The Jakarta Security specification provides a full description of
 the algorithm, but it can be roughly summarized as follows:
 
 * Iterate over the available validating IdentityStores, in priority order,
@@ -229,7 +229,7 @@ application's `HttpAuthenticationMechanism`, which indicates that a
 A container-supplied interceptor then intercepts calls to the `HttpAuthenticationMechanism`,
 invokes the `RememberMeIdentityStore` as necessary before and after calls to the
 authentication mechanism, and ensures that the user's identity is correctly
-set for the session. The JSR-375 specification provides a detailed description
+set for the session. The Jakarta Security specification provides a detailed description
 of the required interceptor behavior.
 
 Implementations of `RememberMeIdentityStore` should take care to manage tokens

src/main/jbake/content/security-api004.adoc

@@ -21,9 +21,9 @@ Topics include:
 [[overview-of-the-built-in-database-identity-store-example]]
 Overview of the Built-In Database Identity Store Example
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-JSR 375 mandates that a Jakarta EE container MUST support a built-in `IdentityStore`
+Jakarta Security mandates that a Jakarta EE container MUST support a built-in `IdentityStore`
 backed by a database. To support this mandatory requirement, `DatabaseIdentityStore`
-is bundled with the GlassFish-RI.
+is bundled with GlassFish.
 
 This example demonstrates how you can configure a `DatabaseIdentityStore` to point
 to a backend database and then use it as an IdentityStore. The authentication mechanism used is
@@ -225,7 +225,7 @@ public class Servlet extends HttpServlet {
 }
 ----
 
-In GlassFish 5.0, group to role mapping is enabled by default. Therefore, you do
+In GlassFish 5.1, group to role mapping is enabled by default. Therefore, you do
 not need to bundle web.xml with the application to provide mapping between
 roles and groups.
 

src/main/jbake/content/security-intro.adoc

@@ -22,14 +22,14 @@ chapter on security in the Jakarta EE 8 specification.
 a|
 *Note:*
 
-The SDK may include additional material demonstrating key features of the Jakarta EE Security API. Please check the latest SDK release notes for additional details.
+The SDK may include additional material demonstrating key features of Jakarta Security. Please check the latest SDK release notes for additional details.
 
 |=======================================================================
 
 
 The following topics are addressed here:
 
-* link:security-intro001.html#BNBWK[Overview of Jakarta EE Security]
+* link:security-intro001.html#BNBWK[Overview of Jakarta Security]
 * link:security-intro002.html#BNBWY[Security Mechanisms]
 * link:security-intro003.html#BNBXE[Securing Containers]
 * link:security-intro004.html#BNBXI[Securing GlassFish Server]

src/main/jbake/content/security-intro001.adoc

@@ -1,15 +1,15 @@
 type=page
 status=published
-title=Overview of Jakarta EE Security
+title=Overview of Jakarta Security
 next=security-intro002.html
 prev=security-intro.html
 ~~~~~~
-= Overview of Jakarta EE Security
+= Overview of Jakarta Security
 
 [[BNBWK]][[overview-of-jakarta-ee-security]]
 
-Overview of Jakarta EE Security
--------------------------------
+Overview of Jakarta Security
+----------------------------
 
 Every enterprise that has either sensitive resources that can be
 accessed by many users or resources that traverse unprotected, open
@@ -59,17 +59,17 @@ and mechanisms can be found in the chapter on security in the Jakarta EE 8
 specification.
 
 Other chapters in this Part discuss security requirements in web tier
-and enterprise tier applications, and the Jakarta EE Security API.
+and enterprise tier applications, and the Jakarta Security.
 
 * link:security-webtier.html#BNCAS[Chapter 51, "Getting Started Securing
 Web Applications"] explains how to add security to web components, such
 as servlets.
 * link:security-jakartaee.html#BNBYK[Chapter 52, "Getting Started Securing
 Enterprise Applications"] explains how to add security to Jakarta EE
 components, such as enterprise beans and application clients.
-* link:security-api.html#using-the-jakarta-ee-security-api[53 Using the Jakarta EE Security API]
+* link:security-api.html#using-the-jakarta-ee-security-api[53 Using Jakarta Security]
 describes the authentication and credential validation funtionality provided by
-the Jakarta EE security API, and provides examples.
+Jakarta Security, and provides examples.
 
 [[BNBWL]][[a-simple-application-security-walkthrough]]
 
@@ -182,7 +182,7 @@ The web page performs the remote method call to the enterprise bean,
 using the user's credential to establish a secure association between
 the web page and the enterprise bean, as shown in link:#BNBWV[Figure
 50-5]. The association is implemented as two related security contexts:
-one in the web server and one in the EJB container.
+one in the web server and one in the enterprise bean container.
 
 [[BNBWV]]
 
@@ -191,11 +191,11 @@ image:img/jakartaeett_dt_043.png[
 "Diagram of authorization process between web component and enterprise
 bean"]
 
-The EJB container is responsible for enforcing access control on the
+The enterprise container is responsible for enforcing access control on the
 enterprise bean method. The container consults the security policy
 associated with the enterprise bean to determine the security roles that
 are permitted access to the method. The security policy is derived from
-annotations or from the deployment descriptor. For each role, the EJB
+annotations or from the deployment descriptor. For each role, the enterprise bean
 container determines whether it can map the caller to the role by using
 the security context associated with the call.
 

src/main/jbake/content/security-intro002.adoc

@@ -65,7 +65,7 @@ certificates, and policy files; generating and verifying JAR signatures;
 and obtaining, listing, and managing Kerberos tickets.
 
 For more information on Java SE security, visit
-`http://docs.oracle.com/javase/7/docs/technotes/guides/security/`.
+`http://docs.oracle.com/javase/8/docs/technotes/guides/security/`.
 
 [[BNBXA]][[jakarta-ee-security-mechanisms]]
 
@@ -92,7 +92,7 @@ application firewalls can be used to enhance application protection by
 protecting the communication stream and all associated application
 resources from attacks.
 
-Jakarta EE security is easy to implement and configure and can offer
+Jakarta Security is easy to implement and configure and can offer
 fine-grained access control to application functions and data. However,
 as is inherent to security applied at the application layer, security
 properties are not transferable to applications running in other

src/main/jbake/content/security-intro003.adoc

@@ -72,8 +72,8 @@ descriptors discussed in this tutorial include the following.
 `web.xml`.
 +
 The schema for web component deployment descriptors is provided in
-Chapter 14 of the Java Servlet 4.0 specification (JSR 369), which can be
-downloaded from `http://jcp.org/en/jsr/detail?id=369`.
+Chapter 14 of the Jakarta Servlet 4.0 specification, which can be
+downloaded from `https://jakarta.ee/specifications/servlet/4.0/`.
 * Enterprise JavaBeans components may use an EJB deployment descriptor
 named `META-INF/ejb-jar.xml`, contained in the EJB JAR file.
 +

src/main/jbake/content/security-intro004.adoc

@@ -32,7 +32,7 @@ configured, and used in access decisions.
 * Using pluggable audit modules.
 * Customizing authentication mechanisms. All implementations of Jakarta EE
 8 compatible web containers are required to support the Servlet Profile
-of JSR 196, which offers an avenue for customizing the authentication
+of Jakarta Authentication, which offers an avenue for customizing the authentication
 mechanism applied by the web container on behalf of one or more
 applications.
 * Setting and changing policy permissions for an application.

src/main/jbake/content/security-intro005.adoc

@@ -350,7 +350,7 @@ architecture provides a mechanism for mapping the roles defined in the
 application to the users or groups defined in the runtime realm.
 
 The role names used in the application are often the same as the group
-names defined in GlassFish Server. The Jakarta EE Security API requires that
+names defined in GlassFish Server. Jakarta Security requires that
 group principal names are mapped
 to roles of the same name by default. Accordingly, the *Default Principal To Role Mapping* setting
 is enabled by default on the Security page of

src/main/jbake/content/security-intro007.adoc

@@ -15,25 +15,25 @@ For more information about security in Jakarta EE applications, see
 
 * Jakarta EE 8 specification:
 +
-`http://jcp.org/en/jsr/detail?id=366`
-* Jakarta EE Security API 1.0:
+``https://jakarta.ee/specifications/platform/8/
+* Jakarta Security 1.0:
 +
-`http://jcp.org/en/jsr/detail?id=375`
-* Java Authentication Service Provider Interface for Containers (JASPIC) 1.1:
+`https://jakarta.ee/specifications/security/1.0/`
+* Jakarta Authentication 1.1:
 +
-`https://jcp.org/en/jsr/detail?id=196`
-* Enterprise JavaBeans 3.2 specification:
+`https://jakarta.ee/specifications/enterprise-beans/3.2/`
+* Jakarta Enterprise Beans 3.2 specification:
 +
-`http://jcp.org/en/jsr/detail?id=345`
-* Implementing Enterprise Web Services 1.3 specification:
+`https://jakarta.ee/specifications/authentication/1.1/`
+* Jakarta Enterprise Web Services 1.4 specification:
 +
-`http://jcp.org/en/jsr/detail?id=109`
+`https://jakarta.ee/specifications/enterprise-ws/1.4/`
 * Java SE security information:
 +
 `http://docs.oracle.com/javase/8/docs/technotes/guides/security/`
-* Java Servlet 4.0 specification:
+* Jakarta Servlet 4.0 specification:
 +
-`http://jcp.org/en/jsr/detail?id=369`
-* Java Authorization Contract for Containers 1.5 specification:
+`https://jakarta.ee/specifications/servlet/4.0/`
+* Jakarta Authorization 1.5 specification:
 +
-`http://jcp.org/en/jsr/detail?id=115`
+`https://jakarta.ee/specifications/authorization/1.5/`