diff --git a/docs/src/main/asciidoc/security-basic-authentication-concept.adoc b/docs/src/main/asciidoc/security-basic-authentication-concept.adoc index 744bd28812e6c..fc44ce178c40e 100644 --- a/docs/src/main/asciidoc/security-basic-authentication-concept.adoc +++ b/docs/src/main/asciidoc/security-basic-authentication-concept.adoc @@ -3,10 +3,14 @@ include::_attributes.adoc[] :categories: security,web -HTTP Basic Authentication is one of the least resource-demanding techniques that enforce access controls to the Web resources. -It uses fields in the HTTP header and does not require HTTP cookies, session identifiers, or login pages. +HTTP Basic authentication is one of the least resource-demanding techniques that enforce access controls to web resources. +You can secure your Quarkus application endpoints with HTTP Basic authentication. Quarkus provides a built-in authentication mechanism for Basic authentication. -An HTTP user agent, such as a web browser, uses an `Authorization` header to provide a user name and password in each HTTP request. +Basic authentication uses fields in the HTTP header and does not require HTTP cookies, session identifiers, or login pages. + +== Authorization header + +An HTTP user agent, for example, a web browser, uses an `Authorization` header to provide a username and password in each HTTP request. The header is specified as `Authorization: Basic `, where credentials are the Base64 encoding of the user ID and password joined by a colon, as shown in the following example. ==== @@ -15,32 +19,46 @@ The header is specified as `Authorization: Basic `, where credentia If the user name is `Alice` and the password is `secret`, the HTTP authorization header would be `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 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. +Therefore, Basic authentication is used with HTTPS to provide confidentiality. -Basic Authentication is a well-specified, simple challenge and response scheme that all web browsers and most web servers understand. -However, there are a few limitations associated with Basic Authentication, which include: +Basic authentication is a well-specified, simple challenge and response scheme that all web browsers and most web servers understand. -Credentials are sent as plain text:: -+ --- -Use HTTPS with Basic Authentication to avoid exposing the credentials. -The risk of exposing credentials as plain text increases if a load balancer terminates HTTPS, as the request is forwarded to Quarkus over HTTP. +== Limitations with using Basic authentication + +The following table outlines some limitations of using HTTP Basic authentication to secure your Quarkus applications: + +.Limitations of HTTP Basic authentication +[cols="35%,65%"] +|=== +|Limitation |Description + +|Credentials are sent as plain text +|Use HTTPS with Basic authentication to avoid exposing the credentials. +The risk of exposing credentials as plain text increases if a load balancer terminates HTTPS, as the request is forwarded to Quarkus over HTTP. Also, in multi-hop deployments, the credentials can be exposed if HTTPS is used between the client and the first Quarkus endpoint only, and the credentials are propagated to the next Quarkus endpoint over HTTP. --- - -Credentials are sent with each request:: -+ --- -In Basic Authentication, a username and password need to be sent with each request, which increases the risk of credentials being exposed. --- - -Application complexity increases:: -+ --- -The Quarkus application must validate that usernames, passwords, and roles are managed securely. + +|Credentials are sent with each request +|In Basic authentication, a username and password need to be sent with each request, which increases the risk of credentials being exposed. + +|Application complexity increases +|The Quarkus application must validate that usernames, passwords, and roles are managed securely. This process, however, can introduce significant complexity to the application. Depending on the use case, other authentication mechanisms that delegate username, password, and role management to specialized services might be a better choice. --- + +|=== + +== Implementing Basic authentication in Quarkus + +For more information about how you can secure your Quarkus applications by using Basic authentication, see the following resources: + +* xref:security-basic-authentication-howto.adoc[Enable Basic authentication] +* xref:security-basic-authentication-tutorial.adoc[Secure a Quarkus application with Basic authentication] + +== References + +* xref:security-overview-concept.adoc[Quarkus Security overview] +* xref:security-authentication-mechanisms-concept.adoc#other-supported-authentication-mechanisms[Authentication mechanisms in Quarkus] + diff --git a/docs/src/main/asciidoc/security-overview-concept.adoc b/docs/src/main/asciidoc/security-overview-concept.adoc index 59757dabd64ac..c73fb97653405 100644 --- a/docs/src/main/asciidoc/security-overview-concept.adoc +++ b/docs/src/main/asciidoc/security-overview-concept.adoc @@ -26,7 +26,7 @@ Quarkus Security also supports the following features: * <> * <> * <> -* <> +* xref:security-vulnerability-detection-concept.adoc[Security vulnerability detection and National Vulnerability Database (NVD) registration] Quarkus Security is also highly customizable. For more information, see xref:security-customization.adoc[Security customization]. @@ -60,7 +60,7 @@ For more information, see xref:security-csrf-prevention.adoc[Cross-Site Request You can 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. For more information, see xref:http-reference.adoc#same-site-cookie[SameSite cookies]. -=== Secret engines +=== Secrets engines Secrets engines are components that store, generate, or encrypt data. Quarkus provides comprehensive HashiCorp Vault support. @@ -75,121 +75,8 @@ For more information, see xref:resteasy-reactive.adoc#secure-serialization[Writi If you're using the REST Data with Panache extension to auto-generate your resources, you can still use the Security annotations within the package `javax.annotation.security`. For more information, see xref:rest-data-panache.adoc#securing-endpoints[Securing auto-generated resources]. + +== Security vulnerability detection -=== US National Vulnerability Database registration - -Most of the Quarkus tags are registered in the US link:https://nvd.nist.gov[National Vulnerability Database] (NVD) in Common Platform Enumeration (CPE) name format. -To view the registered Quarkus CPE names, use link:https://nvd.nist.gov/products/cpe/search/results?namingFormat=2.3&keyword=quarkus[this search query]. - -If the NVE database flags a CVE against a Quarkus tag, a link that provides more details about the CVE is added to the given CPE name entry. - -The NVD CPE team updates the list regularly, but if you encounter a false positive, report the details by creating an issue in the link:https://github.com/quarkusio/quarkus/issues/2611[quarkusio] repository. - -You can detect the vulnerabilities at the application build time with an NVD feed by using the Maven link:https://jeremylong.github.io/DependencyCheck/dependency-check-maven/[OWASP Dependency check plugin]. - - -To add the OWASP Dependency check plugin to your Quarkus Maven project, add the following XML configuration to the `pom.xml` file: - -[source,xml] ----- - - org.owasp - dependency-check-maven - ${owasp-dependency-check-plugin.version} - ----- - -[IMPORTANT] -==== -Set the `owasp-dependency-check-plugin.version` value to `7.4.4` or later. -==== - -Next, configure the plugin as follows: - -[source,xml] ----- - - org.owasp - dependency-check-maven - ${owasp-dependency-check-plugin.version} - - - 7 - - ${project.basedir}/dependency-cpe-suppression.xml - - - ----- - -To detect less severe issues, adjust the value of `failBuildOnCVSS` to suppress the false positives, as demonstrated in the following code sample: -[source,xml] ----- - - - - - - - - ^io\.netty:netty-tcnative-classes.*:.*$ - cpe:/a:netty:netty - - - - - - ^io\.quarkus:quarkus-mutiny.*:.*$ - cpe:/a:mutiny:mutiny - - - - - - ^io\.smallrye.reactive:mutiny.*:.*$ - cpe:/a:mutiny:mutiny - - - - - - ^io\.smallrye.reactive:smallrye-mutiny.*:.*$ - cpe:/a:mutiny:mutiny - - - - - - ^io\.smallrye.reactive:vertx-mutiny.*:.*$ - cpe:/a:mutiny:mutiny - - - - - - ^org\.graalvm\.sdk:g like this - - ----- - -Ensure that you review and update the suppression list regularly to ensure that the results are up to date. -You can optionally apply a time limit to individual suppressions by adding an expiry attribute, as outlined in the following example: - -`...` -You can adjust the expiry date if you need to. +Most of the Quarkus tags are reported in the US link:https://nvd.nist.gov[National Vulnerability Database (NVD)]. +For information about security vulnerabilities, see xref:security-vulnerability-detection-concept.adoc[Security vulnerability detection and reporting in Quarkus]. \ No newline at end of file diff --git a/docs/src/main/asciidoc/security-proactive-authentication-concept.adoc b/docs/src/main/asciidoc/security-proactive-authentication-concept.adoc index 7acefe164099b..4ccb8a45d1a94 100644 --- a/docs/src/main/asciidoc/security-proactive-authentication-concept.adoc +++ b/docs/src/main/asciidoc/security-proactive-authentication-concept.adoc @@ -147,4 +147,10 @@ public class AuthenticationFailedExceptionHandler { }); } } ----- \ No newline at end of file +---- + +== References + +* xref:security-overview-concept.adoc[Quarkus Security overview] +* xref:security-authentication-mechanisms-concept.adoc#other-supported-authentication-mechanisms[Authentication mechanisms in Quarkus] + diff --git a/docs/src/main/asciidoc/security-vulnerability-detection-concept.adoc b/docs/src/main/asciidoc/security-vulnerability-detection-concept.adoc new file mode 100644 index 0000000000000..101ef54716750 --- /dev/null +++ b/docs/src/main/asciidoc/security-vulnerability-detection-concept.adoc @@ -0,0 +1,137 @@ +//// +This document 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 +//// +[id="security-vulnerability-detection-concept"] += Security vulnerability detection and reporting in Quarkus +include::_attributes.adoc[] +:categories: security,contributing + +Most of the Quarkus tags are registered in the US link:https://nvd.nist.gov[National Vulnerability Database (NVD)] in Common Platform Enumeration (CPE) name format. + +== US National Vulnerability Database + +To view the registered Quarkus CPE names in the US NVD, use the following search URL: + +https://nvd.nist.gov/products/cpe/search/results?namingFormat=2.3&keyword=quarkus + +If the NVE database flags a CVE against a Quarkus tag, a link that provides more details about the CVE is added to the given CPE name entry. + +The NVD CPE team updates the list regularly, but if you encounter a false positive, report the details by creating an issue in the link:https://github.com/quarkusio/quarkus/issues/2611[quarkusio] repository. + +== Detecting vulnerabilities in Quarkus at build time + +You can detect the vulnerabilities at the application build time with an NVD feed by using the Maven link:https://jeremylong.github.io/DependencyCheck/dependency-check-maven/[OWASP Dependency check plugin]. + + +To add the OWASP Dependency check plugin to your Quarkus Maven project, add the following XML configuration to the `pom.xml` file: + +[source,xml] +---- + + org.owasp + dependency-check-maven + ${owasp-dependency-check-plugin.version} + +---- + +[IMPORTANT] +==== +Set the `owasp-dependency-check-plugin.version` value to `7.4.4` or later. +==== + +Next, configure the plugin as follows: + +[source,xml] +---- + + org.owasp + dependency-check-maven + ${owasp-dependency-check-plugin.version} + + + 7 + + ${project.basedir}/dependency-cpe-suppression.xml + + + +---- + +To detect less severe issues, adjust the value of `failBuildOnCVSS` to suppress the false positives, as demonstrated in the following code sample: +[source,xml] +---- + + + + + + + + ^io\.netty:netty-tcnative-classes.*:.*$ + cpe:/a:netty:netty + + + + + + ^io\.quarkus:quarkus-mutiny.*:.*$ + cpe:/a:mutiny:mutiny + + + + + + ^io\.smallrye.reactive:mutiny.*:.*$ + cpe:/a:mutiny:mutiny + + + + + + ^io\.smallrye.reactive:smallrye-mutiny.*:.*$ + cpe:/a:mutiny:mutiny + + + + + + ^io\.smallrye.reactive:vertx-mutiny.*:.*$ + cpe:/a:mutiny:mutiny + + + + + + ^org\.graalvm\.sdk:g like this + + +---- + +Ensure that you review and update the suppression list regularly to ensure that the results are up to date. +You can optionally apply a time limit to individual suppressions by adding an expiry attribute, as outlined in the following example: + +`...` +You can adjust the expiry date if you need to. + +== References + +* xref:security-overview-concept.adoc[Quarkus Security overview] +* xref:security-authentication-mechanisms-concept.adoc#other-supported-authentication-mechanisms[Authentication mechanisms in Quarkus] \ No newline at end of file