intra-mart Accel Platform 認可仕様書 第12版 2017-08-01

リソース管理

リソースとリソースグループ

認可 概要 で紹介した通り、認可を行う際の「何を」にあたる情報がリソースです。

リソースのキーとなる情報はリソースURIです。アプリケーションで認可機構を利用する場合、認可対象になるもの(「何を」にあたります)をリソースURIとして表現し、予め認可機構に登録します。これによって管理者がそのリソースの権限を管理できるようになります。

ユーザがそのリソースを利用しようとした際には、アプリケーションはリソースURIで認可機構に問い合わせることで管理者がそのリソースをユーザに対して利用を許可したかどうかを判断することができます。

../../../_images/GenericUse.png

リソースはリソースグループを使用して権限設定を階層的にまとめることができます。階層的に構成したリソースとリソースグループでは、上位に設定した権限設定を継承させて適用することができます。(この動作の詳細は「ポリシー解釈器 」を参照してください)

これによってある程度まとまったリソースに対して認可設定を行うことができるようになっています。

認可機構に対してAPIを使ってリソースを作成すると、リソースと対になるリソースグループが1つ作成されます。 APIモデル上ではリソースとリソースグループの持つ情報は以下のようになっています。

リソース

  • リソースURI(、および、ID)
  • リソースタイプ

リソースグループ

  • ID
  • 名称
  • 説明
  • グループの階層にかかわる情報

リソースは名称や説明を持ちません。リソースと対になっているリソースグループがリソースの名称や説明にあたる情報を保持します。このためAPIモデル上ではリソースとはリソースグループとリソースのセットの事になります。

../../../_images/R-RG.png

リソースURIの仕様

リソースURIは認可機構がシステム上で認可対象を特定するためのシステム上一意な識別子です。リソースURIは以下のような構成の文字列です。

RESOURCE-TYPE-ID:IDENTIFIER-COMPONENT

それぞれの意味合いを説明します。

RESOURCE-TYPE-ID
このリソースの振る舞いを決める リソースタイプ のIDがまず先頭に必要です。
: (コロン)
RESOURCE-TYPE-IDIDENTIFIER-COMPONENT を分ける記号として : (コロン)を使います。
IDENTIFIER-COMPONENT
このリソースをシステムで一意に判別するためのIDを表す文字列です。アプリケーション名やアプリケーション内のコンポーネント名などで階層を区切って、システム上他のアプリケーション等と衝突することの無いよう設計する必要があります。

リソースURIの例) service://authz/settings/basic

リソースタイプとアクション

認可 概要 で「どうする」として紹介しているものをアクションと呼びます。アクションはユーザがリソースに対してどういった操作を行うかを表すものです。リソースは必ず単一のリソースタイプを持っており、このリソースタイプがどういったアクションをとりうるのかを決定しています。

../../../_images/R-RT-A.png

リソースタイプとアクションはJavaクラスとして実装されています。リソースタイプは以下のような責務を負っています。

  • リソースタイプIDの定義
  • このリソースタイプで使用するアクションの定義・取扱い
    • 取りうるアクションの列挙
    • アクションのパース
  • リソースタイプにバインドされるリソースモデルの決定
  • リソースモデルのURIへの変換

アクションもリソースタイプ同様にJavaクラスとして実装され、 リソースタイプによってその関連が明示されます。

リソースタイプの定義

リソースタイプおよびアクションは必要に応じて実装を追加することができるようになっています。リソースタイプを定義するためには ResourceType インタフェースを実装したクラスと、リソースを扱うためのモデルクラスを作成する必要があります。

リソースタイプは以下のクラスを実装します。

完全修飾クラス名
jp.co.intra_mart.foundation.authz.model.resources.ResourceType<T>

型引数Tはリソースのモデルクラスです。このモデルクラスには特に制約はありません。ここで定義したモデルクラスを使用してリソース登録を行ったりすることができるようになるので、役割として適切であればアプリケーションなどで使用している既存のクラスをそのまま使用したほうが取り扱い易くなるでしょう。

注意

