intra-mart Accel Platform / Setup Guide

Version 10 2014-04-01

«  10.3. Multiple Tenants by WAR file   ::   Contents   ::   10.5. Port List  »

10.4. Tenant Resolution Function

10.4.1. Overview

In this chapter, how the operation target tenant is resolved when virtual tenant function is used is described.
In intra-mart Accel Platform, tenant ID property of account context indicates the operation target tenant.
The tenant ID property of account context will be resolved by using tenant resolution function.
Specifications of tenant resolution function are hereafter described.
The program to be created on intra-mart Accel Platform does not have to engage the operation target tenant.
(Operation target tenant will be automatically resolved by the tenant resolution system that is described on this page.)

10.4.1.1. About Tenant Auto Resolution Function using Request Information

In intra-mart Accel Platform, tenant for operations can be determined using request information.
By using this function, particular tenant will be the tenant for operations regardless of user authentication status, and it is not necessary to specify the tenant ID for log-in.
For example, if you do automatic resolution for tenant using sub-domain of URL, tenant for operations can be determined for each URL as shown below.
../../../_images/resolve_tenant_for_url.png

Note

Tenant Auto Resolution Function using Request Informationis not used as standard.
Tenant Auto Resolution Function using Request Informationwill be enabled if you use a module which provides [IM-SecureSingOn for Accel Platform] application or the function.

Note

Please refer to [Providing Tenant Auto Resolution Function using Request Information] for the implementation method of Tenant Auto Resolution Function using Request Information.

10.4.2. Tenant Resolution Scenarios

There are following scenarios to resolve tenant when Web accessing is made :
  • General User
    • In case the tenant is specified for log-in
    • In case Tenant Auto Resolution Function using Request Informationis used

  • System Administrator

10.4.2.1. General User

10.4.2.1.1. In case the tenant is specified for log-in

If there are multiple tenants, you should specify the tenant on log-in screen of general user and log-in.

If you successfully log-in, the tenant specified on log-in screen will be the tenant for operations.
If you log-out, it will be unauthenticated and the default tenant will become the subject for operations.
In unauthenticated status, the default tenant will be the tenant which is the subject for operations.
../../../_images/normal_flow.png

10.4.2.1.2. In case Tenant Auto Resolution Function using Request Informationis used

By using Tenant Auto Resolution Function using Request Information, the tenant can be resolved from arbitrary information of the request.
When you are using this function, the tenant for operations will not be switched by log-in/out and you cannot log-in specifying the tenant on log-in screen.
In unauthenticated status, the tenant which is automatically resolved will be the tenant for operations.
../../../_images/resolved_tenant_flow.png

10.4.2.2. System Administrator

In case of system administrator, the tenant for operations will be the default tenant.
System administrator cacn switch the tenant for operations using tenant switching function. Please refer to [Tenant Switching] for details.

10.4.3. Providing Tenant Auto Resolution Function using Request Information

10.4.3.1. Overview

If Tenant Auto Resolution Function using Request Informationis enabled, tenant for operations will be resolved by the following flow.
  1. Do tenant ID resolution in the provided tenant automatic resolution function.
  2. Do tenant ID verification in the provided tenant verification function.
  3. Set tenant ID to the tenant ID property of account context.
About Tenant Automatic Resplution Function、Tenant Verification Function and its providing method are described below.

10.4.3.2. Tenant Automatic Resplution Function

It is a function to resolve the tenant ID from the request information.

You can use Tenant Auto Resolution Function using Request Information``RequestBasedTenantIdResolver`` by creating a class which implements interface and setting the plug-in setting file.

Multiple tenant resolution function can be set and provided.
If multiple tenant resolution functions are provided, a tenant resolution function will be executed in the priority sequence of tenant resolution function according to the plug-in specifications.
Tenant resolution process is closed at the point when the tenand resolution is executed (when the value other than null is returned by getTenantId(HttpServletRequest) method). Subsequent tenant resolution function will not be executed.
If the tenant cannot resolve tenant (null is returned by getTenantId(HttpServletRequest) method), tenant resolution may be done in subsequent tenant resolution function.
If all tenant resolution functions failed to resolve the tenant, (all returned null), it will be resolved as default tenant if there occurs no problem in Tenant Verification Function verification which will be stated in the next section.

