From 96140e26c7b64c50bbd5927e2ce074ea07e380e2 Mon Sep 17 00:00:00 2001 From: Michelle Purcell Date: Mon, 26 Jun 2023 14:51:39 +0100 Subject: [PATCH] Minor doc enhancements to Security Basic Auth docs Minor fix Minor edits to basic auth concept More edits to the how-to content Style and grammar edits- security Basic auth docs Update docs/src/main/asciidoc/security-basic-authentication-tutorial.adoc Co-authored-by: Sergey Beryozkin Reverted identity providers topic back to main --- .../security-basic-authentication-howto.adoc | 37 ++++---- ...ecurity-basic-authentication-tutorial.adoc | 90 ++++++++++--------- .../security-basic-authentication.adoc | 28 +++--- 3 files changed, 81 insertions(+), 74 deletions(-) diff --git a/docs/src/main/asciidoc/security-basic-authentication-howto.adoc b/docs/src/main/asciidoc/security-basic-authentication-howto.adoc index d36a70ac21d6f..b58298fa1a9f2 100644 --- a/docs/src/main/asciidoc/security-basic-authentication-howto.adoc +++ b/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] diff --git a/docs/src/main/asciidoc/security-basic-authentication-tutorial.adoc b/docs/src/main/asciidoc/security-basic-authentication-tutorial.adoc index fc9124cc39487..b812f1db4fa9c 100644 --- a/docs/src/main/asciidoc/security-basic-authentication-tutorial.adoc +++ b/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,8 +550,8 @@ 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] @@ -553,8 +559,8 @@ Use the following information to learn how you can securely use `OpenID Connect` == 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] diff --git a/docs/src/main/asciidoc/security-basic-authentication.adoc b/docs/src/main/asciidoc/security-basic-authentication.adoc index 54ca848e82cbc..4349139f8179d 100644 --- a/docs/src/main/asciidoc/security-basic-authentication.adoc +++ b/docs/src/main/asciidoc/security-basic-authentication.adoc @@ -4,8 +4,9 @@ include::_attributes.adoc[] :diataxis-type: concept :categories: security,web -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. +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. Basic authentication uses fields in the HTTP header and does not require HTTP cookies, session identifiers, or login pages. @@ -21,8 +22,8 @@ If the user name is `Alice` and the password is `secret`, the HTTP authorization ==== 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. +The credentials are merely encoded with Base64 when in transit, and not encrypted or hashed in any way. +Therefore, to provide confidentiality, use Basic authentication with HTTPS. Basic authentication is a well-specified, simple challenge and response scheme that all web browsers and most web servers understand. @@ -32,23 +33,22 @@ The following table outlines some limitations of using HTTP Basic authentication .Limitations of HTTP Basic authentication -[width=80%] [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. +The risk of exposing credentials as plain text increases if a load balancer terminates HTTPS because the request is forwarded to Quarkus over HTTP. +Furthermore, 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 must be sent with each request, which increases the risk of credentials being exposed. +|In Basic authentication, a username and password must be sent with each request, increasing the risk of exposing credentials. |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. +Depending on the use case, other authentication mechanisms that delegate username, password, and role management to specialized services might be more secure. |=== @@ -61,13 +61,13 @@ For more information about how you can secure your Quarkus applications by using == Role-based access control -{project-name} also includes built-in security to allow for role-based access control (RBAC) based on the common security annotations @RolesAllowed, @DenyAll, @PermitAll on REST endpoints and CDI beans. -For more information, see xref:security-authorize-web-endpoints-reference.adoc[Authorization of web endpoints]. +{project-name} also includes built-in security to allow for role-based access control (RBAC) based on the common security annotations @RolesAllowed, @DenyAll, @PermitAll on REST endpoints and CDI beans. +For more information, see the Quarkus xref:security-authorize-web-endpoints-reference.adoc[Authorization of web endpoints] guide. == 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-authorize-web-endpoints-reference.adoc[Authorization of web endpoints] +* xref:security-authorize-web-endpoints-reference.adoc[Authorization of web endpoints] \ No newline at end of file