You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
186 lines
11 KiB
186 lines
11 KiB
|
|
[[how-to-multitenancy]] |
|
= How-to: Implement Multitenancy |
|
:index-link: ../how-to.html |
|
:docs-dir: .. |
|
|
|
This guide shows how to customize Spring Authorization Server to support multiple issuers per host in a multi-tenant hosting configuration. |
|
The purpose of this guide is to demonstrate a general pattern for building multi-tenant capable components for Spring Authorization Server, which can also be applied to other components to suit your needs. |
|
|
|
* xref:guides/how-to-multitenancy.adoc#multi-tenant-define-tenant-identifier[Define the tenant identifier] |
|
* xref:guides/how-to-multitenancy.adoc#multi-tenant-enable-multiple-issuers[Enable multiple issuers] |
|
* xref:guides/how-to-multitenancy.adoc#multi-tenant-create-component-registry[Create a component registry] |
|
* xref:guides/how-to-multitenancy.adoc#multi-tenant-create-components[Create multi-tenant components] |
|
* xref:guides/how-to-multitenancy.adoc#multi-tenant-add-tenants-dynamically[Add tenants dynamically] |
|
|
|
[[multi-tenant-define-tenant-identifier]] |
|
== Define the tenant identifier |
|
|
|
The xref:protocol-endpoints.adoc#oidc-provider-configuration-endpoint[OpenID Connect 1.0 Provider Configuration Endpoint] and xref:protocol-endpoints.adoc#oauth2-authorization-server-metadata-endpoint[OAuth2 Authorization Server Metadata Endpoint] allow for path components in the issuer identifier value, which effectively enables supporting multiple issuers per host. |
|
|
|
For example, an https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationRequest[OpenID Provider Configuration Request] "http://localhost:9000/issuer1/.well-known/openid-configuration" or an https://datatracker.ietf.org/doc/html/rfc8414#section-3.1[Authorization Server Metadata Request] "http://localhost:9000/.well-known/oauth-authorization-server/issuer1" would return the following configuration metadata: |
|
|
|
[source,json] |
|
---- |
|
{ |
|
"issuer": "http://localhost:9000/issuer1", |
|
"authorization_endpoint": "http://localhost:9000/issuer1/oauth2/authorize", |
|
"token_endpoint": "http://localhost:9000/issuer1/oauth2/token", |
|
"jwks_uri": "http://localhost:9000/issuer1/oauth2/jwks", |
|
"revocation_endpoint": "http://localhost:9000/issuer1/oauth2/revoke", |
|
"introspection_endpoint": "http://localhost:9000/issuer1/oauth2/introspect", |
|
... |
|
} |
|
---- |
|
|
|
NOTE: The base URL of the xref:protocol-endpoints.adoc[Protocol Endpoints] is the issuer identifier value. |
|
|
|
Essentially, an issuer identifier with a path component represents the _"tenant identifier"_. |
|
|
|
[[multi-tenant-enable-multiple-issuers]] |
|
== Enable multiple issuers |
|
|
|
Support for using multiple issuers per host is disabled by default. |
|
To enable, add the following configuration: |
|
|
|
.AuthorizationServerSettingsConfig |
|
[source,java] |
|
---- |
|
include::{examples-dir}/main/java/sample/multitenancy/AuthorizationServerSettingsConfig.java[] |
|
---- |
|
|
|
<1> Set to `true` to allow usage of multiple issuers per host. |
|
|
|
[[multi-tenant-create-component-registry]] |
|
== Create a component registry |
|
|
|
We start by building a simple registry for managing the concrete components for each tenant. |
|
The registry contains the logic for retrieving a concrete implementation of a particular class using the issuer identifier value. |
|
|
|
We will use the following class in each of the delegating implementations below: |
|
|
|
.TenantPerIssuerComponentRegistry |
|
[source,java] |
|
---- |
|
include::{examples-dir}/main/java/sample/multitenancy/TenantPerIssuerComponentRegistry.java[] |
|
---- |
|
|
|
<1> Component registration implicitly enables an allowlist of approved issuers that can be used. |
|
|
|
TIP: This registry is designed to allow components to be easily registered at startup to support adding tenants statically, but also supports xref:guides/how-to-multitenancy.adoc#multi-tenant-add-tenants-dynamically[adding tenants dynamically] at runtime. |
|
|
|
[[multi-tenant-create-components]] |
|
== Create multi-tenant components |
|
|
|
The components that require multi-tenant capability are: |
|
|
|
* xref:guides/how-to-multitenancy.adoc#multi-tenant-registered-client-repository[`RegisteredClientRepository`] |
|
* xref:guides/how-to-multitenancy.adoc#multi-tenant-oauth2-authorization-service[`OAuth2AuthorizationService`] |
|
* xref:guides/how-to-multitenancy.adoc#multi-tenant-oauth2-authorization-consent-service[`OAuth2AuthorizationConsentService`] |
|
* xref:guides/how-to-multitenancy.adoc#multi-tenant-jwk-source[`JWKSource<SecurityContext>`] |
|
|
|
For each of these components, an implementation of a composite can be provided that delegates to the concrete component associated to the _"requested"_ issuer identifier. |
|
|
|
Let's step through a scenario of how to customize Spring Authorization Server to support 2x tenants for each multi-tenant capable component. |
|
|
|
[[multi-tenant-registered-client-repository]] |
|
=== Multi-tenant RegisteredClientRepository |
|
|
|
The following example shows a sample implementation of a xref:core-model-components.adoc#registered-client-repository[`RegisteredClientRepository`] that is composed of 2x `JdbcRegisteredClientRepository` instances, where each instance is mapped to an issuer identifier: |
|
|
|
.RegisteredClientRepositoryConfig |
|
[source,java] |
|
---- |
|
include::{examples-dir}/main/java/sample/multitenancy/RegisteredClientRepositoryConfig.java[] |
|
---- |
|
|
|
TIP: Click on the "Expand folded text" icon in the code sample above to display the full example. |
|
|
|
<1> A `JdbcRegisteredClientRepository` instance mapped to issuer identifier `issuer1` and using a dedicated `DataSource`. |
|
<2> A `JdbcRegisteredClientRepository` instance mapped to issuer identifier `issuer2` and using a dedicated `DataSource`. |
|
<3> A composite implementation of a `RegisteredClientRepository` that delegates to a `JdbcRegisteredClientRepository` mapped to the _"requested"_ issuer identifier. |
|
<4> Obtain the `JdbcRegisteredClientRepository` that is mapped to the _"requested"_ issuer identifier indicated by `AuthorizationServerContext.getIssuer()`. |
|
<5> If unable to find `JdbcRegisteredClientRepository`, then error since the _"requested"_ issuer identifier is not in the allowlist of approved issuers. |
|
|
|
IMPORTANT: Explicitly configuring the issuer identifier via `AuthorizationServerSettings.builder().issuer("http://localhost:9000")` forces to a single-tenant configuration. Avoid explicitly configuring the issuer identifier when using a multi-tenant hosting configuration. |
|
|
|
In the preceding example, each of the `JdbcRegisteredClientRepository` instances are configured with a `JdbcTemplate` and associated `DataSource`. |
|
This is important in a multi-tenant configuration as a primary requirement is to have the ability to isolate the data from each tenant. |
|
|
|
Configuring a dedicated `DataSource` for each component instance provides the flexibility to isolate the data in its own schema within the same database instance or alternatively isolate the data in a separate database instance altogether. |
|
|
|
The following example shows a sample configuration of 2x `DataSource` `@Bean` (one for each tenant) that are used by the multi-tenant capable components: |
|
|
|
.DataSourceConfig |
|
[source,java] |
|
---- |
|
include::{examples-dir}/main/java/sample/multitenancy/DataSourceConfig.java[] |
|
---- |
|
|
|
<1> Use a separate H2 database instance using `issuer1-db` as the name. |
|
<2> Use a separate H2 database instance using `issuer2-db` as the name. |
|
|
|
[[multi-tenant-oauth2-authorization-service]] |
|
=== Multi-tenant OAuth2AuthorizationService |
|
|
|
The following example shows a sample implementation of an xref:core-model-components.adoc#oauth2-authorization-service[`OAuth2AuthorizationService`] that is composed of 2x `JdbcOAuth2AuthorizationService` instances, where each instance is mapped to an issuer identifier: |
|
|
|
.OAuth2AuthorizationServiceConfig |
|
[source,java] |
|
---- |
|
include::{examples-dir}/main/java/sample/multitenancy/OAuth2AuthorizationServiceConfig.java[] |
|
---- |
|
|
|
<1> A `JdbcOAuth2AuthorizationService` instance mapped to issuer identifier `issuer1` and using a dedicated `DataSource`. |
|
<2> A `JdbcOAuth2AuthorizationService` instance mapped to issuer identifier `issuer2` and using a dedicated `DataSource`. |
|
<3> A composite implementation of an `OAuth2AuthorizationService` that delegates to a `JdbcOAuth2AuthorizationService` mapped to the _"requested"_ issuer identifier. |
|
<4> Obtain the `JdbcOAuth2AuthorizationService` that is mapped to the _"requested"_ issuer identifier indicated by `AuthorizationServerContext.getIssuer()`. |
|
<5> If unable to find `JdbcOAuth2AuthorizationService`, then error since the _"requested"_ issuer identifier is not in the allowlist of approved issuers. |
|
|
|
[[multi-tenant-oauth2-authorization-consent-service]] |
|
=== Multi-tenant OAuth2AuthorizationConsentService |
|
|
|
The following example shows a sample implementation of an xref:core-model-components.adoc#oauth2-authorization-consent-service[`OAuth2AuthorizationConsentService`] that is composed of 2x `JdbcOAuth2AuthorizationConsentService` instances, where each instance is mapped to an issuer identifier: |
|
|
|
.OAuth2AuthorizationConsentServiceConfig |
|
[source,java] |
|
---- |
|
include::{examples-dir}/main/java/sample/multitenancy/OAuth2AuthorizationConsentServiceConfig.java[] |
|
---- |
|
|
|
<1> A `JdbcOAuth2AuthorizationConsentService` instance mapped to issuer identifier `issuer1` and using a dedicated `DataSource`. |
|
<2> A `JdbcOAuth2AuthorizationConsentService` instance mapped to issuer identifier `issuer2` and using a dedicated `DataSource`. |
|
<3> A composite implementation of an `OAuth2AuthorizationConsentService` that delegates to a `JdbcOAuth2AuthorizationConsentService` mapped to the _"requested"_ issuer identifier. |
|
<4> Obtain the `JdbcOAuth2AuthorizationConsentService` that is mapped to the _"requested"_ issuer identifier indicated by `AuthorizationServerContext.getIssuer()`. |
|
<5> If unable to find `JdbcOAuth2AuthorizationConsentService`, then error since the _"requested"_ issuer identifier is not in the allowlist of approved issuers. |
|
|
|
[[multi-tenant-jwk-source]] |
|
=== Multi-tenant JWKSource |
|
|
|
And finally, the following example shows a sample implementation of a `JWKSource<SecurityContext>` that is composed of 2x `JWKSet` instances, where each instance is mapped to an issuer identifier: |
|
|
|
.JWKSourceConfig |
|
[source,java] |
|
---- |
|
include::{examples-dir}/main/java/sample/multitenancy/JWKSourceConfig.java[] |
|
---- |
|
|
|
<1> A `JWKSet` instance mapped to issuer identifier `issuer1`. |
|
<2> A `JWKSet` instance mapped to issuer identifier `issuer2`. |
|
<3> A composite implementation of an `JWKSource<SecurityContext>` that uses the `JWKSet` mapped to the _"requested"_ issuer identifier. |
|
<4> Obtain the `JWKSet` that is mapped to the _"requested"_ issuer identifier indicated by `AuthorizationServerContext.getIssuer()`. |
|
<5> If unable to find `JWKSet`, then error since the _"requested"_ issuer identifier is not in the allowlist of approved issuers. |
|
|
|
[[multi-tenant-add-tenants-dynamically]] |
|
== Add Tenants Dynamically |
|
|
|
If the number of tenants is dynamic and can change at runtime, defining each `DataSource` as a `@Bean` may not be feasible. |
|
In this case, the `DataSource` and corresponding components can be registered through other means at application startup and/or runtime. |
|
|
|
The following example shows a Spring `@Service` capable of adding tenants dynamically: |
|
|
|
.TenantService |
|
[source,java] |
|
---- |
|
include::{examples-dir}/main/java/sample/multitenancy/TenantService.java[] |
|
----
|
|
|