Fixed title , abstract, sequence, and Maven bit

docs/src/main/asciidoc/security-getting-started.adoc

@@ -3,26 +3,23 @@ This guide is maintained in the main Quarkus repository
 and pull requests should be submitted there:
 https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 ////
-= Get started with security in Quarkus by using Basic authentication
-
+= Secure a Quarkus application with basic authentication
 include::./attributes.adoc[]
+:categories: get-started
+:toc: preamble
 
-To help you get started with security in Quarkus, this tutorial demonstrates how you can secure your Quarkus application endpoints by combining the xref:security-built-in-authentication.adoc#basic-auth[Quarkus built-in basic HTTP authentication] with the JPA identity provider.
-`IdentityProvider` verifies the authentication credentials to create a `SecurityIdentity` instance and authorizes secure access to the endpoint by using Role Based Access Control (RBAC). 
-[NOTE]
-====
-Completing these steps ensures that your Quarkus applications are more secure than just configuring users and roles in `application.properties` alone.
-====
+Secure your Quarkus application endpoints by combining the xref:security-built-in-authentication.adoc#basic-auth[Quarkus built-in basic HTTP authentication] with the JPA identity provider to enable role-based access control (RBAC). 
+The JPA `IdentityProvider` creates a `SecurityIdentity` instance, which is used during user authentication to verify and authorize access requests making your Quarkus application more secure.
 
-After you have completed this tutorial, you will be ready to apply more advanced security mechanisms in Quarkus, for example, use the `OpenID Connect` authentication mechanism.
+After you complete this tutorial, you will be ready to apply more advanced security mechanisms in Quarkus, for example, how to use the OpenID Connect (OIDC) authentication mechanism.
 
 == Prerequisites
 
 include::{includes}/prerequisites.adoc[]
 
-== About this security tutorial
+== What you will build
 
-In this example, you will build a microservice that provides the following endpoints:
+If you complete all of the steps in this tutorial, you will build a microservice that provides the following endpoints:
 
 [cols="20%,40% ",options="header"]
 |===
@@ -32,32 +29,36 @@ In this example, you will build a microservice that provides the following endpo
 | `/api/admin`| The `/api/users/me` endpoint is protected with RBAC and only users that have been granted the `user` role can access it. A JSON document with details about the user is returned as a response.
 |===
 
-== Get the completed tutorial resources 
+== How to complete this tutorial
+
+You can start from scratch and complete each of the numbered steps in sequence or you can bypass the basic setup steps that are already familiar to you:
+
+* To start from scratch, go to *Create a Maven project with the `security-jpa` extension*.
 
-Follow all of the instructions in each section of this tutorial. 
-However, if you want to go straight to the completed JPA security example resources for this tutorial, use the following steps:
+* To skip the basics and go straight to the end solution, either:
+** Clone the Git repository: `git clone {quickstarts-clone-url}`
+** Download the {quickstarts-archive-url}[archive]
+[TIP]
+====
+The solution is located in the `security-jpa-quickstart` {quickstarts-tree-url}/security-jpa-quickstart[directory].
+====
 
-. Retrieve the JPA security quick start resource files:
-.. Clone the repository: `git clone {quickstarts-clone-url}`.
-.. Download the {quickstarts-archive-url}[archive] file.
-. Open the `security-jpa-quickstart` {quickstarts-tree-url}/security-jpa-quickstart[directory].
+:sectnums:
+:sectnumlevels: 3
 
-== Add the `security-jpa` extension to your Maven project
+== Create a Maven project with the `security-jpa` extension
 
 For Quarkus security to be able to map your security source to JPA entities, ensure that the Maven project that is used in this tutorial includes the `security-jpa` extension.
-You can either create a new Maven project that also imports the `security-jpa` extension or you can add the extension to an existing Maven project.
-
-Complete one of the following steps:
+You can either create a new Maven project with the `security-jpa` extension or you can add the extension to an existing Maven project.
 
-* To create a new Maven project that imports the `security-jpa` extension, use the following command:
+* To create the Maven project, use the following command:
 
 :create-app-artifact-id: security-jpa-quickstart
 :create-app-extensions: security-jpa,jdbc-postgresql,resteasy-reactive,hibernate-orm-panache
 include::{includes}/devtools/create-app.adoc[]
 [NOTE]
 ====
 xref:hibernate-orm-panache.adoc[Hibernate ORM with Panache] is used to store your user identities but you can also use xref:hibernate-orm.adoc[Hibernate ORM].
