Improve the Basic Authentication section

Signed-off-by: Michal Maléř <[email protected]>

docs/src/main/asciidoc/security-built-in-authentication.adoc

@@ -7,17 +7,46 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 
 include::./attributes.adoc[]
 
-This document describes the Quarkus built-in authentication mechanisms for HTTP based FORM, BASIC and Mutual TLS authentication as well as the proactive authentication.
+The following section describes the Quarkus built-in authentication mechanisms for HTTP based FORM, BASIC, and Mutual TLS authentication. Proactive authentication is also described.
 
 [[basic-auth]]
 == Basic Authentication
+
+HTTP Basic Authentication uses fields in the HTTP header and is the easiest to set up. Also, it is one of the least resource-demanding techniques that enforce access controls to the Web resources without requiring HTTP cookies, session identifiers, or login pages.
+
+In the context of an HTTP request, Basic authentication is a method for an HTTP user agent, such as a web browser, to provide a user name and password when creating a request. In Basic HTTP Authentication, a request contains a header field in the form of `Authorization: Basic <credentials>`, where credentials are the Base64 encoding of a user ID and password joined by a colon as described in the following example.
+
+====
+.Example
+ 
+If the user name is `Alice` and the password is `secret`, the HTTP authorization header looks authorization as `Authorization: Basic  QWxjZTpzZWNyZXQ=`, where `QWxjZTpzZWNyZXQ=` is a Base64 encoded representation of the `Alice:secret` string.
+====
+
+The Basic Authentication mechanism does not provide confidentiality protection for the transmitted credentials. The credentials are merely encoded with Base64 when in transit and not encrypted or hashed in any way. Therefore, Basic Authentication is used with HTTPS to provide confidentiality.
+
+[[enabling-basic-auth]]
+=== Enabling Basic Authentication
+
+.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].
+
+.Procedure
+
+* Enable Basic Authentication by setting the value of `quarkus.http.auth.basic` property to `true`.
++
+[source,properties]
+----
+quarkus.http.auth.basic=true
+----
+
+For a Basic Authentication configuration walk-through that uses `JPA`, see the xref:security-getting-started.adoc[Getting Started With Security] guide.
+
+.Additional resources
+
+* xref:security.adoc#identity-providers[Security Identity Providers]
+* xref:security-testing.adoc#configuring-user-information[Configuring User Information in application.properties]
 
-To enable basic authentication set `quarkus.http.auth.basic=true`. You must also have at least one extension installed
-that provides a username/password based `IdentityProvider`, such as xref:security-jdbc.adoc[Elytron JDBC].
-
-Please see xref:security.adoc#identity-providers[Security Identity Providers] for more information.
-
-Please also see xref:security-testing.adoc#configuring-user-information[Configuring User Information in application.properties] section.
 
 [[form-auth]]
 == Form Based Authentication
@@ -98,7 +127,7 @@ X509Certificate certificate = credential.getCertificate();
 
 === Authorization
 
-The information from the client certificate can be used to enhance Quarkus `SecurityIdentity`. For example, one can add new roles after checking a client certificate subject name, etc.
+The information from the client certificate can be used to enhance Quarkus `SecurityIdentity`. For example, one can add new roles after checking a client certificate subject name, and so on.
 Please see the xref:security-customization.adoc#security-identity-customization[SecurityIdentity Customization] section for more information about customizing Quarkus `SecurityIdentity`.
 
 [[proactive-authentication]]

docs/src/main/asciidoc/security.adoc

@@ -204,9 +204,16 @@ Some extensions such as `OIDC`, `OAuth2`, `SmallRye JWT` have the inlined `Ident
 For example, `quarkus-oidc` uses its own `IdentityProvider` to convert a token to `SecurityIdentity`. 
 
 If you use `Basic` or `Form` HTTP-based authentication then you have to add an `IdentityProvider` which can convert a username and password to `SecurityIdentity`.
-See xref:security-getting-started.adoc[JPA IdentityProvider], xref:security-jdbc.adoc[JDBC IdentityProvider] and xref:security-ldap.adoc[LDAP IdentityProvider] for more information.
 
-You can also use xref:security-testing.adoc#configuring-user-information[User Properties IdentityProvider] for testing.
+* For more information about `Basic` or `Form` HTTP-based authentication, see: 
+** xref:security-getting-started.adoc[JPA IdentityProvider]
+** xref:security-jdbc.adoc[JDBC IdentityProvider]
+** xref:security-ldap.adoc[LDAP IdentityProvider]
+
+* For a a Basic Authentication configuration walk-through using JPA, see:
+** xref:security-getting-started.adoc[Getting Started With Security] guide.
+
+* For testing, use the xref:security-testing.adoc#configuring-user-information[User Properties IdentityProvider] section with the `IdentityProvider` with already set usernames, passwords, and roles in `application.properties`.
 
 == Combining Authentication Mechanisms