Docs: security-oidc-bearer-token-authentication-tutorial guide

[jedla97]

Describe the bug

Going through the security-oidc-bearer-token-authentication-tutorial guide I found some issues.

1. Procedure headlines start with dot which is quite unusual. Example .1. Headline.
2. When creating app there is missing info that extension quarkus-resteasy-reactive should be added. Quickstart using quarkus-resteasy-reactive-jackson.
3. Section Using Gradle (build.gradle): is there but missing text. There should be equivalent of maven pom added extension.
4. Text defining keycloak.version should be probably updated. It's recommend 17.0.0+ but now 22.x and 23.x versions are based on Quarkus 3.x. It would be nice to bump it little. I tested it with 17.0.0 and the guide is work fine but there is possible in more complex scenarios it can fail using older Keycloak. I search through source code and the 17.0.0+ is in more guides.
5. Links getting 404:
   - Keycloak link to creating a new realm should be https://www.keycloak.org/docs/latest/server_admin/index.html#proc-creating-a-realm_server_administration_guide
   - Quarkus Keycloak Admin Client should be https://quarkus.io/version/main/guides/security-keycloak-admin-client
   - Dev Services for Keycloak link to should be https://quarkus.io/version/main/guides/security-openid-connect-dev-services
   - Dev UI should be https://quarkus.io/version/main/guides/dev-ui
   - In references maybe the Dev Services for Keycloak should point out at https://quarkus.io/version/main/guides/security-openid-connect-dev-services#dev-services-for-keycloak
6. In dev mode the users are now alice (admin) and bob (user). Can be seen in security-oidc-bearer-token-authentication guide.
7. Adding quarkus-realm.json seems have no real effect on dev mode or it's not mention where I should put it or what to do with it except I can use it to create realm in Keycloak with web gui.
8. Dev mode section say accessing the /api/admin or /api/users/me but it not clear where or how. It can be tested in dev-ui login and test the different paths there or it can be tested by curl. For me first thing was put it in browser and try it. But we need token to access with specific user. This is mentioned in testing section. My personal take is that the order of procedure should be like this (using all the procedures mentioned in guide)
   - 1. Create the Maven project
   - 2. Write the application
   - 3. Configure the application
   - 4. Run the application in dev mode
   - 5. Test the application
   - 6. Start and configure the Keycloak server
   - 7. Run the Application in JVM mode
   - 8. Run the application in native mode

The order is my personal take but I definitely wouldn't put Start and configuration of Keycloak before devmode as we need it only with JVM and native mode. For the testing reason is mentioned above. Or it can be last but there it should be something in devmode section how to test it (for example link to testing section)

Expected behavior

No response

Actual behavior

No response

How to Reproduce?

No response

Output of uname -a or ver

No response

Output of java -version

No response

Quarkus version or git rev

No response

Build tool (ie. output of mvnw --version or gradlew --version)

No response

Additional information

No response

[quarkus-bot]

/cc @pedroigor (bearer-token,oidc), @sberyozkin (bearer-token,oidc,security)

[sberyozkin]

@jedla97 Thanks for the review,

Procedure headlines start with dot which is quite unusual. Example .1. Headline.

I agree, I'm not too keen on retaining this style

When creating app there is missing info that extension quarkus-resteasy-reactive should be added. Quickstart using quarkus-resteasy-reactive-jackson.

quarkus-resteasy-reactive-jackson pulls in quarkus-resteasy-reactive so it is fine

Section Using Gradle (build.gradle): is there but missing text. There should be equivalent of maven pom added extension.

Please open an independent issue, it is generated and is not controlled at the individual guide level.

Re points 6-8 - I'll try to clarify a few details, but I'll probably won't be changing the order of sections now, it is a typical flow observed across many tutorials.

Dev mode section say accessing the /api/admin or /api/users/me but it not clear where or how. It can be tested in dev-ui login and test the different paths there or it can be tested by curl

Given this comment I believe it is quite clear how it should be tested, thanks

[sberyozkin]

@jedla97 I've started working on the PR

[sberyozkin]

@jedla97 I'm opening a PR now, here are the changes given your comments:

Procedure headlines start with dot which is quite unusual. Example .1. Headline.

Fixed it

When creating app there is missing info that extension quarkus-resteasy-reactive should be added. Quickstart using quarkus-resteasy-reactive-jackson.

As mentioned above, it pulled in transitively

Section Using Gradle (build.gradle): is there but missing text. There should be equivalent of maven pom added extension.

Might be a localbuild related, if I click Gradle at https://quarkus.io/version/main/guides/security-oidc-bearer-token-authentication-tutorial, all looks correct

Text defining keycloak.version should be probably updated. It's recommend 17.0.0+ but now 22.x and 23.x versions are based on Quarkus 3.x. It would be nice to bump it little. I tested it with 17.0.0 and the guide is work fine but there is possible in more complex scenarios it can fail using older Keycloak. I search through source code and the 17.0.0+ is in more guides.

Fixed for this guide and will continue in other guides

Links getting 404:

• Keycloak link to creating a new realm should be https://www.keycloak.org/docs/latest/server_admin/index.html#proc-creating-a-realm_server_administration_guide
• Quarkus Keycloak Admin Client should be https://quarkus.io/version/main/guides/security-keycloak-admin-client
• Dev Services for Keycloak link to should be https://quarkus.io/version/main/guides/security-openid-connect-dev-services
• Dev UI should be https://quarkus.io/version/main/guides/dev-ui

Fixed, the template used right now does not resolve correctly

In references maybe the Dev Services for Keycloak should point out at https://quarkus.io/version/main/guides/security-openid-connect-dev-services#dev-services-for-keycloak

IMHO it is not necessary, there is only Introduction before that section in that doc

In dev mode the users are now alice (admin) and bob (user). Can be seen in security-oidc-bearer-token-authentication guide. Adding quarkus-realm.json seems have no real effect on dev mode or it's not mention where I should put it or what to do with it except I can use it to create realm in Keycloak with web gui.

The configuration example in this tutorial just above where alice and admin are mentioned has this:

# Tell Dev Services for Keycloak to import the realm file
# This property is not effective when running the application in JVM or Native modes
quarkus.keycloak.devservices.realm-path=quarkus-realm.json

So IMHO all is clear here.

Dev mode section say accessing the /api/admin or /api/users/me but it not clear where or how. It can be tested in dev-ui login and test the different paths there or it can be tested by curl. For me first thing was put it in browser and try it. But we need token to access with specific user. This is mentioned in testing section.

IMHO it is all very precise here:
https://quarkus.io/version/main/guides/security-oidc-bearer-token-authentication-tutorial#keycloak-dev-mode

[jedla97]

@sberyozkin Thanks for addressing the problem or explain them!

For the keycloak I found out why it was not loaded for me. It was that quickstart have it in config directory so I put it there also but not add it as resources in pom.