SupportConsoleDevelopersStart a trialContact

Chapter 5. Using OpenID Connect (OIDC) multitenancy

This guide demonstrates how your OpenID Connect (OIDC) application can support multitenancy to serve multiple tenants from a single application. These tenants can be distinct realms or security domains within the same OIDC provider or even distinct OIDC providers.

Each customer functions as a distinct tenant when serving multiple customers from the same application, such as in a SaaS environment. By enabling multitenancy support to your applications, you can support distinct authentication policies for each tenant, even authenticating against different OIDC providers, such as Keycloak and Google.

To authorize a tenant by using Bearer Token Authorization, see the OpenID Connect (OIDC) Bearer token authentication guide.

To authenticate and authorize a tenant by using the OIDC authorization code flow, read the OpenID Connect authorization code flow mechanism for protecting web applications guide.

Also, see the OpenID Connect (OIDC) configuration properties reference guide.

5.1. Prerequisites

To complete this guide, you need:

  • Roughly 15 minutes
  • An IDE
  • JDK 17+ installed with JAVA_HOME configured appropriately
  • Apache Maven 3.9.6
  • A working container runtime (Docker or Podman)
  • Optionally the Quarkus CLI if you want to use it
  • Optionally Mandrel or GraalVM installed and configured appropriately if you want to build a native executable (or Docker if you use a native container build)
  • jq tool

5.2. Architecture

In this example, we build a very simple application that supports two resource methods:

  • /{tenant}

This resource returns information obtained from the ID token issued by the OIDC provider about the authenticated user and the current tenant.

  • /{tenant}/bearer

This resource returns information obtained from the Access Token issued by the OIDC provider about the authenticated user and the current tenant.

5.3. Solution

For a thorough understanding, we recommend you build the application by following the upcoming step-by-step instructions.

Alternatively, if you prefer to start with the completed example, clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git -b 3.8, or download an archive.

The solution is located in the security-openid-connect-multi-tenancy-quickstart directory.

5.4. Creating the Maven project

First, we need a new project. Create a new project with the following command:

  • Using the Quarkus CLI: 

    quarkus create app org.acme:security-openid-connect-multi-tenancy-quickstart \
    --extension='oidc,resteasy-reactive-jackson' \
    --no-code
cd security-openid-connect-multi-tenancy-quickstart

    To create a Gradle project, add the --gradle or --gradle-kotlin-dsl option.

    For more information about how to install and use the Quarkus CLI, see the Quarkus CLI guide.

  • Using Maven: 

    mvn io.quarkus.platform:quarkus-maven-plugin:3.8.5:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=security-openid-connect-multi-tenancy-quickstart \
    -Dextensions='oidc,resteasy-reactive-jackson' \
    -DnoCode
cd security-openid-connect-multi-tenancy-quickstart

    To create a Gradle project, add the -DbuildTool=gradle or -DbuildTool=gradle-kotlin-dsl option.

For Windows users:

  • If using cmd, (don’t use backward slash \ and put everything on the same line)
  • If using Powershell, wrap -D parameters in double quotes e.g. "-DprojectArtifactId=security-openid-connect-multi-tenancy-quickstart"

If you already have your Quarkus project configured, add the oidc extension to your project by running the following command in your project base directory:

  • Using the Quarkus CLI: 

    quarkus extension add oidc

  • Using Maven: 

    ./mvnw quarkus:add-extension -Dextensions='oidc'

  • Using Gradle: 

    ./gradlew addExtension --extensions='oidc'

This adds the following to your build file:

  • Using Maven: 

    <dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-oidc</artifactId>
</dependency>

  • Using Gradle: 

    implementation("io.quarkus:quarkus-oidc")

5.5. Writing the application

Start by implementing the /{tenant} endpoint. As you can see from the source code below, it is just a regular Jakarta REST resource: 

package org.acme.quickstart.oidc;