ResourceTypeとリソースモデルクラスは1対1の関係で定義されている必要があります。他のリソースタイプとモデルを共有することはできないので注意してください。

上記で定義したクラスは設定ファイルに記載することで認可機構に認識させます。以下のXMLファイルを作成します。

場所
%CONTEXT_PATH%/WEB-INF/conf/authz-resource-type-config/ 配下
XMLスキーマ
%CONTEXT_PATH%/WEB-INF/schema/authz-resource-type-config.xsd

下記は設定例です。下記のように、 resource-type 要素type-class 属性 にリソースタイプの実装クラスを、model-class 属性 にモデルクラスを、それぞれ完全修飾クラス名で記述します。 cache-class 属性 は任意項目で、リソースのキャッシュコントローラクラスを完全修飾クラス名で記述します。リソースのキャッシュを行わない場合は、記述する必要はありません。

<?xml version="1.0" encoding="UTF-8"?>
<p:authz-resource-type-config
    xmlns:p="http://www.intra-mart.jp/authz/authz-resource-type-config/"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.intra-mart.jp/authz/authz-resource-type-config/ ../../schema/authz-resource-type-config.xsd">

  <resource-type
      type-class="jp.co.intra_mart.system.router.authz.resourcetype.GeneralServiceResourceType"
      model-class="jp.co.intra_mart.system.router.authz.resourcetype.GeneralServiceModel"
      cache-class="jp.co.intra_mart.system.router.authz.resourcetype.GeneralServiceResourceTypeCacheController" />

</p:authz-resource-type-config>

リソースタイプの追加にあたっては別途 「認可拡張プログラミングガイド」の「リソース拡張ガイド」の章 で手順や必要な準備について解説しています。 リソースタイプを追加する際にはこちらも参照してください。

intra-mart Accel Platform の標準的なモジュール構成においてデフォルトでインストールされるリソースタイプの詳細については「intra-mart Accel Platform に含まれるリソースタイプ 」を参照してください。

リソースのキャッシュコントローラの定義

リソースの情報が頻繁に利用されることが予想される場合、適切なキャッシュを行うことでパフォーマンスを改善することができます。キャッシュを行うためのコントローラクラスを実装することで、リソースタイプごとに異なる戦略でキャッシュを実装することができます。コントローラクラスを定義するためには ResourceTypeCacheController インタフェースを実装したクラスを作成する必要があります。

リソースのコントローラクラスは以下のクラスを実装します。

完全修飾クラス名
jp.co.intra_mart.foundation.authz.services.admin.impl.cache.ResourceTypeCacheController

リソースのキャッシュコントローラの追加にあたっては別途 「認可拡張プログラミングガイド」の「リソース拡張ガイド」の章 で手順や必要な準備について解説しています。 リソースのキャッシュコントローラを追加する際にはこちらも参照してください。

intra-mart Accel Platform の標準的なモジュール構成においてデフォルトでインストールされるキャッシュコントローラは、intra-mart Accel Platform に含まれるリソースタイプ の「画面・処理(service)」のリソースタイプに設定されている GeneralServiceResourceTypeCacheController クラスです。

リソースグループセット

リソースグループは階層構造をとっていますが、階層の先頭のリソースグループとその配下のツリーをリソースグループセットと呼称しています。

リソース管理上、リソースグループセット毎に特定の目的をもってツリー構造が構成されています。 特定のリソースグループセットとそのIDは intra-mart Accel Platform で予約されています。新たにリソースグループセットを追加する場合は衝突がないよう注意してください。予約されているリソースグループセットについては「予約されているリソースグループセット一覧 」を参照してください。

リソースグループ汎用属性

リソースグループには、システム稼動後に認可リソースを登録する機能が自由に設定可能な汎用属性を設定することができます。

認可機能では以下の機能を実現するために利用しています。
  • リソースの閉塞

コラム

リソースの閉塞については「閉塞」を参照してください。

設定内容は任意の文字列で構成された属性キーと属性値の組み合わせで、マップのように管理することができます。 属性キーは他の機能と重複しないよう、機能を示す固有ID(モジュールID)を接頭子にします。

コラム

