diff --git a/docs/src/main/asciidoc/security-authentication-mechanisms.adoc b/docs/src/main/asciidoc/security-authentication-mechanisms.adoc index f16939e380881..dd3f8522251c7 100644 --- a/docs/src/main/asciidoc/security-authentication-mechanisms.adoc +++ b/docs/src/main/asciidoc/security-authentication-mechanisms.adoc @@ -65,7 +65,7 @@ For more information, see the following documentation: * xref:security-basic-authentication.adoc[Basic authentication] ** xref:security-basic-authentication-howto.adoc[Enable Basic authentication] * xref:security-jpa.adoc[Quarkus Security with Jakarta Persistence] -** xref:security-getting-started-tutorial.adoc[Getting Started with Security using Basic authentication and Jakarta Persistence] +** xref:security-getting-started-tutorial.adoc[Getting started with Security by using Basic authentication and Jakarta Persistence] * xref:security-identity-providers.adoc[Identity providers] [[form-auth]] diff --git a/docs/src/main/asciidoc/security-authorize-web-endpoints-reference.adoc b/docs/src/main/asciidoc/security-authorize-web-endpoints-reference.adoc index 62a755bfd5b1c..d0e4bb48dc2c5 100644 --- a/docs/src/main/asciidoc/security-authorize-web-endpoints-reference.adoc +++ b/docs/src/main/asciidoc/security-authorize-web-endpoints-reference.adoc @@ -924,5 +924,5 @@ CAUTION: Annotation-based permissions do not work with custom xref:security-cust * xref:security-architecture.adoc[Quarkus Security architecture] * xref:security-authentication-mechanisms.adoc#other-supported-authentication-mechanisms[Authentication mechanisms in Quarkus] * xref:security-basic-authentication.adoc[Basic authentication] -* xref:security-getting-started-tutorial.adoc[Getting Started with Security using Basic authentication and Jakarta Persistence] +* xref:security-getting-started-tutorial.adoc[Getting started with Security by using Basic authentication and Jakarta Persistence] * xref:security-oidc-bearer-token-authentication.adoc#token-scopes-and-security-identity-permissions[OpenID Connect Bearer Token Scopes And SecurityIdentity Permissions] diff --git a/docs/src/main/asciidoc/security-basic-authentication-howto.adoc b/docs/src/main/asciidoc/security-basic-authentication-howto.adoc index 692b6b868b7ca..015127dbfb430 100644 --- a/docs/src/main/asciidoc/security-basic-authentication-howto.adoc +++ b/docs/src/main/asciidoc/security-basic-authentication-howto.adoc @@ -67,7 +67,7 @@ For securing a production application, it is crucial to use a database to store == 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-getting-started-tutorial.adoc[Getting Started with Security using Basic authentication and Jakarta Persistence] guide. +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-getting-started-tutorial.adoc[Getting started with Security by using Basic authentication and Jakarta Persistence] guide. == References diff --git a/docs/src/main/asciidoc/security-basic-authentication.adoc b/docs/src/main/asciidoc/security-basic-authentication.adoc index 61cac5921dd01..acb0afa6d4488 100644 --- a/docs/src/main/asciidoc/security-basic-authentication.adoc +++ b/docs/src/main/asciidoc/security-basic-authentication.adoc @@ -62,7 +62,7 @@ Depending on the use case, other authentication mechanisms that delegate usernam 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-getting-started-tutorial.adoc[Getting Started with Security using Basic authentication and Jakarta Persistence] +* xref:security-getting-started-tutorial.adoc[Getting started with Security by using Basic authentication and Jakarta Persistence] == Role-based access control diff --git a/docs/src/main/asciidoc/security-getting-started-tutorial.adoc b/docs/src/main/asciidoc/security-getting-started-tutorial.adoc index e19b2cb2dbd3d..a4676ab997cc7 100644 --- a/docs/src/main/asciidoc/security-getting-started-tutorial.adoc +++ b/docs/src/main/asciidoc/security-getting-started-tutorial.adoc @@ -4,39 +4,37 @@ and pull requests should be submitted there: https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc //// [id="security-getting-started-tutorial"] -= Getting Started with Security using Basic authentication and Jakarta Persistence += Getting started with Security by using Basic authentication and Jakarta Persistence include::_attributes.adoc[] :diataxis-type: tutorial :categories: security,getting-started :topics: security,authentication,basic-authentication,http :extensions: io.quarkus:quarkus-vertx-http,io.quarkus:quarkus-elytron-security-jdbc,io.quarkus:quarkus-elytron-security-ldap,io.quarkus:quarkus-security-jpa-reactive -Get started with Quarkus Security by securing your Quarkus application endpoints with the built-in Quarkus xref:security-basic-authentication.adoc[Basic authentication] and the Jakarta Persistence identity provider and enabling role-based access control. +Get started with Quarkus Security by securing your Quarkus application endpoints with the built-in Quarkus xref:security-basic-authentication.adoc[Basic authentication] and the Jakarta Persistence identity provider, enabling role-based access control. -The Jakarta Persistence `IdentityProvider` verifies and converts a xref:security-basic-authentication.adoc[Basic authentication] user name and password pair to a `SecurityIdentity` instance which is used to authorize access requests, making your Quarkus application secure. +The Jakarta Persistence `IdentityProvider` verifies and converts a xref:security-basic-authentication.adoc[Basic authentication] user name and password pair to a `SecurityIdentity` instance, which is used to 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] guide. -This tutorial prepares you for implementing more advanced security mechanisms in Quarkus, for example, how to use the OpenID Connect (OIDC) authentication mechanism. +This tutorial prepares you to implement more advanced security mechanisms in Quarkus, for example, how to use the OpenID Connect (OIDC) authentication mechanism. == Prerequisites include::{includes}/prerequisites.adoc[] -== What you will build +== Building your application -To demonstrate different authorization policies, the steps in this tutorial guide you through building an application that provides the following endpoints: +This tutorial gives detailed steps for creating an application with endpoints that illustrate various authorization policies: [cols="20%,40% ",options="header"] |=== |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). -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. -This endpoint returns the caller's username as a string. +|`/api/public`| Accessible without authentication, this endpoint allows anonymous access. +a| `/api/admin`| Secured with role-based access control (RBAC), this endpoint is accessible only to users with the `admin` role. +Access is controlled declaratively by using the `@RolesAllowed` annotation. +a| `/api/users/me`| Also secured by RBAC, this endpoint is accessible only to users with the `user` role. +It returns the caller's username as a string. |=== [TIP] @@ -56,11 +54,11 @@ You can find the solution in the `security-jpa-quickstart` link:{quickstarts-tre == Create and verify the Maven project -For Quarkus Security to be able to map your security source to Jakarta Persistence entities, ensure that the Maven project that is used in this tutorial includes the `security-jpa` or the `security-jpa-reactive` extension. +For Quarkus Security to be able to map your security source to Jakarta Persistence entities, ensure that the Maven project in this tutorial includes the `security-jpa` or `security-jpa-reactive` extension. [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. +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. 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. @@ -70,7 +68,8 @@ The instructions in this example tutorial use a PostgreSQL database for the iden === Create the Maven project -You can either create a new Maven project with the Security Jakarta Persistence extension or you can add the extension to an existing Maven project. You can use either Hibernate ORM or Hibernate Reactive. +You can create a new Maven project with the Security Jakarta Persistence extension or add the extension to an existing Maven project. +You can use either Hibernate ORM or Hibernate Reactive. * To create a new Maven project with the Jakarta Persistence extension, complete one of the following steps: ** To create the Maven project with Hibernate ORM, use the following command: @@ -253,7 +252,7 @@ public class User extends PanacheEntity { /** * Adds a new user to the database * @param username the username - * @param password the unencrypted password (it will be encrypted with bcrypt) + * @param password the unencrypted password (it is encrypted with bcrypt) * @param role the comma-separated roles */ public static void add(String username, String password, String role) { <5> @@ -267,9 +266,9 @@ public class User extends PanacheEntity { ---- -The `security-jpa` extension initializes only if a single entity is annotated with `@UserDefinition`. +The `security-jpa` extension only initializes 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. +<1> The `@UserDefinition` annotation must be present on a single entity, 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. @@ -296,7 +295,7 @@ For more information, see link:{quickstarts-tree-url}/security-jpa-reactive-qui + [NOTE] ==== -When secure access is required and no other authentication mechanisms are enabled, the built-in xref:security-basic-authentication.adoc[Basic authentication] of Quarkus is the fallback authentication mechanism. +When secure access is required, and no other authentication mechanisms are enabled, the built-in xref:security-basic-authentication.adoc[Basic authentication] of Quarkus is the fallback authentication mechanism. Therefore, in this tutorial, you do not need to set the property `quarkus.http.auth.basic` to `true`. ==== + @@ -322,7 +321,7 @@ quarkus.hibernate-orm.database.generation=drop-and-create [NOTE] ==== * 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. +configuration property and not the `quarkus.datasource.jdbc.url` configuration property typically used by JDBC datasources. + [source,properties] ---- @@ -332,7 +331,7 @@ configuration property and not the `quarkus.datasource.jdbc.url` configuration p * 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. +Therefore, adjustments are needed in a production environment. ==== [source,java] @@ -393,7 +392,7 @@ testImplementation("io.rest-assured:rest-assured") include::{includes}/devtools/dev.adoc[] -* The following properties configuration demonstrates how you can enable PostgreSQL testing to run in production (`prod`) mode only. +* The following properties configuration demonstrates how to enable PostgreSQL testing to run only in production (`prod`) mode. In this scenario, `Dev Services for PostgreSQL` launches and configures a `PostgreSQL` test container. [source,properties] @@ -481,11 +480,11 @@ As you can see in this code sample, you do not need to start the test container [NOTE] ==== When you start your application in dev mode, Dev Services for PostgreSQL launches a PostgreSQL dev mode 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. +While developing your application, you can add and run tests individually by 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 dev mode container. ==== -=== Use Curl or a browser to test your application +=== Use curl or a browser to test your application * Use the following example to start the PostgreSQL server: [source,bash] @@ -580,13 +579,13 @@ You can also access the same endpoint URLs by using a browser. [NOTE] ==== -If 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 connect to a protected resource anonymously, a Basic authentication form displays, prompting you to enter credentials. ==== === Results -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. +When you provide the credentials of an authorized user, for example, `admin:admin`, the Jakarta Persistence security extension authenticates and loads the user's roles. 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 shown in the following example: @@ -602,7 +601,7 @@ Content-Type: text/html;charset=UTF-8 Forbidden ---- -Finally, the user named `user` is authorized and the security context contains the principal details, for example, the username. +Finally, the user named `user` is authorized, and the security context contains the principal details, for example, the username. [source,shell] ---- @@ -619,8 +618,8 @@ user == What's next -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. +You have successfully learned how to create and test a secure Quarkus application. +This was achieved by integrating the built-in xref:security-basic-authentication.adoc[Basic authentication] in Quarkus with the Jakarta Persistence identity provider. 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: diff --git a/docs/src/main/asciidoc/security-identity-providers.adoc b/docs/src/main/asciidoc/security-identity-providers.adoc index 234358233b621..aee512286f909 100644 --- a/docs/src/main/asciidoc/security-identity-providers.adoc +++ b/docs/src/main/asciidoc/security-identity-providers.adoc @@ -27,7 +27,7 @@ To get started with security in Quarkus, consider combining the Quarkus built-in For more information about Basic authentication, its mechanisms, and related identity providers, see the following resources: * xref:security-jpa.adoc[Quarkus Security with Jakarta Persistence] -** xref:security-getting-started-tutorial.adoc[Getting Started with Security using Basic authentication and Jakarta Persistence] +** xref:security-getting-started-tutorial.adoc[Getting started with Security by using Basic authentication and Jakarta Persistence] * xref:security-authentication-mechanisms.adoc#form-auth[Form-based authentication] * xref:security-jdbc.adoc[Using security with JDBC] * xref:security-ldap.adoc[Using security with an LDAP realm] diff --git a/docs/src/main/asciidoc/security-jdbc.adoc b/docs/src/main/asciidoc/security-jdbc.adoc index 52b58c65ae623..e9447819c373a 100644 --- a/docs/src/main/asciidoc/security-jdbc.adoc +++ b/docs/src/main/asciidoc/security-jdbc.adoc @@ -185,7 +185,7 @@ INSERT INTO test_user (id, username, password, role) VALUES (2, 'user','user', ' ==== It is probably useless, but we kindly remind you that you must not store clear-text passwords in production environment ;-). The `elytron-security-jdbc` extension offers a built-in bcrypt password mapper. -Please refer to the xref:security-getting-started-tutorial.adoc#define-the-user-entity[Define the user entity] section of the Getting Started with Security using Basic authentication and Jakarta Persistence tutorial for practical example. +Please refer to the xref:security-getting-started-tutorial.adoc#define-the-user-entity[Define the user entity] section of the Getting started with Security by using Basic authentication and Jakarta Persistence tutorial for practical example. ==== We can now configure the Elytron JDBC Realm. diff --git a/docs/src/main/asciidoc/security-jpa.adoc b/docs/src/main/asciidoc/security-jpa.adoc index 3317e9e813a67..d114c46cf9666 100644 --- a/docs/src/main/asciidoc/security-jpa.adoc +++ b/docs/src/main/asciidoc/security-jpa.adoc @@ -80,7 +80,7 @@ public class User extends PanacheEntity { 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, either a regular Hibernate ORM entity or a Hibernate ORM with a Panache entity. +<1> The `@UserDefinition` annotation must be present on a single entity, 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, `security-jpa` uses bcrypt-hashed passwords, or you can configure plain text or custom passwords instead. @@ -222,6 +222,6 @@ include::{generated-dir}/config/quarkus-security-jpa.adoc[opts=optional, levelof == References -* xref:security-getting-started-tutorial.adoc[Getting Started with Security by using Basic authentication and Jakarta Persistence] +* xref:security-getting-started-tutorial.adoc[Getting started with Security by using Basic authentication and Jakarta Persistence] * xref:security-identity-providers.adoc[Identity providers] * xref:security-overview.adoc[Quarkus Security overview] diff --git a/docs/src/main/asciidoc/security-overview.adoc b/docs/src/main/asciidoc/security-overview.adoc index 066c08635b3ed..6bad18e92531c 100644 --- a/docs/src/main/asciidoc/security-overview.adoc +++ b/docs/src/main/asciidoc/security-overview.adoc @@ -43,7 +43,7 @@ For more information, see the Quarkus xref:security-customization.adoc[Security To get started with security in Quarkus, consider securing your Quarkus application endpoints with the built-in Quarkus xref:security-basic-authentication.adoc[Basic authentication] and the Jakarta Persistence identity provider and enabling role-based access control. -Complete the steps in the xref:security-getting-started-tutorial.adoc[Getting Started with Security using Basic authentication and Jakarta Persistence] tutorial. +Complete the steps in the xref:security-getting-started-tutorial.adoc[Getting started with Security by using Basic authentication and Jakarta Persistence] tutorial. After successfully securing your Quarkus application with Basic authentication, you can increase the security further by adding more advanced authentication mechanisms, for example, the Quarkus xref:security-oidc-code-flow-authentication.adoc[OpenID Connect (OIDC) authorization code flow mechanism] guide. @@ -103,6 +103,6 @@ For information about security vulnerabilities, see the xref:security-vulnerabil == References * xref:security-basic-authentication.adoc[Basic authentication] -* xref:security-getting-started-tutorial.adoc[Getting Started with Security using Basic authentication and Jakarta Persistence] +* xref:security-getting-started-tutorial.adoc[Getting started with Security by using Basic authentication and Jakarta Persistence] * xref:security-oidc-code-flow-authentication-tutorial.adoc[Protect a web application by using OIDC authorization code flow] * xref:security-oidc-bearer-token-authentication-tutorial.adoc[Protect a service application by using OIDC Bearer token authentication]