DOCS: Updated SE security docs (#4687)

docs/includes/security/helidon-endpoints.adoc

@@ -18,7 +18,7 @@
 
 ifndef::rootdir[:rootdir: {docdir}/../..]
 
-=== Protecting Helidon endpoints
+=== Protecting Helidon Endpoints
 :description: Helidon Security Endpoints
 :keywords: helidon, security, static, content, health, openapi, metrics
 
@@ -35,12 +35,12 @@ can be protected only through Security integration with WebServer.
 The following section describes configuration of such protection using configuration files,
  in this case using a `yaml` file, as it provides a tree structure.
 
-==== Configuring endpoint protection
+==== Configuring Endpoint Protection
 
 The configuration is usually placed under `security.web-server` (this can be
 customized in Helidon SE).
 
-The following shows an example we will explain in detail:
+The following example shows how to configure the application.yaml using customized setting:
 
 [source,yaml]
 .application.yaml

docs/includes/security/jep-290.adoc

@@ -26,24 +26,24 @@ ifndef::rootdir[:rootdir: {docdir}/../..]
 == Contents
 
 - <<Overview, Overview>>
-- <<Deserialization setup, Deserialization setup>>
-- <<System property configuration, System property configuration>>
-- <<Programmatic configuration, Programmatic configuration>>
+- <<Deserialization Setup, Deserialization Setup>>
+- <<System Property Configuration, System Property Configuration>>
+- <<Programmatic Configuration, Programmatic Configuration>>
 
 == Overview
 
 link:https://openjdk.org/jeps/290[JEP-290] brought support for deserialization filters to Java programming language.
 Such filtering allows us to control which classes may be deserialized using Java serialization.
 
-== Deserialization setup
+== Deserialization Setup
 
 Helidon default settings forbids any deserialization except for patterns defined in a `pattern`
 property of any `{metainf}` on classpath. The patterns are semicolon delimited strings, such as `io.myapp.&#42;&#42;;java.util.HashMap` (any subpackage of `io.myapp` and class `java.util.HashMap`).
 Helidon will *always* add a deny-all filter pattern to the end of the pattern string (to make sure we exclude any unspecified class - we only operate on whitelists)
 
 These defaults can be modified either through system properties, or programmatically.
 
-== System property configuration
+== System Property Configuration
 The following system properties can be used to control deserialization in Helidon:
 
 .System properties
@@ -81,7 +81,7 @@ Options:
 
 |===
 
-== Programmatic configuration
+== Programmatic Configuration
 
 Custom `SerializationConfig` may be registered, but it *must* be done before Helidon server is started.
 

docs/includes/security/providers/abac.adoc

@@ -23,9 +23,13 @@ ifndef::rootdir[:rootdir: {docdir}/../../..]
 :keywords: helidon, security, authorization, abac
 :feature-name: ABAC Security Provider
 
-Attribute based access control authorization provider.
+Attribute-based Access Control (ABAC) authorization provider provides security and authorization service implementations. 
 
-==== Setup
+==== Overview
+
+include::{rootdir}/config/io_helidon_security_providers_abac_AbacProvider.adoc[leveloffset=+2,tag=config]
+
+==== Maven Dependency
 
 [source,xml]
 .Maven dependency
@@ -36,11 +40,9 @@ Attribute based access control authorization provider.
 </dependency>
 ----
 
-==== Overview
 
-include::{rootdir}/config/io_helidon_security_providers_abac_AbacProvider.adoc[leveloffset=+2,tag=config]
 
-==== Example code
+==== Examples
 
 See the link:{helidon-github-tree-url}/examples/security/attribute-based-access-control[example] on GitHub.
 
@@ -52,7 +54,7 @@ security:
     - abac:
 ----
 
-==== Configuration options
+==== Configuration Options
 The following table shows all configuration options of the provider and their default values
 
 [cols="2,2,5"]
@@ -64,7 +66,7 @@ The following table shows all configuration options of the provider and their de
 |`fail-if-none-validated` |`true` |"None validated" means: there was not a single attribute that was validated
 |===
 
-==== How does it work?
+==== Usage
 ABAC uses available validators and validates them against attributes of the authenticated
  user.
 
@@ -153,7 +155,7 @@ public class AbacResource {
 }
 ----
 
-===== Interaction with JAX-RS sub-resource locators
+===== Interaction with JAX-RS Sub-Resource Locators
 When using sub-resource locators in JAX-RS, the roles allowed are collected from each "level" of
 execution:
 - Application class annotations

docs/se/security/containers-integration.adoc

@@ -16,25 +16,23 @@
 
 ///////////////////////////////////////////////////////////////////////////////
 
-= Containers Integration
+= Cloud Security Container Integrations
 :description: Helidon Security containers integration
 :keywords: helidon, security
 :rootdir: {docdir}/../..
 
 include::{rootdir}/includes/se.adoc[]
 
-== Contents
 
-- <<Cloud Security Container Integrations,Cloud Security Container Integrations>>
-- <<Reference,Reference>>
 
-== Cloud Security Container Integrations
+The following cloud security containers are integrated with Helidon Security:
 
-The following containers are integrated with Helidon Security:
+- <<WebServer, WebServer>>
+- <<Jersey, Jersey >>
 
-=== Web server
+== WebServer
 
-Integration of xref:../webserver.adoc[reactive web server]
+To integrate xref:../webserver.adoc[reactive web server], add the following dependency to your project's pom.xml file:
 
 [source,xml]
 .Maven Dependency
@@ -45,12 +43,12 @@ Integration of xref:../webserver.adoc[reactive web server]
 </dependency>
 ----
 
-==== Bootstrapping
+=== Configure Security with WebServer
 
-There are two steps to configure security with web server:
+There are two steps to configure security with WebServer:
 
-1. Create security instance and register it with server
-2. Protect routes of web server with various security features
+1. Create a security instance and register it with the server.
+2. Protect server routes with optional security features.
 
 [source,java]
 .Example using builders
@@ -95,9 +93,9 @@ security.web-server:
 
 include::{rootdir}/includes/security/helidon-endpoints.adoc[]
 
-=== Jersey
+== Jersey
 
-Integration of Jersey (JAX-RS implementation) both for inbound and outbound security.
+Jersey (JAX-RS implementation) can be configured for both inbound and outbound security.
 
 [source,xml]
 .Maven Dependency
@@ -108,7 +106,7 @@ Integration of Jersey (JAX-RS implementation) both for inbound and outbound secu
 </dependency>
 ----
 
-==== Inbound security
+=== Inbound security
 
 [source,java]
 .Integrate with Jersey
@@ -120,9 +118,9 @@ ResourceConfig resourceConfig = new ResourceConfig()
     .register(new io.helidon.security.jersey.SecurityFeature(security));
 ----
 
-=== Protecting a resource
+=== Secure a Resource Method
 
-The current approach does not have a configuration option. The security must be
+The current approach does not have a configuration option so security must be
  configured through annotations.
 Security currently supports @Authenticated and @Authorized. When a resource is annotated with one of these
  annotations (application class, resource class, or resource method), security will
@@ -142,7 +140,7 @@ public String getHelloName(@PathParam("name") String name) {
 }
 ----
 
-=== Access context
+=== Access Context
 
 [source,java]
 .Support in a JAX-RS resource
@@ -154,7 +152,7 @@ private SecurityContext securityContext;
 ----
 
 
-==== Outbound security
+=== Outbound Security
 Outbound security is automatically registered with Jersey client.
 The provider must have outbound security configured for identity to be propagated.
 

docs/se/security/extensibility.adoc

@@ -25,11 +25,11 @@ This guide describes how you can extend the Security component.
 
 The component has the following extension points:
 
-* Security providers
-* Provider selection policy
-* Integration with a framework
+- <<Security Providers, Security Providers>>
+- <<Provider Selection Policy, Provider Selection Policy>>
+- <<Framework Integration, Framework Integration>>
 
-== Security providers
+== Security Providers
 You can build a custom provider for each type of security concept supported.
 By default, each provider is asynchronous. For simple cases, a class
 exists in "spi" package to help implement a synchronous approach:
@@ -45,7 +45,7 @@ You have two options:
 The second option allows for easier configuration, as the configuration key can be
  used without a class definition and creates a default name of a provider.
 
-=== Authentication provider
+=== Authentication Provider
 To create a custom authentication provider, create a class that implements
 `io.helidon.security.spi.AuthenticationProvider`.
 Implementation is responsible for taking a request and asserting a subject
@@ -55,7 +55,7 @@ In case the protocol is multi-request (e.g. challenge for basic authentication),
  default semantics of these is HTTP, though providers may exist that are not
  HTTP specific.
 
-=== Authorization provider
+=== Authorization Provider
 To create a custom authorization provider, create a class that implements
 `io.helidon.security.spi.AuthorizationProvider`.
 Implementation is responsible for taking a request and checking whether the
@@ -65,13 +65,13 @@ Implementation is responsible for taking a request and checking whether the
 If authentication is configured, the Security component guarantees it resolved
  before authorization.
 
-=== Outbound security provider
+=== Outbound Security Provider
 To create a custom outbound security provider, create a class that implements
 `io.helidon.security.spi.OutboundSecurityProvider`.
 Implementation can update outgoing message headers to handle
 security for an outgoing request (e.g. identity propagation, mapping etc.).
 
-=== Audit provider
+=== Audit Provider
 To create a custom audit provider, create a class that implements
 `io.helidon.security.spi.AuditProvider`.
 Security component feeds each audit provider all messages from all components
@@ -87,7 +87,7 @@ Implementation may do whatever desired with these messages, e.g.:
 * forward them to an audit component
 * discard them
 
-== Provider selection policy
+== Provider Selection Policy
 Each request is processed by a single authentication and/or authorization
  provider. The selection policy provides the security component information about
  which provider to use. Out of the box, there are three policies:
@@ -103,7 +103,7 @@ Each request is processed by a single authentication and/or authorization
 To create a custom provider selection policy, create a class that implements
 "io.helidon.security.spi.ProviderSelectionPolicy".
 
-== Framework integration
+== Framework Integration
 The Security component supports integration with Helidon WebServer (`helidon-security-integration-webserver`)
  and with Jersey (`helidon-security-integration-jersey`).
 

docs/se/security/introduction.adoc

@@ -26,15 +26,11 @@ include::{rootdir}/includes/se.adoc[]
 
 Helidon Security provides authentication, authorization and auditing for your Helidon application.
 
-include::{rootdir}/includes/dependencies.adoc[]
+== Contents
 
-[source,xml]
-----
-<dependency>
-    <groupId>io.helidon.security</groupId>
-    <artifactId>helidon-security</artifactId>
-</dependency>
-----
+- <<Overview, Overview>>
+- <<Maven Coordinates, Maven Coordinates>>
+- <<Usage, Usage>>
 
 == Overview
 
@@ -44,7 +40,7 @@ Helidon Security provides the following features
  security Subject with Principal and Grants. Principal represents current user/service.
  Grant may represent a Role, Scope etc.
  Responsibility to create Principals and Grants lies with with AuthenticationProvider
- SPI. The following Principals are expected and supported out of the box:
+ SPI. The following Principals are expected and supported by default:
 .. UserPrincipal - the party is an end-user (e.g. a person) - there can be zero to
  one user principals in a subject
 .. ServicePrincipal - the party is a service (e.g. a computer program) - there can
@@ -69,7 +65,19 @@ Security module is quite HTTP centric (as most common use cases are related to
  protocol). Nevertheless there may be security providers that only make sense with
  HTTP (such as HTTP digest authentication).
 
-== How to use
+
+include::{rootdir}/includes/dependencies.adoc[]
+
+[source,xml]
+----
+<dependency>
+    <groupId>io.helidon.security</groupId>
+    <artifactId>helidon-security</artifactId>
+</dependency>
+----
+
+
+== Usage
 
 To integrate with a container, or to use Security standalone, we must
  create an instance of security.
@@ -114,7 +122,7 @@ context.atnClientBuilder()
                 });
 ----
 
