Merge pull request #34320 from michelle-purcell/SECURITY-DOCS-BASIC-AUTH

Minor doc enhancements to Security Basic Auth docs

docs/src/main/asciidoc/security-basic-authentication-howto.adoc

@@ -8,46 +8,47 @@ Enable xref:security-basic-authentication.adoc[Basic authentication] for your Qu
 
 == Prerequisites
 
-* You have installed at least one extension that provides an `IdentityProvider` based on username and password, such as xref:security-jdbc.adoc[Elytron JDBC].
+* You have installed at least one extension that provides an `IdentityProvider` based on username and password, such as link:{url-quarkusio-guides}security-jdbc[Elytron JDBC].
 
 == Procedure
 
-. Enable Basic authentication by setting the value of `quarkus.http.auth.basic` property to `true`.
+. Enable Basic authentication by setting the `quarkus.http.auth.basic` property to `true`.
 +
 [source,properties]
 ----
 quarkus.http.auth.basic=true
 ----
 
-An easy way to configure the required user credentials for Basic authentication to work is to configure the user name, secret, and roles directly in the `application.properties` file.
-
-.Example of Basic authentication properties
-
+. For testing purposes, you can configure the required user credentials, user name, secret, and roles, in the `application.properties` file.
+For example:
++
 [source,properties]
 ----
 quarkus.http.auth.basic=true
 quarkus.security.users.embedded.plain-text=true
-quarkus.security.users.embedded.users.alice=alice
-quarkus.security.users.embedded.users.bob=bob
-quarkus.security.users.embedded.roles.alice=admin
-quarkus.security.users.embedded.roles.bob=user
+quarkus.security.users.embedded.users.alice=alice <1>
+quarkus.security.users.embedded.users.bob=bob <2>
+quarkus.security.users.embedded.roles.alice=admin <1>
+quarkus.security.users.embedded.roles.bob=user <2>
 ----
-
-In this configuration the credentials for users `alice` and `bob` are configured: `alice` has a password `alice` and an `admin` role, `bob` has a password `bob` and a `user` role.
-
-For more information, see xref:security-testing.adoc#configuring-user-information[Configuring User Information] in the "Security Testing" guide.
-
+<1> The user, `alice`, has `alice` as their password and `admin` as their role.
+<2> The user, `bob`, has `bob` as their password and `user` as their role.
++
+For information about other methods that you can use to configure the required user credentials, see the xref:security-testing.adoc#configuring-user-information[Configuring User Information] section of the Quarkus "Security Testing" guide.
++
 [IMPORTANT]
 ====
 Configuring user names, secrets, and roles in the `application.properties` file is only suitable for testing scenarios.
-If you are securing an application for production, always use a database to store this information.
+If you are securing a production application, always use a database to store this information.
 ====
 
-To walk through how to configure Basic authentication together with Jakarta Persistence for storing user credentials in a database, see the xref:security-basic-authentication-tutorial.adoc[Secure a Quarkus application with Basic authentication] tutorial.
+== Next steps
+
+For a more detailed walk-through that shows you how to configure Basic authentication together with Jakarta Persistence for storing user credentials in a database, see the xref:security-basic-authentication-tutorial.adoc[Secure a Quarkus application with Basic authentication and Jakarta Persistence] guide.
 
 == References
 
 * xref:security-overview.adoc[Quarkus Security overview]
 * xref:security-identity-providers.adoc[Identity Providers]
 * xref:security-testing.adoc#configuring-user-information[Configuring User Information in application.properties]
-* xref:security-basic-authentication.adoc[Basic authentication] 
+* xref:security-basic-authentication.adoc[Basic authentication]

docs/src/main/asciidoc/security-basic-authentication-tutorial.adoc

@@ -7,7 +7,7 @@ include::_attributes.adoc[]
 Secure your Quarkus application endpoints by combining the built-in Quarkus xref:security-basic-authentication.adoc[Basic authentication] with the Jakarta Persistence identity provider to enable role-based access control (RBAC).
 The Jakarta Persistence `IdentityProvider` creates a `SecurityIdentity` instance, which is used during user authentication to verify and authorize access requests making your Quarkus application secure.
 
-For more information about Jakarta Persistence, see the xref:security-jpa.adoc[Quarkus Security with Jakarta Persistence] section.
+For more information about Jakarta Persistence, see the xref:security-jpa.adoc[Quarkus Security with Jakarta Persistence] guide.
 
 This tutorial prepares you for implementing more advanced security mechanisms in Quarkus, for example, how to use the OpenID Connect (OIDC) authentication mechanism.
 