10.4.3.2.1. Tenant Automatic Resolution Function Creation

The class that implements following interface is created.
  • jp.co.intra_mart.foundation.admin.tenant.context.RequestBasedTenantIdResolver
Following is the sample implementation that resolves tenant by using Cookie.
package sample.context;

import javax.servlet.http.Cookie;
import javax.servlet.http.HttpServletRequest;

import jp.co.intra_mart.foundation.admin.tenant.context.RequestBasedTenantIdResolver;

public class CookieTenantIdResolver implements RequestBasedTenantIdResolver {

    private static final String COOKIE_KEY = "X-TENANT-ID";

    @Override
    public String getTenantId(final HttpServletRequest request) {
        return getCookieValue(request, COOKIE_KEY);
    }

    private Cookie getCookie(final HttpServletRequest request, final String name) {
        final Cookie[] cookies = request.getCookies();

        if (cookies == null) {
            return null;
        }

        for (final Cookie cookie : cookies) {
            if (name.equals(cookie.getName())) {
                return cookie;
            }
        }

        return null;
    }

    private String getCookieValue(final HttpServletRequest request, final String name) {
        final Cookie cookie = getCookie(request, name);

        if (cookie == null) {
            return null;
        }

        return cookie.getValue();
    }

}

Note

Please refer to [API list of RequestBasedTenantIdResolver interface] for details of RequestBasedTenantIdResolver interface.

10.4.3.2.2. Tenant Automatic Resolution Function Setting

Tenant automatic resolution function is set in plug-in file. Therefore, the setting that uses plug-in function can be performed.
Extension point to set Tenant Auto Resolution Function using Request Information is jp.co.intra_mart.foundation.admin.tenant.context.tenant.resolvers.
The created plug-in file is placed in WEB-INF/plugin/sample_tenant_resolver/plugin.xml. (Folder name immediately under plugin can be changed to any name that does not duplicate with other plug-ins.)
Plug-in setting sample that operates tenant automatic resolution function implementation which uses above Cookie is shown below.
<?xml version="1.0" encoding="UTF-8"?>
<plugin>
    <extension point="jp.co.intra_mart.foundation.admin.tenant.context.tenant.resolvers">
        <tenant-id-resolvers
            id="sample.context.cookie_resolver"
            version="1.0.0"
            rank="1">

            <!-- tenant-id-resolver タグは複数指定可能です。 -->
            <!-- RequestBasedTenantIdResolverインタフェースを実装したクラスの完全修飾クラス名をclass属性に指定してください。 -->
            <tenant-id-resolver class="sample.context.CookieTenantIdResolver" />

        </tenant-id-resolvers>
    </extension>
</plugin>

Note

Please refer to [API List of PluginManager] for the setting specification of plug-in.

If above materials are deployed, the value of Cookie key X-TENANT-ID will be treated as tenant ID.

10.4.3.3. Tenant Verification Function

It is a function to judge if the tenant ID resolved by the tenant automatic resolution function has a valid value.

If the tenant ID resolved by the tenant automatic resolution function was not an error in the verification function, it will be set to the tenant ID property of account context. For example, if non-existing tenant ID is set to the tenant ID property of account context, functions provided by intra-mart Accel Platform may not work properly. Validity check will be performed in tenant verification function to avoid conditions like this.

Multiple tenant verification functions can be set and provided.
If multiple tenant verification functions are provided, it will be executed in the priority sequence of tenant verification function according to the plug-in specifications.
At the point when error (InvalidTenantIdException by validate(String, Resource) ) occurs in tenant verification, tenant verification is closed. Subsequent tenant verification functions will not be executed.

10.4.3.3.1. Tenant Verification Function Creation