-
 You must also add your preferred database connector library.
 The instructions in this example tutorial use a PostgreSQL database for the identity store.
 ====
@@ -66,7 +67,9 @@ The instructions in this example tutorial use a PostgreSQL database for the iden
 :add-extension-extensions: security-jpa
 include::{includes}/devtools/extension-add.adoc[]
 
-When you run this command, the following XML is added to your build file:
+=== Verification
+
+When you run either command, the following XML is added to your build file:
 
 [source,xml,role="primary asciidoc-tabs-target-sync-cli asciidoc-tabs-target-sync-maven"]
 .pom.xml
@@ -380,7 +383,7 @@ While developing your application, you can also start to add tests one by one an
 `Dev Services for PostgreSQL` supports testing while you develop by providing a separate `PostgreSQL` test container that does not conflict with the `devmode` container.
 ====
 
-=== Testing your application by using `curl` or a browser
+=== Test your application by using `curl` or a browser
 
 Use the following example to start the PostgreSQL server:
 [source,bash]
@@ -391,7 +394,7 @@ docker run --rm=true --name security-getting-started -e POSTGRES_USER=quarkus \
 ----
 === Compile and run the application
 
-Compile and run the application by using one of the following methods:
+Compile and run your Quarkus application by using one of the following methods:
 
 ==== JVM mode
 
@@ -416,7 +419,7 @@ Run the application:
 ./target/security-jpa-quickstart-runner
 ----
 
-=== Access and test the security of the application:
+=== Access and test the application security
 
 When your application is running, you can access your application by using one of the following `curl` commands. 
 You can also access the same endpoint URLs by using a browser.
@@ -478,7 +481,7 @@ Content-Type: text/html;charset=UTF-8
 Forbidden%
 ----
 
-Finally, using the user `user` works and the security context contains the principal details, for example, user name.
+Finally, the user name `user` is authorized and the security context contains the principal details, for example, the user name.
 
 [source,shell]
 ----
@@ -490,9 +493,11 @@ Content-Type: text/plain;charset=UTF-8
 user%
 ----
 
+:sectnums!:
+
 == JPA security information 
 
-Now that you have successfully run and tested the security quick start project, use the following information to further explore the security features of Quarkus and the JPA identity store.
+Now that you have successfully run and tested the security quick start project, you are ready to explore more security features of Quarkus and the JPA identity store.
 
 === Supported model types
 
@@ -539,12 +544,12 @@ By default, passwords are stored and hashed by using https://en.wikipedia.org/wi
 https://en.wikipedia.org/wiki/Crypt_(C)[Modular Crypt Format] (MCF).
 
 When you need to create a hashed password we provide the convenient `String BcryptUtil.bcryptHash(String password)`
-function, which defaults to creating a random salt and hashing in 10 iterations. You can also specify the number of iterations and the salt.
+function, which defaults to creating a random salt and hashing in 10 iterations. 
+You can also specify the number of iterations and the salt.
 
-NOTE: When you use MCF, you don't need dedicated columns to store the hashing algorithm, the iterations count, or the salt because
-they are all stored in the hashed value.
+NOTE: When you use MCF, you don't need dedicated columns to store the hashing algorithm, the iterations count, or the salt because they are all stored in the hashed value.
 
-You can also store passwords by using a different hashing algorithm, for example,  `@Password(value = PasswordType.CUSTOM, provider = CustomPasswordProvider.class)`, as outlined in the following code snippet:
+You can also store passwords by using a different hashing algorithm, for example, `@Password(value = PasswordType.CUSTOM, provider = CustomPasswordProvider.class)`, as outlined in the following code snippet:
 
 [source,java]
 ----
@@ -577,10 +582,12 @@ public class CustomPasswordProvider implements PasswordProvider {
 }
 ----
 
-WARNING: In a test environment, you can also store passwords in plain text by using `@Password(PasswordType.CLEAR)`. For applications running in production, do not store passwords in plain text.
+WARNING: In a test environment, you can also store passwords in plain text by using `@Password(PasswordType.CLEAR)`.
+For applications running in production, do not store passwords in plain text.
 
 == What's next
 
+Congratulations!
 You have learned how to create and test a secure Quarkus application by combining the xref:security-built-in-authentication.adoc#basic-auth[Quarkus built-in basic HTTP authentication] with the JPA identity provider.
 
 After you have completed this tutorial, explore some of the more advanced security mechanisms in Quarkus.