Skip to content

Commit

Permalink
Sync web site with Quarkus documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
quarkusbot committed Dec 19, 2024
1 parent 7543f26 commit f987413
Show file tree
Hide file tree
Showing 8 changed files with 69 additions and 17 deletions.
2 changes: 1 addition & 1 deletion _generated-doc/latest/config/quarkus-all-config.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -9810,7 +9810,7 @@ a|icon:lock[title=Fixed at build time] [[quarkus-vertx-http_quarkus-http-auth-in
--
Require that all registered HTTP authentication mechanisms must complete the authentication.

Typically, this property has to be true when the credentials are carried over mTLS, when both mTLS and another authentication, for example, OIDC bearer token authentication, must succeed. In such cases, `SecurityIdentity` created by the first mechanism, mTLS, can be injected, identities created by other mechanisms will be available on `SecurityIdentity`. The identities can be retrieved using utility method as in the example below:
Typically, this property has to be true when the credentials are carried over mTLS, when both mTLS and another authentication, for example, OIDC bearer token authentication, must succeed. In such cases, `SecurityIdentity` created by the first mechanism, mTLS, can be injected, identities created by other mechanisms will be available on `SecurityIdentity`. The mTLS mechanism is always the first mechanism, because its priority is elevated when inclusive authentication is enabled. The identities can be retrieved using utility method as in the example below:

```
`io.quarkus.vertx.http.runtime.security.HttpSecurityUtils.getSecurityIdentities(securityIdentity)`
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,7 @@ a|icon:lock[title=Fixed at build time] [[quarkus-vertx-http_quarkus-http-auth-in
--
Require that all registered HTTP authentication mechanisms must complete the authentication.

Typically, this property has to be true when the credentials are carried over mTLS, when both mTLS and another authentication, for example, OIDC bearer token authentication, must succeed. In such cases, `SecurityIdentity` created by the first mechanism, mTLS, can be injected, identities created by other mechanisms will be available on `SecurityIdentity`. The identities can be retrieved using utility method as in the example below:
Typically, this property has to be true when the credentials are carried over mTLS, when both mTLS and another authentication, for example, OIDC bearer token authentication, must succeed. In such cases, `SecurityIdentity` created by the first mechanism, mTLS, can be injected, identities created by other mechanisms will be available on `SecurityIdentity`. The mTLS mechanism is always the first mechanism, because its priority is elevated when inclusive authentication is enabled. The identities can be retrieved using utility method as in the example below:

```
`io.quarkus.vertx.http.runtime.security.HttpSecurityUtils.getSecurityIdentities(securityIdentity)`
Expand Down
2 changes: 1 addition & 1 deletion _guides/_attributes.adoc
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
// Common attributes.
// --> No blank lines (it ends the document header)
:project-name: Quarkus
:quarkus-version: 3.17.4
:quarkus-version: 3.17.5
:quarkus-platform-groupid: io.quarkus.platform
// .
:maven-version: 3.9.9
Expand Down
2 changes: 1 addition & 1 deletion _guides/centralized-log-management.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -250,7 +250,7 @@ For this you can use the same `docker-compose.yml` file as above but with a diff
input {
tcp {
port => 4560
coded => json
codec => json
}
}
Expand Down
6 changes: 5 additions & 1 deletion _guides/security-authentication-mechanisms.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -602,7 +602,11 @@ quarkus.http.auth.inclusive=true
If the authentication is inclusive then `SecurityIdentity` created by the first authentication mechanism can be
injected into the application code.
For example, if both <<mutual-tls>> and basic authentication mechanism authentications are required,
the <<mutual-tls>> authentication mechanism will create `SecurityIdentity` first.
the <<mutual-tls>> mechanism will create `SecurityIdentity` first.

NOTE: The <<mutual-tls>> mechanism has the highest priority when inclusive authentication is enabled, to ensure
that an injected `SecurityIdentity` always represents <<mutual-tls>> and can be used to get access to `SecurityIdentity`
identities provided by other authentication mechanisms.

Additional `SecurityIdentity` instances can be accessed as a `quarkus.security.identities` attribute on the first
`SecurityIdentity`, however, accessing these extra identities directly may not be necessary, for example,
Expand Down
43 changes: 43 additions & 0 deletions _guides/security-oidc-bearer-token-authentication.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -1345,6 +1345,49 @@ Authentication that requires a dynamic tenant will fail.
You can filter OIDC requests made by Quarkus to the OIDC provider by registering one or more `OidcRequestFilter` implementations, which can update or add new request headers, and log requests.
For more information, see xref:security-oidc-code-flow-authentication#code-flow-oidc-request-filters[OIDC request filters].

[[bearer-token-oidc-response-filters]]
=== OIDC response filters

You can filter responses from the OIDC providers by registering one or more `OidcResponseFilter` implementations, which can check the response status, headers and body in order to log them or perform other actions.

You can have a single filter intercepting all the OIDC responses, or use an `@OidcEndpoint` annotation to apply this filter to the specific endpoint responses only. For example:

[source,java]
----
package io.quarkus.it.keycloak;
import jakarta.enterprise.context.ApplicationScoped;
import io.quarkus.arc.Unremovable;
import io.quarkus.logging.Log;
import io.quarkus.oidc.common.OidcEndpoint;
import io.quarkus.oidc.common.OidcEndpoint.Type;
import io.quarkus.oidc.common.OidcResponseFilter;
import io.quarkus.oidc.common.runtime.OidcConstants;
import io.quarkus.oidc.runtime.OidcUtils;
@ApplicationScoped
@Unremovable
@OidcEndpoint(value = Type.DISCOVERY) <1>
public class DiscoveryEndpointResponseFilter implements OidcResponseFilter {
@Override
public void filter(OidcResponseContext rc) {
String contentType = rc.responseHeaders().get("Content-Type"); <2>
if (contentType.equals("application/json") {
String tenantId = rc.requestProperties().get(OidcUtils.TENANT_ID_ATTRIBUTE); <3>
String metadata = rc.responseBody().toString(); <4>
Log.debugf("Tenant %s OIDC metadata: %s", tenantId, metadata);
}
}
}
----
<1> Restrict this filter to requests targeting the OIDC discovery endpoint only.
<2> Check the response `Content-Type` header.
<3> Use `OidcRequestContextProperties` request properties to get the tenant id.
<4> Get the response data as String.

== References

* xref:security-oidc-configuration-properties-reference.adoc[OIDC configuration properties]
Expand Down
8 changes: 3 additions & 5 deletions _guides/security-oidc-code-flow-authentication.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -392,9 +392,8 @@ package io.quarkus.it.keycloak;
import jakarta.enterprise.context.ApplicationScoped;
import org.jboss.logging.Logger;
import io.quarkus.arc.Unremovable;
import io.quarkus.logging.Log;
import io.quarkus.oidc.common.OidcEndpoint;
import io.quarkus.oidc.common.OidcEndpoint.Type;
import io.quarkus.oidc.common.OidcResponseFilter;
Expand All @@ -405,16 +404,15 @@ import io.quarkus.oidc.runtime.OidcUtils;
@Unremovable
@OidcEndpoint(value = Type.TOKEN) <1>
public class TokenEndpointResponseFilter implements OidcResponseFilter {
private static final Logger LOG = Logger.getLogger(TokenResponseFilter.class);
@Override
public void filter(OidcResponseContext rc) {
String contentType = rc.responseHeaders().get("Content-Type"); <2>
if (contentType.equals("application/json")
&& OidcConstants.AUTHORIZATION_CODE.equals(rc.requestProperties().get(OidcConstants.GRANT_TYPE)) <3>
&& "code-flow-user-info-cached-in-idtoken".equals(rc.requestProperties().get(OidcUtils.TENANT_ID_ATTRIBUTE)) <3>
&& rc.responseBody().toJsonObject().containsKey("id_token")) { <4>
LOG.debug("Authorization code completed for tenant 'code-flow-user-info-cached-in-idtoken'");
Log.debug("Authorization code completed for tenant 'code-flow-user-info-cached-in-idtoken'");
}
}
}
Expand Down
21 changes: 14 additions & 7 deletions _guides/writing-native-applications-tips.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -197,7 +197,7 @@ public class MyReflectionConfiguration {
}
----

Note: By default the `@RegisterForReflection` annotation will also registered any potential nested classes for reflection. If you want to avoid this behavior, you can set the `ignoreNested` attribute to `true`.
Note: By default the `@RegisterForReflection` annotation will also register any potential nested classes for reflection. If you want to avoid this behavior, you can set the `ignoreNested` attribute to `true`.

==== Using a configuration file

Expand Down Expand Up @@ -320,6 +320,7 @@ and in the case of using the Maven configuration instead of `application.propert
----
====

[[managing-proxy-classes-app]]
=== Managing Proxy Classes

While writing native application you'll need to define proxy classes at image build time by specifying the list of interfaces that they implement.
Expand All @@ -331,9 +332,10 @@ In such a situation, the error you might encounter is:
com.oracle.svm.core.jdk.UnsupportedFeatureError: Proxy class defined by interfaces [interface org.apache.http.conn.HttpClientConnectionManager, interface org.apache.http.pool.ConnPoolControl, interface com.amazonaws.http.conn.Wrapped] not found. Generating proxy classes at runtime is not supported. Proxy classes need to be defined at image build time by specifying the list of interfaces that they implement. To define proxy classes use -H:DynamicProxyConfigurationFiles=<comma-separated-config-files> and -H:DynamicProxyConfigurationResources=<comma-separated-config-resources> options.
----

Solving this issue requires creating a `proxy-config.json` file under the `src/main/resources/META-INF/native-image/<group-id>/<artifact-id>` folder.
This way the configuration will be automatically parsed by the native build, without additional configuration.
For more information about the format of this file, see the link:https://www.graalvm.org/{graalvm-docs-version}/reference-manual/native-image/metadata/#dynamic-proxy-metadata-in-json[Dynamic Proxy Metadata in JSON] documentation.
To solve the issue you can create a `proxy-config.json` file under the `src/main/resources/META-INF/native-image/<group-id>/<artifact-id>` folder.
For more information about the format of the `proxy-config.json`, see the https://www.graalvm.org/{graalvm-docs-version}/reference-manual/native-image/metadata/#dynamic-proxy-metadata-in-json[Dynamic Proxy Metadata in JSON] documentation.

Alternatively, you can create a quarkus extension and register the proxy classes as described in <<managing-proxy-classes-extension>>.

[[modularity-benefits]]
=== Modularity Benefits
Expand Down Expand Up @@ -633,9 +635,10 @@ Using such a construct means that a `--initialize-at-run-time` option will autom
For more information about the `--initialize-at-run-time` option, see the link:https://www.graalvm.org/{graalvm-docs-version}/reference-manual/native-image/optimizations-and-performance/ClassInitialization/[GraalVM Class Initialization in Native Image] guide.
====

[[managing-proxy-classes-extension]]
=== Managing Proxy Classes

Very similarly, Quarkus allows extensions authors to register a `NativeImageProxyDefinitionBuildItem`. An example of doing so is:
Similarly, Quarkus allows extensions authors to register a `NativeImageProxyDefinitionBuildItem`. An example of doing so is:

[source,java]
----
Expand All @@ -650,11 +653,15 @@ public class S3Processor {
}
----

Using such a construct means that a `-H:DynamicProxyConfigurationResources` option will automatically be added to the `native-image` command line.
This will allow Quarkus to generate the necessary configuration for handling the proxy class.

Alternatively, you may create a `proxy-config.json` as described in <<managing-proxy-classes-app>>.

[NOTE]
====
For more information about Proxy Classes, see the link:https://www.graalvm.org/{graalvm-docs-version}/reference-manual/native-image/guides/configure-dynamic-proxies/[GraalVM Configure Dynamic Proxies Manually] guide.
In both cases the configuration will be automatically parsed by the native build, without additional configuration.
For more information about using Proxy Classes in native executables, see https://www.graalvm.org/jdk21/reference-manual/native-image/dynamic-features/DynamicProxy/[Dynamic Proxy in Native Image] and https://www.graalvm.org/{graalvm-docs-version}/reference-manual/native-image/guides/configure-dynamic-proxies/[GraalVM Configure Dynamic Proxies Manually].
====

=== Logging with Native Image
Expand Down

0 comments on commit f987413

Please sign in to comment.