Docs: “Using OpenID Connect (OIDC) and Keycloak to centralize authorization” guide issues

[gtroitsk]

Describe the bug

Found issues in the “Using OpenID Connect (OIDC) and Keycloak to centralize authorization” guide

Configuring the application + other application.properties examples

• Is it possible to not have spaces before numbered notes in application.properties files? Trailing spaces can cause wrong behaviour for some properties.

Starting and configuring the Keycloak server

• Docker run command example: trailing space after backslash, before the 1. note that breaks command execution

• Having an example using Docker CLI is good for community guide, but for future reference in RHBQ doc, we can add a note that it is possible to use Red Hat supported - Podman.

• Keycloak Administration Console access example is duplicated, let’s use the second variant - starts with “Accessing the Keycloak server”

• Docs says: “After importing the realm, you can see the resource permissions:”
  That took me some time to find the right tab. I think it will be nice to have a path mentioned. “From menu go to Clients and choose backend-service, next Authorization and Resources tabs”

• Data from screenshot is hard to read without opening it in new tab. I suggest to create new and smaller

Running the application in native mode

• Command for running Native binary should be the next:
  ./target/security-keycloak-authorization-quickstart-1.0.0-SNAPSHOT-runner

Checking permission scopes programmatically

• In the 3.note after the Java code example: “see the section Authorization using annotations of the Security Authorization guide”. Guide is now called “Authorization of web endpoints”

Dynamic tenant configuration resolution

• Please remove “config” from called builder method on the line this.enhancedTenantConfig = KeycloakPolicyEnforcerTenantConfig.builder(config)

• tenantConfig.tenantId.orElse(null) tenantId is deprecated since 3.18, please change to tenantId()

Common:
Keycloak Authorization Services are …(plural)

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 (keycloak,oidc), @sberyozkin (keycloak,oidc)

[gtroitsk]

CC @rolfedh

[sberyozkin]

@gtroitsk Thanks for the review of this doc,

Is it possible to not have spaces before numbered notes in application.properties files? Trailing spaces can cause wrong behaviour for some properties.

Do you mean, for a example, a space between backend-service and <2> in quarkus.oidc.client-id=backend-service <2> ? I'm not sure it will look good though, example, backend-service<2>. I see such spaces in many other, including non-security guides, I guess if trailing spaces cause issues for some properties then we'd have to deal with them in separate issues. I removed a couple of spaces in the Docker CLI command though

Having an example using Docker CLI is good for community guide, but for future reference in RHBQ doc, we can add a note that it is possible to use Red Hat supported - Podman.

I guess that would work best for the actual Red Hat version of this doc. Or may be we should have an enhancement request where, in various docs, we could use a macro similar to the one we use to show how to start Quarkus in devmode with Maven, Gradle, CLI, in this case we'd have a macro offering both podman and docker options...

Keycloak Administration Console access example is duplicated, let’s use the second variant - starts with “Accessing the Keycloak server”

I'm not sure what is duplicated, I see in one case it shows how to import the existing realm, and it is also referenced in another section related to customizing it, but the duplication is minimal

Data from screenshot is hard to read without opening it in new tab. I suggest to create new and smaller

I recall it was quite hard to capture the whole content, may be you'd like to experiment ? if we make it too small, it might be equally hard to see the details...

Keycloak Authorization Services are …(plural)

Can you clarify this point please ? They are plural in the Keycloak docs too.

I've started with the draft #46481

[sberyozkin]

Asciidoc needs a space between the text and the callout

[rolfedh]

Let me test something with the callouts. I see that some of the guides use comments with callouts, like this example on line 525 of datasource.adoc:

[source,java,indent=0]
----
public class MyProducer {
    @Inject
    @DataSource("pg")
    InjectableInstance<DataSource> pgDataSourceBean; // <1>

It doesn't fix the trailing space issue, but it does get rid of the callout appearing in the copy/paste code.

[rolfedh]

For commands and inputs, we can comment the callouts like this (// <1>) so they aren't included when users click the Copy button.

We can also delete the space preceding the comment bars like this...

    InjectableInstance<DataSource> pgDataSourceBean;// <1>

...if you're okay with the way it looks:

If make these changes, we should test to ensure it doesn't impact the code.

[rolfedh]

Having an example using Docker CLI is good for community guide, but for future reference in RHBQ doc, we can add a note that it is possible to use Red Hat supported - Podman.

In some of our downstream docs, we offer Podman command example following the Docker command. For example:

** For Podman:
+
[source,shell]
----
./mvnw package -Dnative -Dquarkus.package.type=native -Dquarkus.native.container-runtime=podman
----

We also mention it in the prerequisites. For example:

.Prerequisites

* Podman or Docker is installed.

Users can also enable Docker compatibility. See Managing Docker compatibility - Experimental feature.

[rolfedh]

Thank you so much for your review and feedback, @gtroitsk. This is critical for improving our customer experiences.
Thanks @sberyozkin, for starting a draft. Please let me know if I can help in any way.

[gtroitsk]

@sberyozkin and @rolfedh thank you both.

1. On the second thought, removing the space preceding the comment doesn't look good, instead we need to fix properties parsing.
2. Comment about Podman command was related to downstream docs, no fix is needed for upsteam. We can replace docker with podman for RHBQ docs in the next release.
3. The Keycloak Administration Console example looks okay now; it was duplicated before.
4. Screenshot of backend-service resources — I tried to minimalize it. You can see how it looks below."

5. Keycloak Authorization Services... I meant that 'services' word is plural, so 'are' must be used in sentences, but it depends how we look at it.

[sberyozkin]

Thanks @rolfedh, @gtroitsk.

@gtroitsk, I update the image, thanks, and also updates a few sections where Keycloak Authorization Services is enabled occurs with Keycloak Authorization Services feature is enabled...

As far as callouts are concerned, I believe the concern was about the application.properties or shell fragments, where extra // would not work. I'm not sure what should be done in the PR about it.