Class that implements following interface is created.
  • jp.co.intra_mart.foundation.admin.tenant.context.TenantIdValidator
Sample implementation is shown as below.
package jp.co.intra_mart.foundation.admin.tenant;

import jp.co.intra_mart.foundation.admin.tenant.context.TenantIdValidator;
import jp.co.intra_mart.foundation.context.core.Resource;
import jp.co.intra_mart.system.admin.tenant.InvalidTenantIdException;

public class SampleTenantIdValidator implements TenantIdValidator {

    @Override
    public void validate(final String tenantId, final Resource resource) throws InvalidTenantIdException {

        if (tenantId != null && !tenantId.startsWith("TENANT_")) {
            // テナントID書式チェック
            // テナントIDが "TENANT_" で始まっていることをチェックします。
            throw new InvalidTenantIdException("テナントIDの書式が正しくありません。");
        }

    }

}

Note

Please refer to [API List of TenantIdValidator Interface] for the details of TenantIdValidator interface.

10.4.3.3.2. Tenant Verification Function Setting

Tenant verification function is also set by plug-in setting file as tenant automatic resolution function.
Extension point to set the tenant verification function is jp.co.intra_mart.foundation.admin.tenant.context.tenant.validators.
Sample plug-in setting file is shown as below.
<?xml version="1.0" encoding="UTF-8"?>
<plugin>
    <extension point="jp.co.intra_mart.foundation.admin.tenant.context.tenant.validators">
        <tenant-id-validators
            id="sample.context.sample_tenant_id_validator"
            version="1.0.0"
            rank="1">

            <!-- tenant-id-validator タグは複数指定可能です。 -->
            <!-- TenantIdValidatorインタフェースを実装したクラスの完全修飾クラス名をclass属性に指定してください。 -->
            <tenant-id-validator class="sample.context.SampleTenantIdValidator" />

        </tenant-id-validators>
    </extension>
</plugin>

10.4.3.3.3. StandardTenantIdValidator

It is an implementation class of TenantIdValidator provided as standard.
Tenant resolution check and tenant existence check are implemented by tenant automatic resolution function.
10.4.3.3.3.1. Complete Class Qualifier
jp.co.intra_mart.system.admin.context.StandardTenantIdValidator
10.4.3.3.3.2. Initialization Parameter of Plug-in
Since StandardTenantIdValidator implements PropertyInitParamable interface, the initialization parameter can be passed by plug-in setting file.
Initialization parameter is specified by <init-param> tag.
<?xml version="1.0" encoding="UTF-8"?>
<plugin>
    <extension point="jp.co.intra_mart.foundation.admin.tenant.context.tenant.validators">
        <tenant-id-validators
            id="jp.co.intra_mart.tenant_id.validator.standard"
            version="8.0.7"
            rank="100">
            <tenant-id-validator class="jp.co.intra_mart.system.admin.context.StandardTenantIdValidator">

                <init-param>
                    <param-name>required_tenant_id</param-name>
                    <param-value>true</param-value>
                </init-param>
                <init-param>
                    <param-name>valid_tenant_id</param-name>
                    <param-value>true</param-value>
                </init-param>

            </tenant-id-validator>
        </tenant-id-validators>
    </extension>
</plugin>
param-name Description
required_tenant_id
It checks if tenant ID is solved. It specifies true or false and will do the check in case of true.
If the tenant ID is not resolved, exception InvalidTenantIdException will occur and you will not be able to access the system.
Checking is not performed if it is omitted.
valid_tenant_id
It checks if the tenant ID is the one from tenant where the resolved tenant ID exists. It specifies true or false and will do the check in case of true.
If the resolved tenant ID is not the one from the existing tenant, exception InvalidTenantIdException will occur and you will not be able to access the system.
Checking is not performed if it is omitted.

Note

Please refer to [API List of PropertyInitParamable Interface] for details of PropertyInitParamable interface.

«  10.3. Multiple Tenants by WAR file   ::   Contents   ::   10.5. Port List  »

Copyright © 2012 NTT DATA INTRAMART CORPORATION