Add a quarkus-oidc-client-registration extension

bom/application/pom.xml

@@ -921,6 +921,16 @@
                 <artifactId>quarkus-rest-client-oidc-filter-deployment</artifactId>
                 <version>${project.version}</version>
             </dependency>
+            <dependency>
+                <groupId>io.quarkus</groupId>
+                <artifactId>quarkus-oidc-client-registration</artifactId>
+                <version>${project.version}</version>
+            </dependency>
+            <dependency>
+                <groupId>io.quarkus</groupId>
+                <artifactId>quarkus-oidc-client-registration-deployment</artifactId>
+                <version>${project.version}</version>
+            </dependency>
             <dependency>
                 <groupId>io.quarkus</groupId>
                 <artifactId>quarkus-oidc-client-graphql</artifactId>

core/deployment/src/main/java/io/quarkus/deployment/Feature.java

@@ -73,6 +73,7 @@ public enum Feature {
     OBSERVABILITY,
     OIDC,
     OIDC_CLIENT,
+    OIDC_CLIENT_REGISTRATION,
     RESTEASY_CLIENT_OIDC_FILTER,
     REST_CLIENT_OIDC_FILTER,
     OIDC_CLIENT_GRAPHQL_CLIENT_INTEGRATION,

devtools/bom-descriptor-json/pom.xml

@@ -1721,6 +1721,19 @@
                         </exclusion>
                     </exclusions>
                 </dependency>
+                <dependency>
+                    <groupId>io.quarkus</groupId>
+                    <artifactId>quarkus-oidc-client-registration</artifactId>
+                    <version>${project.version}</version>
+                    <type>pom</type>
+                    <scope>test</scope>
+                    <exclusions>
+                        <exclusion>
+                            <groupId>*</groupId>
+                            <artifactId>*</artifactId>
+                        </exclusion>
+                    </exclusions>
+                </dependency>
                 <dependency>
                     <groupId>io.quarkus</groupId>
                     <artifactId>quarkus-oidc-common</artifactId>

docs/pom.xml

@@ -1733,6 +1733,19 @@
                 </exclusion>
             </exclusions>
         </dependency>
+        <dependency>
+            <groupId>io.quarkus</groupId>
+            <artifactId>quarkus-oidc-client-registration-deployment</artifactId>
+            <version>${project.version}</version>
+            <type>pom</type>
+            <scope>test</scope>
+            <exclusions>
+                <exclusion>
+                    <groupId>*</groupId>
+                    <artifactId>*</artifactId>
+                </exclusion>
+            </exclusions>
+        </dependency>
         <dependency>
             <groupId>io.quarkus</groupId>
             <artifactId>quarkus-oidc-common-deployment</artifactId>

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

@@ -0,0 +1,279 @@
+////
+This guide is maintained in the main Quarkus repository
+and pull requests should be submitted there:
+https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
+////
+= OpenID Connect (OIDC) and OAuth2 dynamic client registration
+include::_attributes.adoc[]
+:diataxis-type: reference
+:categories: security
+:topics: security,oidc,client
+:extensions: io.quarkus:quarkus-oidc-client-registration
+
+Typically, you have to register an OIDC client (application) manually in your OIDC provider's dashboard.
+During this process, you specify the human readable application name, allowed redirect and post logout URLs, and other properties.
+After the registration has been completed, you copy the generated client id and secret to your Quarkus OIDC application properties.
+
+OpenID Connect and OAuth2 dynamic client registration allows you to register OIDC clients dynamically, and manage individual client registrations.
+You can read more about it in the https://openid.net/specs/openid-connect-registration-1_0.html[OIDC client registration] and https://datatracker.ietf.org/doc/html/rfc7592[OAuth2 Dynamic Client Registration Management Protocol] specification documents.
+
+You can use Quarkus extension for OpenID Connect dynamic client registration and management.
+
+This includes the following:
+
+ - Using `quarkus-oidc-client-registration` to register one or more clients using OIDC client registration configurations, either on start-up or on demand, and read, update and delete metadata of the registered clients. xref:security-openid-connect-multitenancy#tenant-config-resolver[OIDC TenantConfigResolver] can be used to create OIDC tenant configurations using the metadata of the registered clients.
+
+== Oidc Client Registration
+
+Add the following dependency:
+
+[source,xml]
+----
+<dependency>
+    <groupId>io.quarkus</groupId>
+    <artifactId>quarkus-oidc-client-registration</artifactId>
+</dependency>
+----
+
+The `quarkus-oidc-client-registration` extension allows register one or more clients using OIDC client registration configurations, either on start-up or on demand, and read, update and delete metadata of the registered clients.
+
+You can register and manage client registrations from the custom xref:security-openid-connect-multitenancy#tenant-config-resolver[OIDC TenantConfigResolver].
+Alternatively, you can register clients without even using OIDC. For example, it can be a command line tool which registers clients and passes metadata of the registered clients to Quarkus services which require them.
+
+
+=== Register clients on start-up
+
+You start with declaring one or more OIDC client registration configurations, for example:
+
+[source,properties]
+----
+# Default OIDC client registration which auto-discovers a standard client registration endpoint.
+# It does not require an initial registration token.
+
+quarkus.oidc-client-registration.auth-server-url=${quarkus.oidc.auth-server-url}
+quarkus.oidc-client-registration.metadata.client-name=Default Client
+quarkus.oidc-client-registration.metadata.redirect-uri=http://localhost:8081/protected
+
+# Named OIDC client registration which configures a registration endpoint path: 
+# It require an initial registration token for a client registration to succeed.
+
+quarkus.oidc-client-registration.tenant-client.registration-path=${quarkus.oidc.auth-server-url}/clients-registrations/openid-connect
+quarkus.oidc-client-registration.tenant-client.metadata.client-name=Tenant Client
+quarkus.oidc-client-registration.tenant-client.metadata.redirect-uri=http://localhost:8081/protected/tenant
+quarkus.oidc-client-registration.initial-token=${initial-registration-token}
+----
+
+The above configuration will lead to two new client registrations created in your OIDC provider.
+
+You or may not need to acquire an initial registration access token. If you don't, then you will have to enable one or more client registration policies in your OIDC provider's dashboard. For example, see https://www.keycloak.org/docs/latest/securing_apps/#_client_registration_policies[Keycloak client registration policies].   
+
+The next step is to inject either `quarkus.oidc.client.registration.OidcClientRegistration` if only a single default client registration is done, or `quarkus.oidc.client.registration.OidcClientRegistrations` if more than one registration is configured, and use metadata of these registered clients.
+
+For example:
+
+[source,java]
+----
+package io.quarkus.it.keycloak;
+
+import java.net.URI;
+import java.util.List;
+import java.util.Optional;
+
+import jakarta.enterprise.event.Observes;
+import jakarta.inject.Inject;
+import jakarta.inject.Singleton;
+import jakarta.json.Json;
+
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+
+import io.quarkus.oidc.OidcRequestContext;
+import io.quarkus.oidc.OidcTenantConfig;
+import io.quarkus.oidc.OidcTenantConfig.ApplicationType;
+import io.quarkus.oidc.TenantConfigResolver;
+import io.quarkus.oidc.client.registration.ClientMetadata;
+import io.quarkus.oidc.client.registration.OidcClientRegistration;
+import io.quarkus.oidc.client.registration.OidcClientRegistrationConfig;
+import io.quarkus.oidc.client.registration.OidcClientRegistrations;
+import io.quarkus.oidc.client.registration.RegisteredClient;
+import io.quarkus.oidc.common.runtime.OidcConstants;
+import io.quarkus.runtime.ShutdownEvent;
+import io.smallrye.mutiny.Uni;
+import io.vertx.ext.web.RoutingContext;
+
+@Singleton
+public class CustomTenantConfigResolver implements TenantConfigResolver {
+
+    @Inject
+    OidcClientRegistration clientReg;
+
+    @Inject
+    OidcClientRegistrations clientRegs;
+
+    @Override
+    public Uni<OidcTenantConfig> resolve(RoutingContext routingContext,
+            OidcRequestContext<OidcTenantConfig> requestContext) {
+        if (routingContext.request().path().endsWith("/protected")) {
+            return Uni.createFrom().item(createTenantConfig("registered-client", clientReg.registeredClient()));
+        } else if (routingContext.request().path().endsWith("/protected/tenant")) {
+            return Uni.createFrom().item(createTenantConfig("registered-client-tenant",
+                clientRegs.getClientRegistration("tenant-client").registeredClient()));
+        }
+        return null;
+    }
+
+    private OidcTenantConfig createTenantConfig(String tenantId, RegisteredClient client) {
+        ClientMetadata metadata = client.getMetadata();
+
+        OidcTenantConfig oidcConfig = new OidcTenantConfig();
+        oidcConfig.setTenantId(tenantId);
+        oidcConfig.setAuthServerUrl(authServerUrl);
+        oidcConfig.setApplicationType(ApplicationType.WEB_APP);
+        oidcConfig.setClientName(metadata.getClientName());
+        oidcConfig.setClientId(metadata.getClientId());
+        oidcConfig.getCredentials().setSecret(metadata.getClientSecret());
+        String redirectUri = metadata.getRedirectUris().get(0);
+        oidcConfig.getAuthentication().setRedirectPath(URI.create(redirectUri).getPath());
+        return oidcConfig;
+    }
+}
+----
+
+=== Register clients on demand
+
+You can register new clients on demand. 
+You can add new clients to the existing, already configured `OidcClientConfiguration` or to a newly created `OidcClientConfiguration`.
+
+Configure one or more OIDC client registrations:
+
+[source,properties]
+----
+quarkus.oidc-client-registration.auth-server-url=${quarkus.oidc.auth-server-url}
+---
+
+The above configuration is sufficient for registering new clients using this configuration. For example:
+
+[source,java]
+----
+package io.quarkus.it.keycloak;
+
+import java.net.URI;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+
+import jakarta.enterprise.event.Observes;
+import jakarta.inject.Inject;
+import jakarta.inject.Singleton;
+import jakarta.json.Json;
+
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+
+import io.quarkus.oidc.OidcRequestContext;
+import io.quarkus.oidc.OidcTenantConfig;
+import io.quarkus.oidc.OidcTenantConfig.ApplicationType;
+import io.quarkus.oidc.TenantConfigResolver;
+import io.quarkus.oidc.client.registration.ClientMetadata;
+import io.quarkus.oidc.client.registration.OidcClientRegistration;
+import io.quarkus.oidc.client.registration.OidcClientRegistrations;
+import io.quarkus.oidc.client.registration.OidcClientRegistrationConfig;
+import io.quarkus.oidc.common.runtime.OidcConstants;
+import io.quarkus.runtime.StartupEvent;
+import io.smallrye.mutiny.Uni;
+import io.vertx.ext.web.RoutingContext;
+
+@Singleton
+public class CustomTenantConfigResolver implements TenantConfigResolver {
+
+    @Inject
+    OidcClientRegistration clientReg;
+
+    @Inject
+    OidcClientRegistrations clientRegs;
+
+    @Inject
+    @ConfigProperty(name = "quarkus.oidc.auth-server-url")
+    String authServerUrl;
+
+    volatile Map<String, RegisteredClient> regClientsMulti;
+
+    void onStartup(@Observes StartupEvent event) {
+        // Two custom OIDC client registrations registered right now
+        ClientMetadata clientMetadataMulti1 = createMetadata("http://localhost:8081/protected/multi1", "Multi1 Client");
+        ClientMetadata clientMetadataMulti2 = createMetadata("http://localhost:8081/protected/multi2", "Multi2 Client");
+
+        Map<String, RegisteredClient> regClientsMulti = clientReg.registerClients(List.of(clientMetadataMulti1, clientMetadataMulti2))
+                .collect().asMap(r -> URI.create(r.metadata().getRedirectUris().get(0)).getPath(), r -> r)
+                .await().indefinitely();
+    }
+
+
+    @Override
+    public Uni<OidcTenantConfig> resolve(RoutingContext routingContext,
+            OidcRequestContext<OidcTenantConfig> requestContext) {
+        if (routingContext.request().path().endsWith("/protected/new-oidc-client-reg")) {
+            // New client registration done dynamically at the request time
+
+            OidcClientRegistrationConfig clientRegConfig = new OidcClientRegistrationConfig();
+            clientRegConfig.auth-server-url = Optional.of(authServerUrl);
+            clientRegConfig.metadata.redirectUri = Optional.of("http://localhost:8081/protected/new-oidc-client-reg");
+            clientRegConfig.metadata.clientName = Optional.of("Dynamic Client");
+
+            return clientRegs.newClientRegistration(clientRegConfig)
+                    .onItem().transform(reg -> 
+                    createTenantConfig("registered-client-dynamically", reg.registeredClient());
+        } if (routingContext.request().path().endsWith("/protected/oidc-client-reg-existing-config")) {
+            // New client registration done dynamically at the request time using the configured client registration
+
+            ClientMetadata metadata = createMetadata("http://localhost:8081/protected/dynamic-tenant",
+                    "Dynamic Tenant Client");
+
+            return clientReg.registerClient(metadata).onItem().transform(r -> 
+                  createTenantConfig("registered-client-dynamically", r));
+
+        } else if (routingContext.request().path().endsWith("/protected/multi1")) {
+            return Uni.createFrom().item(createTenantConfig("registered-client-multi1",
+                    regClientsMulti.get("/protected/multi1").metadata()));
+        } else if (routingContext.request().path().endsWith("/protected/multi2")) {
+            return Uni.createFrom().item(createTenantConfig("registered-client-multi2",
+                    regClientsMulti.get("/protected/multi2").metadata()));
+        }
+
+        return null;
+    }
+
+    private OidcTenantConfig createTenantConfig(String tenantId, ClientMetadata metadata) {
+        OidcTenantConfig oidcConfig = new OidcTenantConfig();
+        oidcConfig.setTenantId(tenantId);
+        oidcConfig.setAuthServerUrl(authServerUrl);
+        oidcConfig.setApplicationType(ApplicationType.WEB_APP);
+        oidcConfig.setClientName(metadata.getClientName());
+        oidcConfig.setClientId(metadata.getClientId());
+        oidcConfig.getCredentials().setSecret(metadata.getClientSecret());
+        String redirectUri = metadata.getRedirectUris().get(0);
+        oidcConfig.getAuthentication().setRedirectPath(URI.create(redirectUri).getPath());
+        return oidcConfig;
+    }
+
+    protected static ClientMetadata createMetadata(String redirectUri, String clientName) {
+        return new ClientMetadata(Json.createObjectBuilder()
+                .add(OidcConstants.CLIENT_METADATA_REDIRECT_URIS, Json.createArrayBuilder().add(redirectUri))
+                .add(OidcConstants.CLIENT_METADATA_CLIENT_NAME, clientName)
+                .build());
+    }
+}
+
+----
+
+[[configuration-reference]]
+== Configuration reference
+
+include::{generated-dir}/config/quarkus-oidc-client-registration.adoc[opts=optional, leveloffset=+1]
+
+== References
+
+* https://openid.net/specs/openid-connect-registration-1_0.html[OIDC client registration]
+* https://datatracker.ietf.org/doc/html/rfc7592[OAuth2 Dynamic Client Registration Management Protocol]
+* https://www.keycloak.org/docs/latest/securing_apps/#_client_registration[Keycloak Dynamic Client Registration Service]
+* xref:security-oidc-bearer-token-authentication.adoc[OIDC Bearer token authentication]
+* xref:security-oidc-code-flow-authentication.adoc[OIDC code flow mechanism for protecting web applications]
+* xref:security-overview.adoc[Quarkus Security overview]