リソースグループ汎用属性は intra-mart Accel Platform 2013 Summerより利用可能です。

API

リソース管理に関係する主要なAPI上の操作を説明します。詳細に関してはAPIリストを参照してください。

リソースの管理

マネージャインスタンスの取得

リソース管理の主要な操作を行うためには ResourceManager クラスを使用します。
マネージャクラス、および、ファクトリクラスは以下の通りです。
マネージャクラス
jp.co.intra_mart.foundation.authz.services.admin.ResourceManager
マネージャファクトリ
jp.co.intra_mart.foundation.authz.services.admin.ResourceManagerFactory

マネージャインスタンスはファクトリクラスを使用して取得します。ファクトリも自身のファクトリメソッドを持っていますので、以下のようにして取得します。

// マネージャインスタンスの取得
final ResourceManager resourceManager = ResourceManagerFactory.getInstance().getResourceManager();

リソースとリソースグループの登録

すでに説明した通り、APIでリソースを登録するとリソースグループがセットで追加されます。このため、概念上はリソースは必ずしもツリーの末端になるわけではありません。

リソースグループのツリーの中に、リソースURIを持つノードが存在することになります。ただし、認可要求はリソースURIを使用してしか行えない点に注意してください。

以下にリソースとリソースグループの構成を登録する例を示します。

// トップとなるリソースグループを登録
final I18nValue<String> topGroupName = new I18nValue<String>(Locale.JAPANESE, "トップグループ");
final I18nValue<String> topGroupDesc = new I18nValue<String>(Locale.JAPANESE, "1段目のグループです。");
final ResourceGroup topGroup = resourceManager.registerResourceGroup("top-group-id", topGroupName, topGroupDesc);

// 中間リソースグループを登録
final I18nValue<String> subGroupName = new I18nValue<String>(Locale.JAPANESE, "中間グループ");
final I18nValue<String> subGroupDesc = new I18nValue<String>(Locale.JAPANESE, "2段目のグループです。");
final ResourceGroup subGroup = resourceManager.registerSubGroup("sub-group-id", topGroup, subGroupName, subGroupDesc);

// 中間リソースの配下にリソースを登録
// 登録の結果の戻り値はリソースグループです。
final I18nValue<String> resourceName = new I18nValue<String>(Locale.JAPANESE, "中間グループ");
final I18nValue<String> resourceDesc = new I18nValue<String>(Locale.JAPANESE, "2段目のグループです。");
final ResourceGroup resource = resourceManager.registerAsResource("service://sample/sample_path", resourceName, resourceDesc, "sample-id", subGroup);

リソースグループの取得

リソースグループはIDによる取得のほか、リソースに当たるリソースグループの場合URIで取得することができます。

// IDによるリソースグループの取得
final ResourceGroup groupA = resourceManager.getResourceGroup(topGroup.getResourceGroupId());

// URIによるリソースにあたるグループの取得
final ResourceGroup groupB = resourceManager.getResourceGroupByUri("service://sample/sample_path");

リソースグループの名称、説明の更新

リソースグループに対して名称と説明を更新できます。

// 名称の更新
final I18nValue<String> name = new I18nValue<String>(Locale.JAPANESE, "トップグループ");
name.put(Locale.ENGLISH, "Top Group");
resourceManager.setResourceGroupNames("top-group-id", name);

// 説明の更新
final I18nValue<String> desc = new I18nValue<String>(Locale.JAPANESE, "1段目のグループです。");
desc.put(Locale.ENGLISH, "Top level of groups");
resourceManager.setResourceGroupDescriptions("top-group-id", desc);

リソースグループの削除

リソースに当たるリソースグループを削除すると、リソースも削除されます。

// リソースグループがリソースにあたるグループだった場合、リソースも削除されます。
resourceManager.removeResourceGroup(resource);

// 削除するリソースグループに配下がある場合、それらも削除されます。
resourceManager.removeResourceGroup("top-group-id");

リソースグループ汎用属性の管理

マネージャインスタンスの取得

