Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Multiple changes for spring-security guide #37560

Merged
merged 1 commit into from
Dec 6, 2023
Merged

Multiple changes for spring-security guide #37560

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 37 additions & 17 deletions docs/src/main/asciidoc/spring-security.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,10 +33,12 @@
First, we need a new project. Create a new project with the following command:

:create-app-artifact-id: spring-security-quickstart
:create-app-group-id: org.acme.spring.security
:create-app-extensions: spring-web,spring-security,quarkus-elytron-security-properties-file,resteasy-reactive-jackson
:create-app-code:
include::{includes}/devtools/create-app.adoc[]

This command generates a project which imports the `spring-web`, `spring-security` and `security-properties-file` extensions.

Check warning on line 41 in docs/src/main/asciidoc/spring-security.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using ', which (non restrictive clause preceded by a comma)' or 'that (restrictive clause without a comma)' rather than 'which'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using ', which (non restrictive clause preceded by a comma)' or 'that (restrictive clause without a comma)' rather than 'which'.", "location": {"path": "docs/src/main/asciidoc/spring-security.adoc", "range": {"start": {"line": 41, "column": 33}}}, "severity": "INFO"}

If you already have your Quarkus project configured, you can add the `spring-web`, `spring-security` and `security-properties-file` extensions
to your project by running the following command in your project base directory:
Expand Down Expand Up @@ -78,10 +80,10 @@

For more information about `security-properties-file`, you can check out the guide of the xref:security-properties.adoc[quarkus-elytron-security-properties-file] extension.

== GreetingController

Check warning on line 83 in docs/src/main/asciidoc/spring-security.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Headings] Use sentence-style capitalization in 'GreetingController'.

Raw Output:
{"message": "[Quarkus.Headings] Use sentence-style capitalization in 'GreetingController'.", "location": {"path": "docs/src/main/asciidoc/spring-security.adoc", "range": {"start": {"line": 83, "column": 4}}}, "severity": "INFO"}

The Quarkus Maven plugin automatically generated a controller with the Spring Web annotations to define our REST endpoint (instead of the Jakarta REST ones used by default).
First create a `src/main/java/org/acme/spring/web/GreetingController.java`, a controller with the Spring Web annotations to define our REST endpoint, as follows:
First create a `src/main/java/org/acme/spring/security/GreetingController.java`, a controller with the Spring Web annotations to define our REST endpoint, as follows:

Check warning on line 86 in docs/src/main/asciidoc/spring-security.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.", "location": {"path": "docs/src/main/asciidoc/spring-security.adoc", "range": {"start": {"line": 86, "column": 145}}}, "severity": "INFO"}

[source,java]
----
Expand All @@ -97,7 +99,7 @@

@GetMapping
public String hello() {
return "hello";
return "Hello Spring";
}
}
----
Expand All @@ -117,15 +119,14 @@
import static org.hamcrest.CoreMatchers.is;

@QuarkusTest
public class GreetingControllerTest {

class GreetingControllerTest {
@Test
public void testHelloEndpoint() {
void testHelloEndpoint() {
given()
.when().get("/greeting")
.then()
.statusCode(200)
.body(is("hello"));
.body(is("Hello Spring"));
}

}
Expand All @@ -141,7 +142,8 @@

The result should be: `{"message": "hello"}`.

[#secure]
== Modify the controller to secure the `hello` method

Check warning on line 146 in docs/src/main/asciidoc/spring-security.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Fluff] Depending on the context, consider using 'Be concise: use 'to' rather than' rather than 'In order to'.

Raw Output:
{"message": "[Quarkus.Fluff] Depending on the context, consider using 'Be concise: use 'to' rather than' rather than 'In order to'.", "location": {"path": "docs/src/main/asciidoc/spring-security.adoc", "range": {"start": {"line": 146, "column": 45}}}, "severity": "INFO"}

Check warning on line 146 in docs/src/main/asciidoc/spring-security.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsWarnings] Consider using 'to' rather than 'In order to' unless updating existing content that uses the term.

Raw Output:
{"message": "[Quarkus.TermsWarnings] Consider using 'to' rather than 'In order to' unless updating existing content that uses the term.", "location": {"path": "docs/src/main/asciidoc/spring-security.adoc", "range": {"start": {"line": 146, "column": 45}}}, "severity": "WARNING"}

In order to restrict access to the `hello` method to users with certain roles, the `@Secured` annotation will be utilized.
The updated controller will be:
Expand Down Expand Up @@ -220,6 +222,16 @@

== Test the changes

=== Automatically

Press `r`, while in DevMode, or run the application with:

include::{includes}/devtools/test.adoc[]

All tests should succeed.

=== Manually

Access allowed::

Open your browser again to http://localhost:8080/greeting and introduce `scott` and `jb0ss` in the dialog displayed.
Expand All @@ -239,15 +251,14 @@
HTTP ERROR 403
----

== Run the application as a native executable

You can generate the native executable with:

include::{includes}/devtools/build-native.adoc[]
[TIP]
====
Some browsers save credentials for basic authentication. If the dialog is not displayed, try to clear saved logins or use the Private mode

Check warning on line 256 in docs/src/main/asciidoc/spring-security.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.CaseSensitiveTerms] Use 'Basic HTTP authentication (first instance)' or 'Basic authentication' rather than 'basic authentication'.