import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;

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 OIDC provider.
     */
    @Inject
    @IdToken
    JsonWebToken idToken;

    /**
     * Injection point for the Access Token issued by the OIDC provider.
     */
    @Inject
    JsonWebToken accessToken;

    /**
     * Returns the ID Token info.
     * This endpoint exists only for demonstration purposes.
     * Do not expose this token in a real application.
     *
     * @return ID Token info
     */
    @GET
    @Produces("text/html")
    public String getIdTokenInfo() {
        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();
    }

    /**
     * Returns the Access Token info.
     * This endpoint exists only for demonstration purposes.
     * Do not expose this token in a real application.
     *
     * @return Access Token info
     */
    @GET
    @Produces("text/html")
    @Path("bearer")
    public String getAccessTokenInfo() {
        StringBuilder response = new StringBuilder().append("<html>")
                .append("<body>");

        response.append("<h2>Welcome, ").append(this.accessToken.getClaim("email").toString()).append("</h2>\n");
        response.append("<h3>You are accessing the application within tenant <b>").append(accessToken.getIssuer()).append(" boundaries</b></h3>");

        return response.append("</body>").append("</html>").toString();
    }
}

To resolve the tenant from incoming requests and map it to a specific quarkus-oidc tenant configuration in application.properties, create an implementation for the io.quarkus.oidc.TenantConfigResolver interface, which can dynamically resolve tenant configurations: 

package org.acme.quickstart.oidc;

import jakarta.enterprise.context.ApplicationScoped;

import org.eclipse.microprofile.config.ConfigProvider;

import io.quarkus.oidc.OidcRequestContext;
import io.quarkus.oidc.OidcTenantConfig;
import io.quarkus.oidc.OidcTenantConfig.ApplicationType;
import io.quarkus.oidc.TenantConfigResolver;
import io.smallrye.mutiny.Uni;
import io.vertx.ext.web.RoutingContext;

@ApplicationScoped
public class CustomTenantResolver implements TenantConfigResolver {

    @Override
    public Uni<OidcTenantConfig> resolve(RoutingContext context, OidcRequestContext<OidcTenantConfig> requestContext) {
        String path = context.request().path();

        if (path.startsWith("/tenant-a")) {
           String keycloakUrl = ConfigProvider.getConfig().getValue("keycloak.url", String.class);

            OidcTenantConfig config = new OidcTenantConfig();
            config.setTenantId("tenant-a");
            config.setAuthServerUrl(keycloakUrl + "/realms/tenant-a");
            config.setClientId("multi-tenant-client");
            config.getCredentials().setSecret("secret");
            config.setApplicationType(ApplicationType.HYBRID);
            return Uni.createFrom().item(config);
        } else {
            // resolve to default tenant config
            return Uni.createFrom().nullItem();
        }
    }
}

In the preceding implementation, tenants are resolved from the request path. If no tenant can be inferred, null is returned to indicate that the default tenant configuration should be used.

The tenant-a application type is hybrid; it can accept HTTP bearer tokens if provided. Otherwise, it initiates an authorization code flow when authentication is required.

5.6. Configuring the application

# Default tenant configuration
%prod.quarkus.oidc.auth-server-url=http://localhost:8180/realms/quarkus
quarkus.oidc.client-id=multi-tenant-client
quarkus.oidc.application-type=web-app

# Tenant A configuration is created dynamically in CustomTenantConfigResolver

