Merge pull request #31380 from michelle-purcell/docs-security-diataxis

Fix abstract preamble in security topics

docs/src/main/asciidoc/security-oidc-bearer-authentication-concept.adoc

@@ -7,15 +7,17 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 = OpenID Connect (OIDC) Bearer authentication
 include::_attributes.adoc[]
 :categories: security,web
-:summary: To secure HTTP access to JAX-RS endpoints in your application, you can use Bearer authentication provided by the Quarkus OpenID Connect (OIDC) extension.
+
+Secure HTTP access to JAX-RS endpoints in your application with Bearer authentication by using the Quarkus OpenID Connect (OIDC) extension.
 
 == Overview of the Bearer authentication mechanism in Quarkus
 
-You can use the Quarkus OpenID Connect (OIDC) extension to secure your JAX-RS applications using Bearer authentication.
+Quarkus supports the Bearer authentication mechanism through the Quarkus OpenID Connect (OIDC) extension.
+
 The bearer tokens are issued by OIDC and OAuth 2.0 compliant authorization servers, such as link:https://www.keycloak.org[Keycloak].
 
 Bearer authentication is the process of authorizing HTTP requests based on the existence and validity of a bearer token.
-The bearer token provides information about the subject of the call which is used to determine whether or not an HTTP resource can be accessed.
+The bearer token provides information about the subject of the call, which is used to determine whether or not an HTTP resource can be accessed.
 
 The following diagrams outline the Bearer authentication mechanism in Quarkus:
 

docs/src/main/asciidoc/security-oidc-code-flow-authentication-concept.adoc

@@ -7,7 +7,8 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 = OpenID Connect authorization code flow mechanism for protecting web applications
 include::_attributes.adoc[]
 :categories: security,web
-:summary: To protect your web applications, you can use the authorization code flow mechanism provided by the Quarkus OpenID Connect (OIDC extension.
+
+To protect your web applications, you can use the authorization code flow mechanism provided by the Quarkus OpenID Connect (OIDC) extension.
 
 == Overview of the OIDC authorization code flow mechanism
 
@@ -28,7 +29,7 @@ image::authorization_code_flow.png[alt=Authorization Code Flow, width="60%", ali
 . The OIDC provider authenticates the user credentials entered and, if successful, issues an authorization code then redirects the user back to the Quarkus web-app with the code included as a query parameter.
 . The Quarkus web-app exchanges this authorization code with the OIDC provider for ID, access, and refresh tokens.
 
-The authorization code flow is completed and the Quarkus web-app uses the tokens issued to access information about the user and grant the relevant role-based authorization to that user.
+The authorization code flow is completed and the Quarkus web-app uses the tokens issued to access information about the user and grants the relevant role-based authorization to that user.
 The following tokens are issued:
 
 * ID token: The Quarkus web-app uses the user information in the ID token to enable the authenticated user to log in securely and to provide role-based access to the web-app.