リソースグループ汎用属性の操作を行うためには ResourceAttributeManager クラスを使用します。
マネージャクラス、および、ファクトリクラスは以下の通りです。
マネージャクラス
jp.co.intra_mart.foundation.authz.services.admin.ResourceAttributeManager
マネージャファクトリ
jp.co.intra_mart.foundation.authz.services.admin.ResourceAttributeManagerFactory

マネージャインスタンスはファクトリクラスを使用して取得します。ファクトリも自身のファクトリメソッドを持っていますので、以下のようにして取得します。

// マネージャインスタンスの取得
final ResourceAttributeManager resourceAttributeManager = ResourceAttributeManagerFactory.getInstance().getResourceAttributeManager();

使い方の詳細についてはAPIリストを参照してください。

閉塞の管理

閉塞状態の管理は「リソースグループ汎用属性」を利用しますが、閉塞状態の管理するAPIとして「ResourceBlocker」を提供しています。 閉塞状態の管理は ResourceAttributeManager ではなく、ResourceBlocker を利用します。

コラム

リソースの閉塞については「閉塞」を参照してください。

コラム

ResourceBlockerは intra-mart Accel Platform 2013 Winterより利用可能です。

マネージャインスタンスの取得

マネージャクラス、および、ファクトリクラスは以下の通りです。

マネージャクラス
jp.co.intra_mart.foundation.authz.services.admin.block.ResourceBlocker
マネージャファクトリ
jp.co.intra_mart.foundation.authz.services.admin.block.ResourceBlockerFactory

マネージャインスタンスはファクトリクラスを使用して取得します。ファクトリも自身のファクトリメソッドを持っていますので、以下のようにして取得します。

// マネージャインスタンスの取得
final ResourceBlocker resourceBlocker = ResourceBlockerFactory.getInstance().getResourceBlocker();

閉塞設定

指定したリソースグループとその配下のすべてのリソースグループに対して閉塞設定を行います。
アクションを指定しての閉塞
閉塞を行うリソースグループのID、リソースタイプとアクションを指定して閉塞を行います。
指定したリソースグループ、および、配下のリソースグループの特定のアクションが閉塞されていた場合、指定したアクションがそのリソースグループが閉塞を行うアクションの一つとして追加されます。
// メニューグループの「参照」アクションを閉塞
resourceBlocker.block("im-menu-group-cat-im_global_nav_pc", "im-menu-group", "read");
リソースグループ自体の閉塞
閉塞を行うリソースグループのIDを指定して閉塞を行います。
指定したリソースグループ、および、配下のリソースグループの特定のアクションが閉塞されていた場合、そのリソースグループ自体を閉塞する状態として更新されます。
// リソースグループ自体の閉塞
resourceBlocker.block("im-menu-group-cat-im_global_nav_pc");

閉塞設定の解除

指定したリソースグループとその配下のすべてのリソースグループに対して閉塞状態の解除を行います。
アクションを指定しての閉塞解除
閉塞を行うリソースグループのID、リソースタイプとアクションを指定して閉塞解除を行います。
指定したリソースグループ、および、配下のリソースグループの特定のアクションが閉塞されていた場合、指定したアクションがそのリソースグループが閉塞を行うアクションから削除されます。
リソースグループ自体が閉塞されている場合、閉塞状態が維持されます。
// メニューグループの「参照」アクションの閉塞を解除
resourceBlocker.unblock("im-menu-group-cat-im_global_nav_pc", "im-menu-group", "read");
リソースグループ自体の閉塞解除
閉塞を行うリソースグループのIDを指定して閉塞を行います。
指定したリソースグループ、および、配下のリソースグループの特定のアクションが閉塞されていた場合も、その閉塞状態が解除されます。
// リソースグループの閉塞の解除
resourceBlocker.unblock("im-menu-group-cat-im_global_nav_pc");

閉塞状態の取得

アクションを指定しての閉塞確認

指定したリソースグループがアクションに対して閉塞されているかどうかを取得できます。

// メニューグループの「参照」アクションが閉塞されているかどうか
resourceBlocker.isBlock("im-menu-group-cat-im_global_nav_pc", "im-menu-group", "read");
リソースグループ自体の閉塞確認

