Merge pull request #17210 from sberyozkin/oidc_debug_and_kc_frontend_url

Update OIDC/JWT docs how to check the errors in the logs and add info about Keycloak Frontend Url

docs/src/main/asciidoc/security-jwt.adoc

@@ -765,7 +765,13 @@ See <<generate-jwt-tokens, Generate JWT tokens with SmallRye JWT>> and learn how
 
 == How to check the errors in the logs ==
 
-Set `quarkus.log.category."io.quarkus.smallrye.jwt.runtime.auth.MpJwtValidator".level=TRACE` and `quarkus.log.category."io.quarkus.smallrye.jwt.runtime.auth.MpJwtValidator".min-level=TRACE` to see more details about the token verification or decryption errors.
+Please enable `io.quarkus.smallrye.jwt.runtime.auth.MpJwtValidator` `TRACE` level logging to see more details about the token verification or decryption errors:
+
+[source, properties]
+----
+quarkus.log.category."io.quarkus.smallrye.jwt.runtime.auth.MpJwtValidator".level=TRACE
+quarkus.log.category."io.quarkus.smallrye.jwt.runtime.auth.MpJwtValidator".min-level=TRACE
+----
 
 == Proactive Authentication
 

docs/src/main/asciidoc/security-openid-connect-client.adoc

@@ -515,6 +515,16 @@ and finally write the test code. Given the Wiremock-based resource above, the fi
 
 If you work with Keycloak then you can use the same approach as described in the link:security-openid-connect#integration-testing-keycloak[OpenId Connect Bearer Token Integration testing] `Keycloak` section.
 
+== How to check the errors in the logs ==
+
+Please enable `io.quarkus.oidc.client.runtime.OidcClientImpl` `TRACE` level logging to see more details about the token acquisition and refresh errors:
+
+[source, properties]
+----
+quarkus.log.category."io.quarkus.oidc.client.runtime.OidcClientImpl".level=TRACE
+quarkus.log.category."io.quarkus.oidc.client.runtime.OidcClientImpl".min-level=TRACE
+----
+
 == Token endpoint configuration
 
 By default the token endpoint address is discovered by adding a `/.well-known/openid-configuration` path to the configured `quarkus.oidc-client.auth-server-url`.

docs/src/main/asciidoc/security-openid-connect-web-authentication.adoc

@@ -741,6 +741,24 @@ Default realm name is `quarkus` and client id - `quarkus-web-app` - set `keycloa
 
 Please see link:security-openid-connect#integration-testing-security-annotation[Use TestingSecurity with injected JsonWebToken] section for more information about using `@TestSecurity` and `@OidcSecurity` annotations for testing the `web-app` application endpoint code which depends on the injected ID and access `JsonWebToken` as well as `UserInfo` and `OidcConfigurationMetadata`.
 
+== How to check the errors in the logs ==
+
+Please enable `io.quarkus.oidc.runtime.OidcProvider` `TRACE` level logging to see more details about the token verification errors:
+
+[source, properties]
+----
+quarkus.log.category."io.quarkus.oidc.runtime.OidcProvider".level=TRACE
+quarkus.log.category."io.quarkus.oidc.runtime.OidcProvider".min-level=TRACE
+----
+
+== External and Internal Access to OpenId Connect Provider
+
+Note that the OpenId Connect Provider externally accessible authorization, logout and other endpoints may have different HTTP(S) URLs compared to the URLs auto-discovered or configured relative to `quarkus.oidc.auth-server-url` internal URL.
+In such cases an issuer verification failure may be reported by the endpoint and redirects to the externally accessible Connect Provider endpoints may fail.
+
+In such cases, if you work with Keycloak then please start it with a `KEYCLOAK_FRONTEND_URL` system property set to the externally accessible base URL.
+If you work with other Openid Connect providers then please check your provider's documentation.
+
 == Configuration Reference
 
 include::{generated-dir}/config/quarkus-oidc.adoc[opts=optional]

docs/src/main/asciidoc/security-openid-connect.adoc

@@ -769,6 +769,22 @@ Note that `@TestSecurity` annotation must always be used and its `user` property
 `@OidcSecurity` annotation is optional and can be used to set the additional token claims, as well as `UserInfo` and `OidcConfigurationMetadata` properties. 
 Additionally, if `quarkus.oidc.token.issuer` property is configured then it will be used as an `OidcConfigurationMetadata` `issuer` property value.
 
+== How to check the errors in the logs ==
+
+Please enable `io.quarkus.oidc.runtime.OidcProvider` `TRACE` level logging to see more details about the token verification errors:
+
+[source, properties]
+----
+quarkus.log.category."io.quarkus.oidc.runtime.OidcProvider".level=TRACE
+quarkus.log.category."io.quarkus.oidc.runtime.OidcProvider".min-level=TRACE
+----
+
+== External and Internal Access to OpenId Connect Provider
+
+Note that the OpenId Connect Provider externally accessible token and other endpoints may have different HTTP(S) URLs compared to the URLs auto-discovered or configured relative to `quarkus.oidc.auth-server-url` internal URL. For example, if your SPA acquires a token from an external token endpoint address and sends it to Quarkus as a Bearer token then an issuer verification failure may be reported by the endpoint.
+
+In such cases, if you work with Keycloak then please start it with a `KEYCLOAK_FRONTEND_URL` system property set to the externally accessible base URL.
+If you work with other Openid Connect providers then please check your provider's documentation.
 
 == References