Merge pull request #18453 from cescoffier/vertx-doc-update

New vert.x getting started and reference guide

docs/src/main/asciidoc/http-reference.adoc

@@ -263,6 +263,63 @@ include::{generated-dir}/config/quarkus-vertx-http-config-group-access-log-confi
 |Response header                                                              |          | `%{o,response_header_name}`
 |===
 
+
+[[reverse-proxy]]
+== Running behind a reverse proxy
+
+Quarkus could be accessed through proxies that additionally generate headers (e.g. `X-Forwarded-Host`) to keep
+information from the client-facing side of the proxy servers that is altered or lost when they are involved.
+In those scenarios, Quarkus can be configured to automatically update information like protocol, host, port and URI
+reflecting the values in these headers.
+
+IMPORTANT: Activating this feature leaves the server exposed to several security issues (i.e. information spoofing).
+Consider activate it only when running behind a reverse proxy.
+
+To setup this feature, please include the following lines in `src/main/resources/application.properties`:
+[source,properties]
+----
+quarkus.http.proxy-address-forwarding=true
+----
+
+To consider only de-facto standard header (`Forwarded` header), please include the following lines in `src/main/resources/application.properties`:
+[source,properties]
+----
+quarkus.http.proxy.allow-forwarded=true
+----
+
+To consider only non-standard headers, please include the following lines instead in `src/main/resources/application.properties`:
+
+[source,properties]
+----
+quarkus.http.proxy.proxy-address-forwarding=true
+quarkus.http.proxy.enable-forwarded-host=true
+quarkus.http.proxy.enable-forwarded-prefix=true
+----
+
+Both configurations related to standard and non-standard headers can be combined, although the standard headers configuration will have precedence.
+
+Supported forwarding address headers are:
+
+* `Forwarded`
+* `X-Forwarded-Proto`
+* `X-Forwarded-Host`
+* `X-Forwarded-Port`
+* `X-Forwarded-Ssl`
+* `X-Forwarded-Prefix`
+
+[[same-site-cookie]]
+== SameSite cookies
+
+One can easily add a https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite[SameSite] cookie property to any of the cookies set by a Quarkus endpoint by listing a cookie name and a `SameSite` attribute, for example:
+
+[source]
+----
+quarkus.http.same-site-cookie.jwt.value=Lax
+quarkus.http.same-site-cookie.session.value=Strict
+----
+
+Given this configuration, the `jwt` cookie will have a `SameSite=Lax` attribute and the `session` cookie will have a `SameSite=Strict` attribute.
+
 == Servlet Config
 
 To use Servlet you need to explicitly include `quarkus-undertow`:

docs/src/main/asciidoc/reactive-sql-clients.adoc

@@ -642,7 +642,7 @@ MySQLPool additional2Client;
 
 The PostgreSQL and MariaDB/MySQL clients can be configured to connect to the server through a UNIX domain socket.
 
-First make sure that link:vertx#native-transport[native transport support] is enabled.
+First make sure that link:vertx-reference.adoc#native-transport[native transport support] is enabled.
 
 Then configure the database connection url.
 This step depends on the database type.

docs/src/main/asciidoc/rest-json.adoc

@@ -182,6 +182,7 @@ If you don't rely on the JSON default, it is heavily recommended to annotate you
 It will allow to narrow down the number of JAX-RS providers (which can be seen as converters) included in the native executable.
 ====
 
+[[json]]
 === Configuring JSON support
 
 ==== Jackson

docs/src/main/asciidoc/security-openid-connect-web-authentication.adoc

@@ -864,7 +864,7 @@ quarkus.log.category."io.quarkus.oidc.runtime.OidcRecorder".min-level=TRACE
 
 OIDC authentication mechanism can be affected if your Quarkus application is running behind a reverse proxy/gateway/firewall when HTTP `Host` header may be reset to the internal IP address, HTTPS connection may be terminated, etc. For example, an authorization code flow `redirect_uri` parameter may be set to the internal host instead of the expected external one.
 
-In such cases configuring Quarkus to recognize the original headers forwarded by the proxy will be required, see link:vertx#reverse-proxy[Running behind a reverse proxy] Vert.x documentation section for more information.
+In such cases configuring Quarkus to recognize the original headers forwarded by the proxy will be required, see link:http-reference#reverse-proxy[Running behind a reverse proxy] Vert.x documentation section for more information.
 
 For example, if your Quarkus endpoint runs in a cluster behind Kubernetes Ingress then a redirect from the OpenId Connect Provider back to this endpoint may not work since the calcuated `redirect_uri` parameter may point to the internal endpoint address. This problem can be resolved with the following configuration:
 

docs/src/main/asciidoc/security.adoc

@@ -251,7 +251,7 @@ If you plan to make your Quarkus application accessible to another application r
 
 == SameSite cookies
 
-Please see link:vertx#same-site-cookie[SameSite cookies] for information about adding a https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite[SameSite] cookie property to any of the cookies set by a Quarkus endpoint.
+Please see link:http-reference.adoc#same-site-cookie[SameSite cookies] for information about adding a https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite[SameSite] cookie property to any of the cookies set by a Quarkus endpoint.
 
 == Testing