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

Docs - Add missing steps to Basic authentication how-to #37121

Merged
merged 1 commit into from
Nov 16, 2023
Merged

Docs - Add missing steps to Basic authentication how-to #37121

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
22 changes: 19 additions & 3 deletions docs/src/main/asciidoc/security-basic-authentication-howto.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,23 +15,39 @@ 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.
For example:

** xref:security-jpa.adoc[Quarkus Security Jakarta Persistence extensions (`security-jpa` or `security-jpa-reactive`)]
** xref:security-properties.adoc[Elytron security properties file extension `(quarkus-elytron-security-properties-file)`]
** xref:security-jdbc.adoc[Elytron security JDBC extension `(quarkus-elytron-security-jdbc)`]

The following procedure outlines how you can enable Basic authentication for your application by using the `elytron-security-properties-file` extension.

== Procedure

. Enable Basic authentication by setting the `quarkus.http.auth.basic` property to `true`.
. In the `application.properties` file, set the `quarkus.http.auth.basic` property to `true`.
+
[source,properties]
----
quarkus.http.auth.basic=true
----

. For testing purposes, you can configure the required user credentials, user name, secret, and roles, in the `application.properties` file.
. **Optional:** In a non-production environment only and purely for testing Quarkus Security in your applications:
.. To enable authentication for the embedded realm, set the `quarkus.security.users.embedded.enabled` property to `true`.
+
[source,properties]
----
security.users.embedded.enabled=true
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry Michelle but I'm not sure we need to highlight this property at all, I don't recall ever using it for tests

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is enabled by default I guess, so may be below it works but if if it is enabled by default then it is 1 extra property to configure

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, I use it here https://github.com/quarkusio/quarkus/blob/main/integration-tests/csrf-reactive/src/main/resources/application.properties#L6 :-) but I'd not highlight in isolation, below it is fine

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry for the noise, if you'd like to highlight then it is fine, but IMHO it it should all be again done below, otherwise it reads as if it can be used outside of the testing, which it technically can be but we don't recommend it

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The default is false - see https://quarkus.io/guides/all-config#quarkus-elytron-security-properties-file_quarkus.security.users.embedded.enabled

I think it's fine to have the property just in the example bellow. IMHO no need to highlight this property in this separate part

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 to @rsvoboda's suggestion.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@sberyozkin , @rsvoboda , @jsmrcka

Thank you for your input and reviews on this bit too.

I think we have to keep in mind that the person reading this introductory-level how-to topic is likely to be new to Quarkus and is therefore likely 'playing' in a test environment. So while we don't recommend it for production, +1 to keeping it in and being consistent elsewhere.

I made some adjustments to the procedure to highlight that some configuration steps are purely for testing purposes. How does this look now?

image

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rsvoboda & @jsmrcka - I also propose that we diverge in the product version a little and either:

  • Add a support note to the prereq section to highlight the extensions that we don't support
  • Remove the extension altogether from the list in the product version

( @tqvarnst @inoxx03 & @[email protected] FYI)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

prereq section should be sufficient, otherwise we would need to drop all 3 mentioned extensions :)

----

.. You can also configure the required user credentials, user name, secret, and roles.
For example:
+
[source,properties]
----
quarkus.http.auth.basic=true
quarkus.security.users.embedded.enabled=true
quarkus.security.users.embedded.plain-text=true
quarkus.security.users.embedded.users.alice=alice <1>
quarkus.security.users.embedded.users.bob=bob <2>
Expand Down