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 and least resource demanding technique for enforcing access controls to Web resources without requiring HTTP cookies, session identifiers, or login pages.
+
+In the context of an HTTP request, basic access authentication is a method for an HTTP user agent (such as a Web browser) to provide a user name and password when making 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. 
+
+====
+.Example
+ 
+If the user name is `Alice` and the password is `secret`, the HTTP Authorization header will look as `Authorization: Basic  QWxjZTpzZWNyZXQ=`,where `QWxjZTpzZWNyZXQ=` is a Base64 encoded representation of the `Alice:secret; string.
+====
+
+The BA mechanism does not provide confidentiality protection for the transmitted credentials; they are merely encoded with Base64 when in transit, and not encrypted or hashed in any way. Therefore, basic authentication is typically used with HTTPS to provide confidentiality.
+
+[[enabling-basic-auth]]
+=== Enabling Basic Authentication
+
+.Prerequisites
+
+* You have installed at least one extension that provides a username/password based `IdentityProvider`, 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 Auth configuration walkthrough that uses JPA as an alternative technology that works with BA, 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

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 Auth canfiguration walkthrough (using JPA), see
+* xref:security-getting-started.adoc[Getting Started With Security] guide.
+
+For testing, use xref:security-testing.adoc#configuring-user-information[User Properties IdentityProvider]
 
 == Combining Authentication Mechanisms