Skip to content

Commit

Permalink
QDOCS-570: complete final editing checks
Browse files Browse the repository at this point in the history
  • Loading branch information
@sheilamjones
sheilamjones committed Jan 4, 2024
1 parent 2e6fe10 commit c5f638e
Showing 1 changed file with 30 additions and 29 deletions.
59 changes: 30 additions & 29 deletions docs/src/main/asciidoc/security-oidc-code-flow-authentication-tutorial.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ With the Quarkus OpenID Connect (OIDC) extension, you can protect application HT

To learn more about the OIDC authorization code flow mechanism, see xref:security-oidc-code-flow-authentication.adoc[OIDC code flow mechanism for protecting web applications].

To learn about how well-known social providers such as Apple, Facebook, GitHub, Google, Mastodon, Microsoft, Twitch, Twitter (X), and Spotify can be used with Quarkus OIDC, see xref:security-openid-connect-providers.adoc[Configuring Well-Known OpenID Connect Providers].
To learn about how well-known social providers such as Apple, Facebook, GitHub, Google, Mastodon, Microsoft, Twitch, Twitter (X), and Spotify can be used with Quarkus OIDC, see xref:security-openid-connect-providers.adoc[Configuring well-known OpenID Connect providers].
See also, xref:security-authentication-mechanisms.adoc#other-supported-authentication-mechanisms[Authentication mechanisms in Quarkus].

If you want to protect your service applications by using OIDC Bearer token authentication, see xref:security-oidc-bearer-token-authentication.adoc[OIDC Bearer token authentication].
Expand All @@ -27,18 +27,18 @@ include::{includes}/prerequisites.adoc[]

== Architecture

In this example, we build a very simple web application with a single page:
In this example, we build a simple web application with a single page:

* `/index.html`

This page is protected and can only be accessed by authenticated users.
This page is protected and only authenticated users can access the page.

== Solution

We recommend that you follow the instructions in the next sections and create the application step by step.
However, you can go right to the completed example.
Follow the instructions in the next sections and create the application step by step.
Alternatively, you can go right to the completed example.

Clone the Git repository: `git clone {quickstarts-clone-url}`, or download an {quickstarts-archive-url}[archive].
Clone the Git repository by using `git clone {quickstarts-clone-url}`, or download an {quickstarts-archive-url}[archive].

The solution is located in the `security-openid-connect-web-authentication-quickstart` link:{quickstarts-tree-url}/security-openid-connect-web-authentication-quickstart[directory].