-=== Builder pattern
+=== Builder Pattern
 
 [source,java]
 .Security through a builder
@@ -125,7 +133,7 @@ Security security = Security.builder()
         .build();
 ----
 
-=== Configuration pattern
+=== Configuration Pattern
 
 See xref:tools.adoc[Secure config] for details about encrypting passwords in
  configuration files.
@@ -155,7 +163,7 @@ security:
         roles: ["user"]
 ----
 
-==== Overriding configuration
+==== Overriding Configuration
 
 When a configuration needs to be overridden, we may have problems with the list
 type of the `providers` configuration. To simplify overrides using properties,
@@ -171,7 +179,7 @@ security.providers.1.header-atn.authenticate=false
 Would explicitly override the second provider (`http-basic-auth` in example above) with
 `header-atn` provider. Note that the `type` and the key of the provider must match.
 
-=== Hybrid pattern (Builder & Configuration)
+=== Hybrid Pattern (Builder with Configuration)
 
 [source,java]
 .Security from configuration and builder

docs/se/security/providers.adoc

@@ -27,6 +27,7 @@ include::{rootdir}/includes/se.adoc[]
 == Contents
 
 - <<Implemented Security Providers, Implemented Security Providers>>
+-  <<Maven Coordinates, Maven Coordinates>>
 - <<Reference, Reference>>
 
 == Implemented Security Providers
@@ -58,7 +59,7 @@ The following providers are no longer evolved:
 === OIDC Provider
 Open ID Connect security provider.
 
-==== Setup
+=== Maven Coordinates
 [source,xml]
 .Maven dependency
 ----