mirror of
https://github.com/jlengrand/quarkus.git
synced 2026-03-10 08:41:22 +00:00
Merge pull request #7260 from pedroigor/issue-6571
[fixes #6571] - Document OIDC Multi-Tenancy feature
This commit is contained in:
sberyozkin
@@ -49,6 +49,7 @@ include::quarkus-intro.adoc[tag=intro]
|
||||
* link:cdi-reference.html[Contexts and Dependency Injection] _(advanced)_
|
||||
* link:security-openid-connect.html[Using OpenID Connect Adapter to Protect JAX-RS Applications]
|
||||
* link:security-openid-connect-web-authentication.html[Protecting Web Applications Using OpenID Connect]
|
||||
* link:security-openid-connect-multitenancy.html[Supporting Multi-Tenancy in OpenID Connect Applications]
|
||||
* link:security-keycloak-authorization.html[Keycloak Authorization]
|
||||
* link:kogito.html[Using Kogito (business automation with processes and rules)]
|
||||
* link:security-oauth2.html[Using OAuth2 RBAC]
|
||||
|
||||
332
docs/src/main/asciidoc/security-openid-connect-multitenancy.adoc
Normal file
332
docs/src/main/asciidoc/security-openid-connect-multitenancy.adoc
Normal file
@@ -0,0 +1,332 @@
|
||||
////
|
||||
This guide is maintained in the main Quarkus repository
|
||||
and pull requests should be submitted there:
|
||||
https://github.com/quarkusio/quarkus/tree/master/docs/src/main/asciidoc
|
||||
////
|
||||
= Quarkus - Supporting Multi-Tenancy in OpenID Connect Applications
|
||||
|
||||
include::./attributes.adoc[]
|
||||
:extension-status: preview
|
||||
|
||||
This guide demonstrates how your OpenID Connect application can support multi-tenancy so that you can serve multiple tenants from a single application. Tenants can be distinct realms or security domains within the same OpenID Provider or even distinct OpenID Providers.
|
||||
|
||||
When serving multiple customers from the same application (e.g.: SaaS), each customer is a tenant. By enabling multi-tenancy support to your applications you are allowed to also support distinct authentication policies for each tenant even though if that means authenticating against different OpenID Providers, such as Keycloak and Google.
|
||||
|
||||
include::./status-include.adoc[]
|
||||
|
||||
== Prerequisites
|
||||
|
||||
To complete this guide, you need:
|
||||
|
||||
* less than 15 minutes
|
||||
* an IDE
|
||||
* JDK 1.8+ installed with `JAVA_HOME` configured appropriately
|
||||
* Apache Maven 3.5.3+
|
||||
* https://stedolan.github.io/jq/[jq tool]
|
||||
* Docker
|
||||
|
||||
== Architecture
|
||||
|
||||
In this example, we build a very simple application which offers a single land page:
|
||||
|
||||
* `/{tenant}`
|
||||
|
||||
The land page is served by a JAX-RS Resource and shows information obtained from the OpenID Provider about the authenticated user and the current tenant.
|
||||
|
||||
== Solution
|
||||
|
||||
We recommend that you follow the instructions in the next sections and create the application step by step.
|
||||
However, you can go right to the completed example.
|
||||
|
||||
Clone the Git repository: `git clone {quickstarts-clone-url}`, or download an {quickstarts-archive-url}[archive].
|
||||
|
||||
The solution is located in the `security-openid-connect-multi-tenancy` {quickstarts-tree-url}/security-openid-connect-multi-tenancy[directory].
|
||||
|
||||
== Creating the Maven Project
|
||||
|
||||
First, we need a new project. Create a new project with the following command:
|
||||
|
||||
[source, subs=attributes+]
|
||||
----
|
||||
mvn io.quarkus:quarkus-maven-plugin:{quarkus-version}:create \
|
||||
-DprojectGroupId=org.acme \
|
||||
-DprojectArtifactId=security-openid-connect-multi-tenancy \
|
||||
-Dextensions="oidc, resteasy-jsonb"
|
||||
cd security-openid-connect-multi-tenancy
|
||||
----
|
||||
|
||||
== Writing the application
|
||||
|
||||
Let's start by implementing the `/{tenant}` endpoint. As you can see from the source code below it is just a regular JAX-RS resource:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
package org.acme.quickstart.oidc;
|
||||
|
||||
import javax.inject.Inject;
|
||||
import javax.ws.rs.GET;
|
||||
import javax.ws.rs.Path;
|
||||
|
||||
import org.eclipse.microprofile.jwt.JsonWebToken;
|
||||
|
||||
import io.quarkus.oidc.IdToken;
|
||||
|
||||
@Path("/{tenant}")
|
||||
public class HomeResource {
|
||||
|
||||
/**
|
||||
* Injection point for the ID Token issued by the OpenID Connect Provider
|
||||
*/
|
||||
@Inject
|
||||
@IdToken
|
||||
JsonWebToken idToken;
|
||||
|
||||
/**
|
||||
* Returns the tokens available to the application. This endpoint exists only for demonstration purposes, you should not
|
||||
* expose these tokens in a real application.
|
||||
*
|
||||
* @return the landing page HTML
|
||||
*/
|
||||
@GET
|
||||
public String getHome() {
|
||||
StringBuilder response = new StringBuilder().append("<html>").append("<body>");
|
||||
|
||||
response.append("<h2>Welcome, ").append(this.idToken.getClaim("email").toString()).append("</h2>\n");
|
||||
response.append("<h3>You are accessing the application within tenant <b>").append(idToken.getIssuer()).append(" boundaries</b></h3>");
|
||||
|
||||
return response.append("</body>").append("</html>").toString();
|
||||
}
|
||||
}
|
||||
|
||||
----
|
||||
|
||||
In order to resolve the tenant from incoming requests and map it to a specific `quarkus-oidc` configuration, you need to create an implementation for the `io.quarkus.oidc.TenantResolver` interface.
|
||||
|
||||
[source,java]
|
||||
----
|
||||
package org.acme.quickstart.oidc;
|
||||
|
||||
import javax.enterprise.context.ApplicationScoped;
|
||||
|
||||
import io.quarkus.oidc.TenantResolver;
|
||||
import io.vertx.ext.web.RoutingContext;
|
||||
|
||||
@ApplicationScoped
|
||||
public class CustomTenantResolver implements TenantResolver {
|
||||
|
||||
@Override
|
||||
public String resolve(RoutingContext context) {
|
||||
String path = context.request().path();
|
||||
String[] parts = path.split("/");
|
||||
|
||||
if (parts.length == 0) {
|
||||
// resolve to default tenant config
|
||||
return null;
|
||||
}
|
||||
|
||||
return parts[1];
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
From the implementation above, tenants are resolved from the request path so that in case no tenant could be inferred, `null` is returned to indicate that the default configuration should be used.
|
||||
|
||||
== Configuring the application
|
||||
|
||||
[source,properties]
|
||||
----
|
||||
# Default Tenant Configuration
|
||||
quarkus.oidc.auth-server-url=http://localhost:8180/auth/realms/quarkus
|
||||
quarkus.oidc.client-id=multi-tenant-client
|
||||
quarkus.oidc.application-type=web-app
|
||||
|
||||
# Tenant A Configuration
|
||||
quarkus.oidc.tenant-a.auth-server-url=http://localhost:8180/auth/realms/tenant-a
|
||||
quarkus.oidc.tenant-a.client-id=multi-tenant-client
|
||||
quarkus.oidc.tenant-a.application-type=web-app
|
||||
|
||||
# HTTP Security Configuration
|
||||
quarkus.http.auth.permission.authenticated.paths=/*
|
||||
quarkus.http.auth.permission.authenticated.policy=authenticated
|
||||
----
|
||||
|
||||
The first configuration is the configuration that should be used when the tenant can not be inferred from the request. This configuration is using a Keycloak instance to authenticate users.
|
||||
|
||||
The second configuration is the configuration that will be used when an incoming request is mapped to the tenant `tenant-a`.
|
||||
|
||||
Note that both configurations map to the same Keycloak server instance while using distinct `realms`.
|
||||
|
||||
You can define multiple tenants in your configuration file, just make sure they have a unique alias so that you can map them properly when resolving a tenant from your `TenantResolver` implementation.
|
||||
|
||||
=== Google OpenID Provider Configuration
|
||||
|
||||
In order to set-up the `tenant-a` configuration to use Google OpenID Provider, you need to create a project as described https://developers.google.com/identity/protocols/OpenIDConnect[here].
|
||||
|
||||
Once you create the project and have your project's `client_id` and `client_secret`, you can try to configure a tenant as follows:
|
||||
|
||||
[source, properties]
|
||||
---
|
||||
# Tenant configuration using Google OpenID Provider
|
||||
quarkus.oidc.tenant-b.auth-server-url=https://accounts.google.com
|
||||
quarkus.oidc.tenant-b.application-type=web-app
|
||||
quarkus.oidc.tenant-b.client-id={GOOGLE_CLIENT_ID}
|
||||
quarkus.oidc.tenant-b.credentials.secret={GOOGLE_CLIENT_SECRET}
|
||||
quarkus.oidc.tenant-b.token.issuer=https://accounts.google.com
|
||||
quarkus.oidc.tenant-b.authentication.scopes=email,profile,openid
|
||||
---
|
||||
|
||||
== Starting and Configuring the Keycloak Server
|
||||
|
||||
To start a Keycloak Server you can use Docker and just run the following command:
|
||||
|
||||
[source,bash,subs=attributes+]
|
||||
----
|
||||
docker run --name keycloak -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin -p 8180:8080 {keycloak-docker-image}
|
||||
----
|
||||
|
||||
You should be able to access your Keycloak Server at http://localhost:8180/auth[localhost:8180/auth].
|
||||
|
||||
Log in as the `admin` user to access the Keycloak Administration Console. Username should be `admin` and password `admin`.
|
||||
|
||||
Now, follow the steps below to import the realms for the two tenants:
|
||||
|
||||
* Import the {quickstarts-tree-url}/security-openid-connect-multi-tenancy/config/default-tenant-realm.json[default-tenant-realm.json] to create the default realm
|
||||
* Import the {quickstarts-tree-url}/security-openid-connect-multi-tenancy/config/tenant-a-realm.json[tenant-a-realm.json] to create the realm for the tenant `tenant-a`.
|
||||
|
||||
For more details, see the Keycloak documentation about how to https://www.keycloak.org/docs/latest/server_admin/index.html#_create-realm[create a new realm].
|
||||
|
||||
== Running and Using the Application
|
||||
|
||||
=== Running in Developer Mode
|
||||
|
||||
To run the microservice in dev mode, use `./mvnw clean compile quarkus:dev`.
|
||||
|
||||
=== Running in JVM Mode
|
||||
|
||||
When you're done playing with "dev-mode" you can run it as a standard Java application.
|
||||
|
||||
First compile it:
|
||||
|
||||
[source,bash]
|
||||
----
|
||||
./mvnw package
|
||||
----
|
||||
|
||||
Then run it:
|
||||
|
||||
[source,bash]
|
||||
----
|
||||
java -jar ./target/security-openid-connect-multi-tenancy-quickstart-runner.jar
|
||||
----
|
||||
|
||||
=== Running in Native Mode
|
||||
|
||||
This same demo can be compiled into native code: no modifications required.
|
||||
|
||||
This implies that you no longer need to install a JVM on your
|
||||
production environment, as the runtime technology is included in
|
||||
the produced binary, and optimized to run with minimal resource overhead.
|
||||
|
||||
Compilation will take a bit longer, so this step is disabled by default;
|
||||
let's build again by enabling the `native` profile:
|
||||
|
||||
[source,bash]
|
||||
----
|
||||
./mvnw package -Pnative
|
||||
----
|
||||
|
||||
After getting a cup of coffee, you'll be able to run this binary directly:
|
||||
|
||||
[source,bash]
|
||||
----
|
||||
./target/security-openid-connect-web-authentication-quickstart-runner
|
||||
----
|
||||
|
||||
== Testing the Application
|
||||
|
||||
To test the application, you should open your browser and access the following URL:
|
||||
|
||||
* http://localhost:8080/default[http://localhost:8080/default]
|
||||
|
||||
If everything is working as expected, you should be redirected to the Keycloak server to authenticate. Note that the requested path
|
||||
defines a `default` tenant which we don't have mapped in the configuration file. In this case, the default configuration will be used.
|
||||
|
||||
In order to authenticate to the application you should type the following credentials when at the Keycloak login page:
|
||||
|
||||
* Username: *alice*
|
||||
* Password: *alice*
|
||||
|
||||
After clicking the `Login` button you should be redirected back to the application.
|
||||
|
||||
If you try now to access the application at the following URL:
|
||||
|
||||
* http://localhost:8080/tenant-a[http://localhost:8080/tenant-a]
|
||||
|
||||
You should be redirected again to the login page at Keycloak. However, now you are going to authenticate using a different `realm`.
|
||||
|
||||
In both cases, if the user is successfully authenticated, the landing page will show the user's name and e-mail. Even though
|
||||
user `alice` exists in both tenants, for the application they are distinct users belonging to different realms/tenants.
|
||||
|
||||
== Programmatically Resolving Tenants Configuration
|
||||
|
||||
If you need a more dynamic configuration for the different tenants you want to support and don't want to end up with multiple
|
||||
entries in your configuration file, you can use the `io.quarkus.oidc.TenantConfigResolver`.
|
||||
|
||||
This interface allows you to dynamically create tenant configurations at runtime:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
package io.quarkus.it.keycloak;
|
||||
|
||||
import javax.enterprise.context.ApplicationScoped;
|
||||
|
||||
import io.quarkus.oidc.TenantConfigResolver;
|
||||
import io.quarkus.oidc.runtime.OidcTenantConfig;
|
||||
import io.vertx.ext.web.RoutingContext;
|
||||
|
||||
@ApplicationScoped
|
||||
public class CustomTenantConfigResolver implements TenantConfigResolver {
|
||||
|
||||
@Override
|
||||
public OidcTenantConfig resolve(RoutingContext context) {
|
||||
String path = context.request().path();
|
||||
String[] parts = path.split("/");
|
||||
|
||||
if (parts.length == 0) {
|
||||
// resolve to default tenant config
|
||||
return null;
|
||||
}
|
||||
|
||||
if ("tenant-c".equals(parts[1])) {
|
||||
OidcTenantConfig config = new OidcTenantConfig();
|
||||
|
||||
config.setTenantId("tenant-c");
|
||||
config.setAuthServerUrl("http://localhost:8180/auth/realms/tenant-c");
|
||||
config.setClientId("multi-tenant-client");
|
||||
OidcTenantConfig.Credentials credentials = new OidcTenantConfig.Credentials();
|
||||
|
||||
credentials.setSecret("my-secret");
|
||||
|
||||
config.setCredentials(credentials);
|
||||
|
||||
// any other setting support by the quarkus-oidc extension
|
||||
|
||||
return config;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
The `OidcTenantConfig` returned from this method is the same used to parse the `oidc` namespace configuration from the `application.properties`. You can populate it using any of the settings supported by the `quarkus-oidc` extension.
|
||||
|
||||
== Configuration Reference
|
||||
|
||||
include::{generated-dir}/config/quarkus-oidc.adoc[opts=optional]
|
||||
|
||||
== References
|
||||
|
||||
* https://www.keycloak.org/documentation.html[Keycloak Documentation]
|
||||
* https://openid.net/connect/[OpenID Connect]
|
||||
* https://tools.ietf.org/html/rfc7519[JSON Web Token]
|
||||
* https://developers.google.com/identity/protocols/OpenIDConnect[Google OpenID Connect]
|
||||
Reference in New Issue
Block a user