指定したリソースグループ自体が閉塞されているかどうかを取得できます。

// リソースグループ自体が閉塞されているかどうか
resourceBlocker.isBlock("im-menu-group-cat-im_global_nav_pc");

ERとテーブル上の表現

リソース管理に関係するテーブルのERを以下に示します。

../../../_images/ER_Resource.png

ここではAPI上のモデルとER上の関連を中心に説明します。テーブルの定義や認可機構全体のERについては別冊のテーブル定義書、ER図を参照してください。

リソースグループ(imaz_resource_group)

主要なフィールド
論理名 物理名
リソースグループID resource_group_id
リソースグループセットID resource_group_set_id
左値 left_value

リソースグループを表します。

リソースグループIDはシステムで一意なIDを持ちます。

リソースグループは階層構造を持つことができ、特定のトップ配下のツリーをリソースグループセットという単位で管理しています。このセットを示すのがリソースセットIDです。リソースグループの階層構造のトップにあたるリソースグループはリソースグループIDとリソースグループセットIDが同じ値になります。

左値はリソースグループセット内で一意の順序を示す0から始まる整数値です。リソースグループは画面上での表示順を保持しており、その順序を保持する値が左値です。この値はAPIによって自動的にコントロールされます。あくまで表示上の順序なので、リソースグループツリーの根から葉全体に対して連番が振られる形になっています。簡単な例を以下に示します。

../../../_images/LeftValue.png

リソースグループ内包(imaz_resource_group_inc)

主要なフィールド
論理名 物理名
リソースグループID resource_group_id
子リソースグループID child_resource_group_set_id
リソースグループセットID resource_group_set_id
深さ depth

セット内における親子関係のすべてを保持します。簡単な例を以下に示します。

../../../_images/Inclusion.png

リソースグループ国際化(imaz_resource_group_i)

主要なフィールド
論理名 物理名
リソースグループID resource_group_id
ロケールID locale_id
表示名 diaplay_name
説明 description

リソースグループに対して表示名と説明を保持します。それぞれ各ローケルに対して保持することができます。

リソースグループセット(imaz_resource_group_set)

主要なフィールド
論理名 物理名
リソースグループセットID resource_group_set_id

リソースグループは階層構造を持つことができ、特定のトップ配下のツリー一式をリソースグループセットと定義しています。このセットを示すのためのIDがリソースグループセットIDです。この値は原則トップのリソースグループのリソースグループIDと同じ値です。

リソース(imaz_resource)

主要なフィールド
論理名 物理名
リソースID resource_id
URI uri
リソースタイプ resource_type

リソースを表すテーブルです。リソースの登録・削除に応じて追加・削除されます。リソースIDはURIのハッシュ値から生成される値のため、任意の値に設定することはできません。リソースタイプはこのリソースを取り扱うリソースタイプのIDです。

リソースグループ所属(imaz_resource_group_ath)

主要なフィールド
論理名 物理名
リソースID resource_id
リソースグループID resource_group_id
リソースグループセットID resource_group_set_id

リソースとリソースグループの関連を示します。リソースを作成すると対になるリソースグループが作成されるため、リソースが登録されるタイミングで登録されます。リソースに対応するリソースグループを削除するとリソースも連動して削除されるので、リソースグループ所属も合わせて削除されます。

リソースタイプ参照テーブル(imaz_resource_type_ref)

主要なフィールド
論理名 物理名
リソースタイプ resource_type
アクション action

登録されているリソースタイプと、リソースタイプが定義しているアクションをデータベース上で取り扱うためのテーブルです。このテーブルの情報は起動時か、最初にResourceManagerを使用するタイミングでリソースタイプの設定情報をもとに自動的に作成されます。

このテーブルの情報は認可設定画面でアクションを適切に提示するために使用しています。

リソースグループ汎用属性テーブル(imaz_resource_group_attr)

主要なフィールド
論理名 物理名
リソースグループID resource_group_id
属性キー attr_key
属性値 attr_value

リソースグループに紐付ける汎用的な属性を取り扱うためのテーブルです。認可にリソースグループを登録した後、任意のキーで属性値を付加することができます。