@@ -23,21 +23,24 @@ To demonstrate different authorization policies, the steps in this tutorial guid
 |===
 |Endpoint | Description
 |`/api/public`| The `/api/public` endpoint can be accessed anonymously.
-|`/api/admin`| The `/api/admin` endpoint is protected with role-based access control (RBAC), and only users who have been granted the `admin` role can access it.
+|`/api/admin`| The `/api/admin` endpoint is protected with role-based access control (RBAC).
+Only users granted with the `admin` role can access it.
 At this endpoint, the `@RolesAllowed` annotation enforces the access constraint declaratively.
-|`/api/users/me`| The `/api/users/me` endpoint is protected by RBAC. Only users that have the `user` role can access the endpoint.
+|`/api/users/me`| The `/api/users/me` endpoint is protected by RBAC.
+Only users that have the `user` role can access the endpoint.
 This endpoint returns the caller's username as a string.
 |===
 
 [TIP]
 ====
-If you just want to examine the code, you can fast-forward to the completed example by using one of the following ways:
+To examine the completed example, download the {quickstarts-archive-url}[archive] or clone the Git repository:
 
-* Download the {quickstarts-archive-url}[archive]
-* Clone the Git repository: `git clone {quickstarts-clone-url}`
+[source,bash,subs=attributes+]
+----
+git clone {quickstarts-clone-url}
+----
 
-You can find the solution using the `security-jpa` extension in the `security-jpa-quickstart` {quickstarts-tree-url}/security-jpa-quickstart[directory]
-and the solution using the `security-jpa-reactive` extension in the `security-jpa-reactive-quickstart` {quickstarts-tree-url}/security-jpa-reactive-quickstart[directory].
+You can find the solution in the `security-jpa-quickstart` {quickstarts-tree-url}/security-jpa-quickstart[directory] in the upstream {ProductName} community.
 ====
 
 :sectnums:
@@ -63,7 +66,7 @@ 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] with the `security-jpa` extension.
-Correspondingly, both xref:hibernate-reactive.adoc[Hibernate Reactive] and xref:hibernate-reactive-panache.adoc[Hibernate Reactive with Panache] can be used with the `security-jpa-reactive` extension.
+Both xref:hibernate-reactive.adoc[Hibernate Reactive] and xref:hibernate-reactive-panache.adoc[Hibernate Reactive with Panache] can be used with the `security-jpa-reactive` extension.
 
 You must also add your preferred database connector library.
 The instructions in this example tutorial use a PostgreSQL database for the identity store.
@@ -79,9 +82,9 @@ include::{includes}/devtools/extension-add.adoc[]
 :add-extension-extensions: security-jpa-reactive
 include::{includes}/devtools/extension-add.adoc[]
 
-=== Verification
+=== Verify the quarkus-security-jpa dependency
 
-When you run either command to add `securityjpa`, the following XML is added to your build file:
+After you run either of the preceding commands, verify that the `security-jpa` dependency was added to your project build XML file,as follows:
 
 [source,xml,role="primary asciidoc-tabs-target-sync-cli asciidoc-tabs-target-sync-maven"]
 .pom.xml
@@ -98,7 +101,7 @@ When you run either command to add `securityjpa`, the following XML is added to
 implementation("io.quarkus:quarkus-security-jpa")
 ----
 
-Similarly, if you added `security-jpa-reactive` instead, the following XML is added to your build file:
+Similarly, if you added the  `security-jpa-reactive` extension, verify that the correct dependency was added to your project build XML file, as follows:
 
 [source,xml,role="primary asciidoc-tabs-target-sync-cli asciidoc-tabs-target-sync-maven"]
 .pom.xml
@@ -165,8 +168,8 @@ public class AdminResource {
     }
 }
 ----
-* Finally, implement the `/api/users/me` endpoint. As you can see from the source code example below, we are trusting only users with the `user` role.
-We are also using `SecurityContext` to get access to the currently authenticated `Principal`, and we return the username, all of which is loaded from the database.
+* Finally, implement an `/api/users/me` endpoint that can only accessed by users who have the `user` role.
+Use `SecurityContext` to get access to the currently authenticated `Principal` user and to return their username, all of which is retrieved from the database.
 +
 [source,java]
 ----