Raw Output:
{"message": "[Quarkus.CaseSensitiveTerms] Use 'Basic HTTP authentication (first instance)' or 'Basic authentication' rather than 'basic authentication'.", "location": {"path": "docs/src/main/asciidoc/spring-security.adoc", "range": {"start": {"line": 256, "column": 36}}}, "severity": "INFO"}
====

== Supported Spring Security functionalities
== Supported Spring Security annotations

Check warning on line 259 in docs/src/main/asciidoc/spring-security.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Headings] Use sentence-style capitalization in 'Supported Spring Security annotations'.

Raw Output:
{"message": "[Quarkus.Headings] Use sentence-style capitalization in 'Supported Spring Security annotations'.", "location": {"path": "docs/src/main/asciidoc/spring-security.adoc", "range": {"start": {"line": 259, "column": 4}}}, "severity": "INFO"}

Quarkus currently only supports a subset of the functionalities that Spring Security provides with more features being planned. More specifically, Quarkus supports the security related features of role-based authorization semantics
Quarkus currently only supports a subset of the functionality that Spring Security provides with more features being planned. More specifically, Quarkus supports the security related features of role-based authorization semantics
(think of `@Secured` instead of `@RolesAllowed`).

=== Annotations
Expand All @@ -256,13 +267,15 @@

.Supported Spring Security annotations
|===
|Name|Comments
|Name|Comments|Spring documentation

|@Secured
|
| See <<secure, above>>
| link:https://docs.spring.io/spring-security/reference/servlet/authorization/method-security.html#use-secured[Authorizing Method Invocation with @Secured]

|@PreAuthorize
|See next section for more details
|link:https://docs.spring.io/spring-security/reference/servlet/authorization/method-security.html#use-preauthorize[Authorizing Method Invocation with @PreAuthorize]

|===

Expand Down Expand Up @@ -320,6 +333,7 @@
this.name = name;
}

// this syntax requires getters for field access
public String getName() {
return name;
}
Expand Down Expand Up @@ -373,7 +387,6 @@
@Component
public class PersonChecker {

@Override
public boolean check(Person person, String username) {
return person.getName().equals(username);
}
Expand Down Expand Up @@ -407,10 +420,13 @@

}
----
[IMPORTANT]
====
Currently, expressions do not support parentheses for logical operators and are evaluated from left to right
====

Also to be noted that currently parentheses are not supported and expressions are evaluated from left to right when needed.

== Important Technical Note

Check warning on line 429 in docs/src/main/asciidoc/spring-security.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Fluff] Depending on the context, consider using 'Be concise: rewrite the sentence to not use' rather than 'note that'.

Raw Output:
{"message": "[Quarkus.Fluff] Depending on the context, consider using 'Be concise: rewrite the sentence to not use' rather than 'note that'.", "location": {"path": "docs/src/main/asciidoc/spring-security.adoc", "range": {"start": {"line": 429, "column": 26}}}, "severity": "INFO"}

Please note that the Spring support in Quarkus does not start a Spring Application Context nor are any Spring infrastructure classes run.
Spring classes and annotations are only used for reading metadata and / or are used as user code method return types or parameter types.
Expand All @@ -428,9 +444,13 @@
|@RolesAllowed("admin")
|

|@PreAuthorize
|No direct replacement
|Quarkus handles complex authorisation differently, see link:https://quarkus.io/guides/security-authorize-web-endpoints-reference[this guide] for details

|===

== More Spring guides

Check warning on line 453 in docs/src/main/asciidoc/spring-security.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Headings] Use sentence-style capitalization in 'More Spring guides'.

Raw Output:
{"message": "[Quarkus.Headings] Use sentence-style capitalization in 'More Spring guides'.", "location": {"path": "docs/src/main/asciidoc/spring-security.adoc", "range": {"start": {"line": 453, "column": 4}}}, "severity": "INFO"}

Quarkus has more Spring compatibility features. See the following guides for more details:

Expand Down