Expand All @@ -48,7 +48,7 @@ The solution is located in the `security-openid-connect-web-authentication-quick
== Create the Maven project

First, we need a new project.
Create a new project with the following command:
Create a new project by running the following command:

:create-app-artifact-id: security-openid-connect-web-authentication-quickstart
:create-app-extensions: resteasy-reactive,oidc
Expand Down Expand Up @@ -78,7 +78,7 @@ implementation("io.quarkus:quarkus-oidc")

== Write the application

Let's write a simple Jakarta REST resource which has all the tokens returned in the authorization code grant response injected:
Let's write a simple Jakarta REST resource, which has all the tokens returned in the authorization code grant response injected:

[source,java]
----
Expand All @@ -99,27 +99,28 @@ import io.quarkus.oidc.RefreshToken;
public class TokenResource {
/**
* Injection point for the ID Token issued by the OpenID Connect Provider
* Injection point for the ID token issued by the OpenID Connect provider
*/
@Inject
@IdToken
JsonWebToken idToken;
/**
* Injection point for the Access Token issued by the OpenID Connect Provider
* Injection point for the access token issued by the OpenID Connect provider
*/
@Inject
JsonWebToken accessToken;
/**
* Injection point for the Refresh Token issued by the OpenID Connect Provider
* Injection point for the refresh token issued by the OpenID Connect provider
*/
@Inject
RefreshToken refreshToken;
/**
* Returns the tokens available to the application. This endpoint exists only for demonstration purposes, you should not
* expose these tokens in a real application.
* Returns the tokens available to the application.
* This endpoint exists only for demonstration purposes.
* Do not expose these tokens in a real application.
*
* @return a HTML page containing the tokens available to the application
*/
Expand Down Expand Up @@ -153,13 +154,13 @@ public class TokenResource {
This endpoint has ID, access, and refresh tokens injected.
It returns a `preferred_username` claim from the ID token, a `scope` claim from the access token, and also a refresh token availability status.

Note that you do not have to inject the tokens - it is only required if the endpoint needs to use the ID token to interact with the currently authenticated user or use the access token to access a downstream service on behalf of this user.
Note that you do not have to inject the tokens - it is only required if the endpoint needs to use the ID token to interact with the currently-authenticated user or use the access token to access a downstream service on behalf of this user.

Check warning on line 157 in docs/src/main/asciidoc/security-oidc-code-flow-authentication-tutorial.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.SentenceLength] Try to keep sentences to an average of 32 words or fewer.

Raw Output:
{"message": "[Quarkus.SentenceLength] Try to keep sentences to an average of 32 words or fewer.", "location": {"path": "docs/src/main/asciidoc/security-oidc-code-flow-authentication-tutorial.adoc", "range": {"start": {"line": 157, "column": 1}}}, "severity": "INFO"}

Check warning on line 157 in docs/src/main/asciidoc/security-oidc-code-flow-authentication-tutorial.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/security-oidc-code-flow-authentication-tutorial.adoc", "range": {"start": {"line": 157, "column": 1}}}, "severity": "INFO"}

Check warning on line 157 in docs/src/main/asciidoc/security-oidc-code-flow-authentication-tutorial.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'needs to'.

Raw Output:
{"message": "[Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'needs to'.", "location": {"path": "docs/src/main/asciidoc/security-oidc-code-flow-authentication-tutorial.adoc", "range": {"start": {"line": 157, "column": 86}}}, "severity": "INFO"}

// SJ: TO DO - update link to point to new reference guide. For more information, see <<access_id_and_access_tokens,Access ID and Access Tokens>> section.

== Configure the application

The OIDC extension allows you to define the configuration using the `application.properties` file which should be located at the `src/main/resources` directory.
The OIDC extension allows you to define the configuration by using the `application.properties` file, which is located in the `src/main/resources` directory.

[source,properties]
----
Expand All @@ -179,7 +180,7 @@ The `quarkus.oidc.application-type` property is set to `web-app` in order to tel

Finally, the `quarkus.http.auth.permission.authenticated` permission is set to tell Quarkus about the paths you want to protect.
In this case, all paths are being protected by a policy that ensures that only `authenticated` users are allowed to access.
For more information, see xref:security-authorize-web-endpoints-reference.adoc[Security Authorization Guide].
For more information, see xref:security-authorize-web-endpoints-reference.adoc[Security authorization guide].

== Start and configure the Keycloak server

Expand All @@ -195,18 +196,18 @@ where `keycloak.version` should be set to `23.0.0` or higher.
You should be able to access your Keycloak Server at http://localhost:8180[localhost:8180].

To access the Keycloak Administration Console, log in as the `admin` user.

Check warning on line 198 in docs/src/main/asciidoc/security-oidc-code-flow-authentication-tutorial.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/security-oidc-code-flow-authentication-tutorial.adoc", "range": {"start": {"line": 198, "column": 39}}}, "severity": "INFO"}
Username should be `admin` and password `admin`.
The username is `admin` and the password is `admin`.

Import the link:{quickstarts-tree-url}/security-openid-connect-web-authentication-quickstart/config/quarkus-realm.json[realm configuration file] to create a new realm.
To create a new realm, import the link:{quickstarts-tree-url}/security-openid-connect-web-authentication-quickstart/config/quarkus-realm.json[realm configuration file].
For more information, see the Keycloak documentation about how to https://www.keycloak.org/docs/latest/server_admin/index.html#configuring-realms[create and configure a new realm].

== Run the application in dev and JVM modes

To run the application in a dev mode, use:
To run the application in dev mode, use:

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

When you're done playing with dev mode, you can run it as a standard Java application.
When you are finished exploring the application in dev mode, you can run it as a standard Java application.

Check warning on line 210 in docs/src/main/asciidoc/security-oidc-code-flow-authentication-tutorial.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/security-oidc-code-flow-authentication-tutorial.adoc", "range": {"start": {"line": 210, "column": 77}}}, "severity": "INFO"}

First, compile it:

Expand All @@ -224,15 +225,14 @@ java -jar target/quarkus-app/quarkus-run.jar
This same demo can be compiled into native code.
No modifications are required.

This implies that you no longer need to install a JVM on your production environment, as the runtime technology is included in
the produced binary, and optimized to run with minimal resource overhead.
This implies that you no longer need to install a JVM on your production environment because the runtime technology is included in the produced binary and optimized to run with minimal resource overhead.

Check warning on line 228 in docs/src/main/asciidoc/security-oidc-code-flow-authentication-tutorial.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'need to'.

Raw Output:
{"message": "[Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'need to'.", "location": {"path": "docs/src/main/asciidoc/security-oidc-code-flow-authentication-tutorial.adoc", "range": {"start": {"line": 228, "column": 33}}}, "severity": "INFO"}

Compilation will take a bit longer, so this step is disabled by default.
You can build again by enabling the native build:

include::{includes}/devtools/build-native.adoc[]

After getting a cup of coffee, you can run this binary directly:
After a while, you can run this binary directly:

[source,bash]
----
Expand All @@ -243,19 +243,20 @@ After getting a cup of coffee, you can run this binary directly:

To test the application, open your browser and access the following URL:


* http://localhost:8080/tokens[http://localhost:8080/tokens]

If everything is working as expected, you are redirected to the Keycloak server to authenticate.

Check warning on line 248 in docs/src/main/asciidoc/security-oidc-code-flow-authentication-tutorial.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/security-oidc-code-flow-authentication-tutorial.adoc", "range": {"start": {"line": 248, "column": 26}}}, "severity": "INFO"}

To authenticate to the application, type the following credentials when at the Keycloak login page:
To authenticate to the application, enter the following credentials at the Keycloak login page:

* Username: *alice*

Check warning on line 252 in docs/src/main/asciidoc/security-oidc-code-flow-authentication-tutorial.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'alice'?

Raw Output:
{"message": "[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'alice'?", "location": {"path": "docs/src/main/asciidoc/security-oidc-code-flow-authentication-tutorial.adoc", "range": {"start": {"line": 252, "column": 14}}}, "severity": "WARNING"}
* Password: *alice*

Check warning on line 253 in docs/src/main/asciidoc/security-oidc-code-flow-authentication-tutorial.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'alice'?

Raw Output:
{"message": "[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'alice'?", "location": {"path": "docs/src/main/asciidoc/security-oidc-code-flow-authentication-tutorial.adoc", "range": {"start": {"line": 253, "column": 14}}}, "severity": "WARNING"}

After clicking the `Login` button, you are redirected back to the application and a session cookie will be created.

The session for this demo is short-lived and you will be asked to re-authenticate on every page refresh. Please follow the Keycloak https://www.keycloak.org/docs/latest/server_admin/#_timeouts[session timeout] documentation to learn how to increase the session timeouts. For example, you can access Keycloak Admin console directly from Dev UI by selecting a `Keycloak Admin` link if you use xref:security-oidc-code-flow-authentication.adoc#integration-testing-keycloak-devservices[Dev Services for Keycloak] in dev mode:
The session for this demo is temporary and, on every page refresh, you will be asked to re-authenticate.
For information about how to increase the session timeouts, see the Keycloak https://www.keycloak.org/docs/latest/server_admin/#_timeouts[session timeout] documentation.
For example, you can access the Keycloak Admin console directly from the dev UI by clicking the `Keycloak Admin` link if you use xref:security-oidc-code-flow-authentication.adoc#integration-testing-keycloak-devservices[Dev Services for Keycloak] in dev mode:

image::dev-ui-oidc-keycloak-card.png[alt=Dev UI OpenID Connect Card,role="center"]

Expand All @@ -270,13 +271,13 @@ After you have completed this tutorial, explore xref:security-oidc-bearer-token-
== References
* xref:security-overview.adoc[Quarkus Security overview]
* xref:security-oidc-code-flow-authentication.adoc[OIDC code flow mechanism for protecting web applications]
* xref:security-openid-connect-providers.adoc[Configuring well-known OpenID Connect Providers]
* xref:security-openid-connect-client-reference.adoc[OpenID Connect and OAuth2 Client and Filters Reference Guide]
* xref:security-openid-connect-providers.adoc[Configuring well-known OpenID Connect providers]
* xref:security-openid-connect-client-reference.adoc[OpenID Connect and OAuth2 Client and Filters reference guide]
* xref:security-openid-connect-dev-services.adoc[Dev Services for Keycloak]
* xref:security-jwt-build.adoc[Sign and encrypt JWT tokens with SmallRye JWT Build]
* xref:security-authentication-mechanisms.adoc#oidc-jwt-oauth2-comparison[Choosing between OpenID Connect, SmallRye JWT, and OAuth2 authentication mechanisms]
* xref:security-keycloak-admin-client.adoc[Quarkus Keycloak Admin Client]
* https://www.keycloak.org/documentation.html[Keycloak Documentation]
* xref:security-oidc-auth0-tutorial.adoc[Protect Quarkus web application by using Auth0 OpenID Connect provider]
* https://openid.net/connect/[OpenID Connect]
* https://tools.ietf.org/html/rfc7519[JSON Web Token]
* https://tools.ietf.org/html/rfc7519[JSON Web token]

0 comments on commit c5f638e

Please sign in to comment.