@@ -237,20 +240,22 @@ public class User extends PanacheEntity {
 
 ----
 
-The `security-jpa` extension initializes only if there is a single entity annotated with `@UserDefinition`.
+The `security-jpa` extension initializes only if a single entity is annotated with `@UserDefinition`.
 
 <1> The `@UserDefinition` annotation must be present on a single entity and can be either a regular Hibernate ORM entity or a Hibernate ORM with Panache entity.
 <2> Indicates the field used for the username.
-<3> Indicates the field used for the password. By default, it uses bcrypt-hashed passwords. You can configure it to use plain text or custom passwords.
-<4> This indicates the comma-separated list of roles added to the target principal representation attributes.
-<5> This method allows us to add users while hashing the password with the proper bcrypt hash.
+<3> Indicates the field used for the password.
+By default, it uses bcrypt-hashed passwords.
+You can configure it to use plain text or custom passwords.
+<4> Indicates the comma-separated list of roles added to the target principal representation attributes.
+<5> Allows us to add users while hashing passwords with the proper bcrypt hash.
 
 NOTE: Hibernate Reactive Panache uses `io.quarkus.hibernate.reactive.panache.PanacheEntity` instead of `io.quarkus.hibernate.orm.panache.PanacheEntity`.
-Please refer to {quickstarts-tree-url}/security-jpa-reactive-quickstart/src/main/java/org/acme/elytron/security/jpa/reactive/User.java[User file] for more information.
+For more information, see  {quickstarts-tree-url}/security-jpa-reactive-quickstart/src/main/java/org/acme/elytron/security/jpa/reactive/User.java[User file].
 
 === Configure the application
 
-. Enable the built-in Quarkus xref:security-basic-authentication.adoc[Basic authentication] by setting the `quarkus.http.auth.basic` property to `true`:
+. Enable the built-in Quarkus xref:security-basic-authentication.adoc[Basic authentication] mechanism by setting the `quarkus.http.auth.basic` property to `true`:
 +
 `quarkus.http.auth.basic`=true`
 +
@@ -260,7 +265,8 @@ When secure access is required and no other authentication mechanisms are enable
 Therefore, in this tutorial, you do not need to set the property `quarkus.http.auth.basic` to `true`.
 ====
 +
-. Configure at least one data source so that the `security-jpa` extension can access your database.
+. Configure at least one data source in the `application.properties` file so the `security-jpa` extension can access your database.
+For example:
 +
 [source,properties]
 ----
@@ -278,8 +284,8 @@ quarkus.hibernate-orm.database.generation=drop-and-create
 
 [NOTE]
 ====
-Reactive datasource used by the `security-jpa-reactive` extension has URL set with the `quarkus.datasource.reactive.url`
-configuration property, instead of the `quarkus.datasource.jdbc.url` configuration property used by JDBC datasource.
+The URLs of Reactive datasources that are used by the `security-jpa-reactive` extension are set with the `quarkus.datasource.reactive.url`
+configuration property and not the `quarkus.datasource.jdbc.url` configuration property that is typically used by JDBC datasources.
 
 [source,properties]
 ----
@@ -289,8 +295,10 @@ configuration property, instead of the `quarkus.datasource.jdbc.url` configurati
 
 [NOTE]
 ====
-In this tutorial, a PostgreSQL database is used for the identity store. link:https://hibernate.org/orm/[Hibernate ORM] automatically creates the database schema on startup.
-This approach is suitable for development but needs to be revised for production.
+In this tutorial, a PostgreSQL database is used for the identity store.
+link:https://hibernate.org/orm/[Hibernate ORM] automatically creates the database schema on startup.
+This approach is suitable for development but is not recommended for production.
+Therefore adjustments are needed in a production environment.
 ====
 
 [source,java]
@@ -316,24 +324,22 @@ public class Startup {
 }
 ----
 
-The application is now protected and the user identities are provided by the specified database.
+The preceding example demonstrates how the application can be protected and identities provided by the specified database.
 
-[NOTE]
+[IMPORTANT]
 ====
 In a production environment, do not store plain text passwords.
 As a result, the `security-jpa` defaults to using bcrypt-hashed passwords.
 ====
 
-== Test your application
+== Test your application by using Dev Services for PostgreSQL
 
-=== Use Dev Services for PostgreSQL to test your application
+Complete the integration testing of your application in JVM and native modes by using xref:https://quarkus.io/guides/dev-services#databases[Dev Services for PostgreSQL] before you run your application in production mode.
 
-include::{includes}/devtools/dev.adoc[]
-
-Add the integration tests before you run your application in production mode.
+To run your application in dev mode:
 
+include::{includes}/devtools/dev.adoc[]
 
-Use xref:https://quarkus.io/guides/dev-services#databases[Dev Services for PostgreSQL] for the integration testing of your application in JVM and native modes.
 
 The following properties configuration demonstrates how you can enable PostgreSQL testing to run in production (`prod`) mode only.
 In this scenario, `Dev Services for PostgreSQL` launches and configures a `PostgreSQL` test container.
@@ -422,8 +428,8 @@ As you can see in this code sample, you do not need to start the test container
 
 [NOTE]
 ====
-If you start your application in dev mode, `Dev Services for PostgreSQL` launches a `PostgreSQL` `devmode` container so that you can start developing your application.
-While developing your application, you can also start to add tests one by one and run them by using the xref:continuous-testing.adoc[Continuous Testing] feature.
+When you start your application in dev mode, `Dev Services for PostgreSQL` launches a `PostgreSQL` `devmode` container so that you can start developing your application.
+While developing your application, you can add tests one by one and run them using the xref:continuous-testing.adoc[Continuous Testing] feature.
 `Dev Services for PostgreSQL` supports testing while you develop by providing a separate `PostgreSQL` test container that does not conflict with the `devmode` container.
 ====
 
@@ -465,7 +471,7 @@ Run 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.
+When your application is running, you can access its endpoints by using one of the following `curl` commands.
 You can also access the same endpoint URLs by using a browser.
 
 * Connect to a protected endpoint anonymously:
@@ -493,7 +499,7 @@ Not authorized
 
 [NOTE]
 ====
-When you use a browser to anonymously connect to a protected resource, a basic authentication form displays prompting you to enter credentials.
+If you use a browser to anonymously connect to a protected resource, a Basic authentication form displays, prompting you to enter credentials.
 ====
 
 * Connect to a protected endpoint as an authorized user:
@@ -513,7 +519,7 @@ admin
 When you provide the credentials of an authorized user, for example, `admin:admin`, the Jakarta Persistence security extension authenticates and loads the roles of the user.
 The `admin` user is authorized to access the protected resources.
 
-If a resource is protected with `@RolesAllowed("user")`, the user `admin` is not authorized to access the resource because it is not assigned to the "user" role, as outlined in the following shell example:
+If a resource is protected with `@RolesAllowed("user")`, the user `admin` is not authorized to access the resource because it is not assigned to the "user" role, as shown in the following shell example:
 
 [source,shell]
 ----
@@ -544,17 +550,17 @@ user
 Congratulations!
 You have learned how to create and test a secure Quarkus application by combining the built-in xref:security-basic-authentication.adoc[Basic authentication] in Quarkus with the Jakarta Persistence identity provider.
 
-After you have completed this tutorial, explore some of the more advanced security mechanisms in Quarkus.
-Use the following information to learn how you can securely use `OpenID Connect` to provide secure single sign-on access to your Quarkus endpoints:
+After completing this tutorial, you can explore more advanced security mechanisms in Quarkus.
+The following information shows you how to use `OpenID Connect` for secure single sign-on access to your Quarkus endpoints:
 
 * xref:security-oidc-bearer-token-authentication.adoc[OIDC Bearer authentication]
 * xref:security-oidc-code-flow-authentication.adoc[OIDC code flow mechanism for protecting web applications]
 
 == References
 
 * xref:security-overview.adoc[Quarkus Security overview]
-* xref:security-architecture.adoc[Quarkus Security architecture] 
-* xref:security-authentication-mechanisms.adoc#other-supported-authentication-mechanisms[Authentication mechanisms in Quarkus]
+* xref:security-architecture.adoc[Quarkus Security architecture]
+* xref:security-authentication-mechanisms.adoc#other-supported-authentication-mechanisms[Other supported authentication mechanisms]
 * xref:security-identity-providers.adoc[Identity providers]
 * xref:security-oidc-bearer-token-authentication.adoc[OIDC Bearer authentication]
 * xref:security-oidc-code-flow-authentication.adoc[OIDC code flow mechanism for protecting web applications]