# HTTP security configuration
quarkus.http.auth.permission.authenticated.paths=/*
quarkus.http.auth.permission.authenticated.policy=authenticated

The first configuration is the default tenant configuration that should be used when the tenant cannot be inferred from the request. Be aware that a %prod profile prefix is used with quarkus.oidc.auth-server-url to support testing a multitenant application with Dev Services For Keycloak. This configuration uses a Keycloak instance to authenticate users.

The second configuration, provided by TenantConfigResolver, is used when an incoming request is mapped to the tenant-a tenant.

Both configurations map to the same Keycloak server instance while using distinct realms.

Alternatively, you can configure the tenant tenant-a directly in application.properties: 

# Default tenant configuration
%prod.quarkus.oidc.auth-server-url=http://localhost:8180/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/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

In that case, also use a custom TenantConfigResolver to resolve it: 

package org.acme.quickstart.oidc;

import jakarta.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 configuration
            return null;
        }

        return parts[1];
    }
}

You can define multiple tenants in your configuration file. To map them correctly when resolving a tenant from your TenantResolver implementation, ensure each has a unique alias.

However, using a static tenant resolution, which involves configuring tenants in application.properties and resolving them with TenantResolver, does not work for testing endpoints with Dev Services for Keycloak because it does not know how the requests are be mapped to individual tenants, and cannot dynamically provide tenant-specific quarkus.oidc.<tenant-id>.auth-server-url values. Therefore, using %prod prefixes with tenant-specific URLs within application.properties does not work in both test and development modes.

Note

When a current tenant represents an OIDC web-app application, the current io.vertx.ext.web.RoutingContext contains a tenant-id attribute by the time the custom tenant resolver has been called for all the requests completing the code authentication flow and the already authenticated requests, when either a tenant-specific state or session cookie already exists. Therefore, when working with multiple OIDC providers, you only need a path-specific check to resolve a tenant id if the RoutingContext does not have the tenant-id attribute set, for example: 

package org.acme.quickstart.oidc;

import jakarta.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 tenantId = context.get("tenant-id");
        if (tenantId != null) {
            return tenantId;
        } else {
            // Initial login request
            String path = context.request().path();
            String[] parts = path.split("/");

            if (parts.length == 0) {
                //Resolve to default tenant configuration
                return null;
            }
            return parts[1];
        }
    }
}

This is how Quarkus OIDC resolves static custom tenants if no custom TenantResolver is registered.

A similar technique can be used with TenantConfigResolver, where a tenant-id provided in the context can return OidcTenantConfig already prepared with the previous request.

Note

If you also use Hibernate ORM multitenancy or MongoDB with Panache multitenancy and both tenant ids are the same and must be extracted from the Vert.x RoutingContext, you can pass the tenant id from the OIDC Tenant Resolver to the Hibernate ORM Tenant Resolver or MongoDB with Panache Mongo Database Resolver as a RoutingContext attribute, for example: 

public class CustomTenantResolver implements TenantResolver {

    @Override
    public String resolve(RoutingContext context) {
        String tenantId = extractTenantId(context);
        context.put("tenantId", tenantId);
        return tenantId;
    }
}

5.7. Starting and configuring the Keycloak server

To start a Keycloak server, you can use Docker and run the following command: 

docker run --name keycloak -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin -p 8180:8080 quay.io/keycloak/keycloak:{keycloak.version} start-dev

where keycloak.version is set to 24.0.0 or higher.

Access your Keycloak server at localhost:8180.

Log in as the admin user to access the Keycloak administration console. The username and password are both admin.

Now, import the realms for the two tenants:

For more information, see the Keycloak documentation about how to create a new realm.

5.8. Running and using the application

5.8.1. Running in developer mode

To run the microservice in dev mode, use:

  • Using the Quarkus CLI: 

    quarkus dev

  • Using Maven: 

    ./mvnw quarkus:dev

  • Using Gradle: 

    ./gradlew --console=plain quarkusDev

5.8.2. Running in JVM mode

After exploring the application in dev mode, you can run it as a standard Java application.

First, compile it:

  • Using the Quarkus CLI: 

    quarkus build

  • Using Maven: 

    ./mvnw install

  • Using Gradle: 

    ./gradlew build

Then run it: 

java -jar target/quarkus-app/quarkus-run.jar

5.8.3. Running in native mode

This same demo can be compiled into native code; no modifications are 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 resources.

Compilation takes a bit longer, so this step is turned off by default; let’s build again by enabling the native build:

  • Using the Quarkus CLI: 

    quarkus build --native

  • Using Maven: 

    ./mvnw install -Dnative

  • Using Gradle: 

    ./gradlew build -Dquarkus.package.type=native

After a little while, you can run this binary directly: 

./target/security-openid-connect-multi-tenancy-quickstart-runner

5.9. Test the application

5.9.1. Use the browser

To test the application, open your browser and access the following URL:

If everything works as expected, you are redirected to the Keycloak server to authenticate. Be aware that the requested path defines a default tenant, which we don’t have mapped in the configuration file. In this case, the default configuration is used.

To authenticate to the application, enter the following credentials in the Keycloak login page:

  • Username: alice
  • Password: alice

After clicking the Login button, you are redirected back to the application.

If you try now to access the application at the following URL:

You are redirected again to the Keycloak login page. However, this time, you are going to authenticate by using a different realm.

In both cases, the landing page shows the user’s name and email if the user is successfully authenticated. Although alice exists in both tenants, the application treats them as distinct users in separate realms.

5.10. Static tenant configuration resolution

When you set multiple tenant configurations in the application.properties file, you only need to specify how the tenant identifier gets resolved. To configure the resolution of the tenant identifier, use one of the following options:

These tenant resolution options are tried in the order they are listed until the tenant id gets resolved. If the tenant id remains unresolved (null), the default (unnamed) tenant configuration is selected.

5.10.1. Resolve with TenantResolver

The following application.properties example shows how you can resolve the tenant identifier of two tenants named a and b by using the TenantResolver method: 

# Tenant 'a' configuration
quarkus.oidc.a.auth-server-url=http://localhost:8180/realms/quarkus-a
quarkus.oidc.a.client-id=client-a
quarkus.oidc.a.credentials.secret=client-a-secret

# Tenant 'b' configuration
quarkus.oidc.b.auth-server-url=http://localhost:8180/realms/quarkus-b
quarkus.oidc.b.client-id=client-b
quarkus.oidc.b.credentials.secret=client-b-secret

You can return the tenant id of either a or b from quarkus.oidc.TenantResolver: 

import quarkus.oidc.TenantResolver;

public class CustomTenantResolver implements TenantResolver {

    @Override
    public String resolve(RoutingContext context) {
        String path = context.request().path();
        if (path.endsWith("a")) {
            return "a";
        } else if (path.endsWith("b")) {
            return "b";
        } else {
            // default tenant
            return null;
        }
    }
}

In this example, the value of the last request path segment is a tenant id, but if required, you can implement a more complex tenant identifier resolution logic.

5.10.2. Default resolution

The default resolution for a tenant identifier is convention based, whereby the authentication request must include the tenant identifier in the last segment of the request path.

The following application.properties example shows how you can configure two tenants named google and github: 

# Tenant 'google' configuration
quarkus.oidc.google.provider=google
quarkus.oidc.google.client-id=${google-client-id}
quarkus.oidc.google.credentials.secret=${google-client-secret}
quarkus.oidc.google.authentication.redirect-path=/signed-in

# Tenant 'github' configuration
quarkus.oidc.github.provider=google
quarkus.oidc.github.client-id=${github-client-id}
quarkus.oidc.github.credentials.secret=${github-client-secret}
quarkus.oidc.github.authentication.redirect-path=/signed-in

In the provided example, both tenants configure OIDC web-app applications to use an authorization code flow to authenticate users and require session cookies to be generated after authentication. After Google or GitHub authenticates the current user, the user gets returned to the /signed-in area for authenticated users, such as a secured resource path on the JAX-RS endpoint.

Finally, to complete the default tenant resolution, set the following configuration property: 

quarkus.http.auth.permission.login.paths=/google,/github
quarkus.http.auth.permission.login.policy=authenticated

If the endpoint is running on http://localhost:8080, you can also provide UI options for users to log in to either http://localhost:8080/google or http://localhost:8080/github, without having to add specific /google or /github JAX-RS resource paths. Tenant identifiers are also recorded in the session cookie names after the authentication is completed. Therefore, authenticated users can access the secured application area without requiring either the google or github path values to be included in the secured URL.

Default resolution can also work for Bearer token authentication. Still, it might be less practical because a tenant identifier must always be set as the last path segment value.

5.10.3. Resolve with annotations

You can use the io.quarkus.oidc.Tenant annotation for resolving the tenant identifiers as an alternative to using io.quarkus.oidc.TenantResolver.

Note

Proactive HTTP authentication must be disabled (quarkus.http.auth.proactive=false) for this to work. For more information, see the Proactive authentication guide.

Assuming your application supports two OIDC tenants, the hr and default tenants, all resource methods and classes carrying @Tenant("hr") are authenticated by using the OIDC provider configured by quarkus.oidc.hr.auth-server-url. In contrast, all other classes and methods are still authenticated by using the default OIDC provider. 

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

import io.quarkus.oidc.Tenant;
import io.quarkus.security.Authenticated;

@Authenticated
@Path("/api/hello")
public class HelloResource {

    @Tenant("hr") 1
    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String sayHello() {
        return "Hello!";
    }
}
1
The io.quarkus.oidc.Tenant annotation must be placed on either the resource class or resource method.

5.11. Dynamic tenant configuration resolution

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: 

package io.quarkus.it.keycloak;

import jakarta.enterprise.context.ApplicationScoped;
import java.util.function.Supplier;

import io.smallrye.mutiny.Uni;
import io.quarkus.oidc.OidcRequestContext;
import io.quarkus.oidc.OidcTenantConfig;
import io.quarkus.oidc.TenantConfigResolver;
import io.vertx.ext.web.RoutingContext;

@ApplicationScoped
public class CustomTenantConfigResolver implements TenantConfigResolver {

    @Override
    public Uni<OidcTenantConfig> resolve(RoutingContext context, OidcRequestContext<OidcTenantConfig> requestContext) {
        String path = context.request().path();
        String[] parts = path.split("/");

        if (parts.length == 0) {
            //Resolve to default tenant configuration
            return null;
        }

        if ("tenant-c".equals(parts[1])) {
            // Do 'return requestContext.runBlocking(createTenantConfig());'
            // if a blocking call is required to create a tenant config,
            return Uni.createFromItem(createTenantConfig());
        }

        //Resolve to default tenant configuration
        return null;
    }

    private Supplier<OidcTenantConfig> createTenantConfig() {
        final OidcTenantConfig config = new OidcTenantConfig();

        config.setTenantId("tenant-c");
        config.setAuthServerUrl("http://localhost:8180/realms/tenant-c");
        config.setClientId("multi-tenant-client");
        OidcTenantConfig.Credentials credentials = new OidcTenantConfig.Credentials();

        credentials.setSecret("my-secret");

        config.setCredentials(credentials);

        // Any other setting supported by the quarkus-oidc extension

        return () -> config;
    }
}

The OidcTenantConfig returned by this method is the same one used to parse the oidc namespace configuration from the application.properties. You can populate it by using any settings supported by the quarkus-oidc extension.

If the dynamic tenant resolver returns null, a Static tenant configuration resolution is attempted next.

5.11.1. Tenant resolution for OIDC web-app applications

The simplest option for resolving the OIDC web-app application configuration is to follow the steps described in the Default resolution section.

Try one of the options below if the default resolution strategy does not work for your application setup.

Several options are available for selecting the tenant configuration that should be used to secure the current HTTP request for both service and web-app OIDC applications, such as:

  • Check the URL paths. For example, a tenant-service configuration must be used for the /service paths, while a tenant-manage configuration must be used for the /management paths.
  • Check the HTTP headers. For example, with a URL path always being /service, a header such as Realm: service or Realm: management can help to select between the tenant-service and tenant-manage configurations.
  • Check the URL query parameters. It can work similarly to the way the headers are used to select the tenant configuration.

All these options can be easily implemented with the custom TenantResolver and TenantConfigResolver implementations for the OIDC service applications.

However, due to an HTTP redirect required to complete the code authentication flow for the OIDC web-app applications, a custom HTTP cookie might be needed to select the same tenant configuration before and after this redirect request because:

  • The URL path might not be the same after the redirect request if a single redirect URL has been registered in the OIDC provider. The original request path can be restored after the tenant configuration has been resolved.
  • The HTTP headers used during the original request are unavailable after the redirect.
  • The custom URL query parameters are restored after the redirect but only after the tenant configuration is resolved.

One option to ensure the information for resolving the tenant configurations for web-app applications is available before and after the redirect is to use a cookie, for example: 

package org.acme.quickstart.oidc;

import java.util.List;

import jakarta.enterprise.context.ApplicationScoped;

import io.quarkus.oidc.TenantResolver;
import io.vertx.core.http.Cookie;
import io.vertx.ext.web.RoutingContext;

@ApplicationScoped
public class CustomTenantResolver implements TenantResolver {

    @Override
    public String resolve(RoutingContext context) {
        List<String> tenantIdQuery = context.queryParam("tenantId");
        if (!tenantIdQuery.isEmpty()) {
            String tenantId = tenantIdQuery.get(0);
            context.response().addCookie(Cookie.cookie("tenant", tenantId));
            return tenantId;
        } else if (!context.request().cookies("tenant").isEmpty()) {
            return context.request().getCookie("tenant").getValue();
        }

        return null;
    }
}

5.12. Disabling tenant configurations

Custom TenantResolver and TenantConfigResolver implementations might return null if no tenant can be inferred from the current request and a fallback to the default tenant configuration is required.

If you expect the custom resolvers always to resolve a tenant, you do not need to configure the default tenant resolution.

  • To turn off the default tenant configuration, set quarkus.oidc.tenant-enabled=false.
Note

The default tenant configuration is automatically disabled when quarkus.oidc.auth-server-url is not configured, but either custom tenant configurations are available or TenantConfigResolver is registered.

Be aware that tenant-specific configurations can also be disabled, for example: quarkus.oidc.tenant-a.tenant-enabled=false.

5.13. References

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.