diff --git a/docs/src/main/asciidoc/security-oidc-code-flow-authentication-tutorial.adoc b/docs/src/main/asciidoc/security-oidc-code-flow-authentication-tutorial.adoc index 157370f05a139..5346d3e3097da 100644 --- a/docs/src/main/asciidoc/security-oidc-code-flow-authentication-tutorial.adoc +++ b/docs/src/main/asciidoc/security-oidc-code-flow-authentication-tutorial.adoc @@ -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]. @@ -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]. @@ -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 @@ -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] ---- @@ -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") @@ -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] ---- @@ -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 @@ -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. -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. First, compile it: @@ -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. 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] ---- @@ -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. -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* * Password: *alice* -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! @@ -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]