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 5, 2024
1 parent e87a492 commit 64232e8
Showing 1 changed file with 37 additions and 33 deletions.
70 changes: 37 additions & 33 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,19 @@ 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 it.

== 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 running the `git clone {quickstarts-clone-url}` command.
Alternatively, 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 +49,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 +79,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,29 +100,30 @@ 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
* @return an HTML page containing the tokens available to the application.
*/
@GET
@Produces("text/html")
Expand Down Expand Up @@ -159,7 +161,7 @@ Note that you do not have to inject the tokens - it is only required if the endp

== 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 @@ -173,13 +175,13 @@ quarkus.http.auth.permission.authenticated.policy=authenticated

This is the simplest configuration you can have when enabling authentication to your application.

The `quarkus.oidc.client-id` property references the `client_id` issued by the OIDC provider and the `quarkus.oidc.credentials.secret` property sets the client secret.
The `quarkus.oidc.client-id` property references the `client_id` issued by the OIDC provider, and the `quarkus.oidc.credentials.secret` property sets the client secret.

The `quarkus.oidc.application-type` property is set to `web-app` in order to tell Quarkus that you want to enable the OIDC authorization code flow, so that your users are redirected to the OIDC provider to authenticate.
The `quarkus.oidc.application-type` property is set to `web-app` to tell Quarkus that you want to enable the OIDC authorization code flow so that your users are redirected to the OIDC provider to authenticate.

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].
In this case, all paths are being protected by a policy ensuring that only `authenticated` users can access them.
For more information, see xref:security-authorize-web-endpoints-reference.adoc[Security authorization guide].

== Start and configure the Keycloak server

Expand All @@ -195,18 +197,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 199 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": 199, "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.
After exploring the application in dev mode, you can run it as a standard Java application.

Check warning on line 211 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": 211, "column": 61}}}, "severity": "INFO"}

First, compile it:

Expand All @@ -224,15 +226,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 229 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": 229, "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,24 +244,27 @@ 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.
If everything works as expected, you are redirected to the Keycloak server to authenticate.

Check warning on line 249 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": 249, "column": 21}}}, "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 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"}
* Password: *alice*

Check warning on line 254 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": 254, "column": 14}}}, "severity": "WARNING"}

After clicking the `Login` button, you are redirected back to the application and a session cookie will be created.
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 valid for a short period of time 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"]

For more information about writing the integration tests that depend on `Dev Services for Keycloak`, see the xref:security-oidc-code-flow-authentication.adoc#integration-testing-keycloak-devservices[Dev Services for Keycloak] section.

:sectnums!:

== Summary

Congratulations!
Expand All @@ -270,8 +274,8 @@ 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]
Expand Down

0 comments on commit 64232e8

Please sign in to comment.