1.7.21

Unitユーザ

Unitユーザとは

CellのCRUD等ユニットレベルのAPIを操作する主体のことをUnitユーザと呼びます

Personium Unitは外部のUnitユーザ管理機構の存在を前提としており、 特段Unitユーザの管理機構を持っていません。一方で、一つまたは複数のCellを特別なUnit管理Cellとして使ってUnitユーザの管理機構に充てることも可能となっています。

ユニットレベルのアクセス制御モデル

Cellの生成・削除にかかわるユニットレベルのAPIもアクセス主体を識別するためにOAuth 2.0のBearerトークン送信を使って保護されたAPIにアクセスするという点は全く同じです。つまりアクセス主体は取得したトークンを以下のようにHTTPのAuthorizationヘッダで送信することで、自身を証明し識別させます。

Authorization: Bearer unitLevelAccessToken

一方でユニットレベルのAPIとそれを操作するUnitユーザのアクセス制御のモデルは、一般のCellで認証されたユーザの自Cellや他Cellへのアクセス制御のモデルとは全く異なります。

ユニットレベルのAPIが認識するトークンは以下の2種類です。

  • Unitユーザトークン（Unit User Token (UUT)）
  • ユニットマスタートークン（Unit Master Token (UMT)）

これらトークンでのアクセス時にはCellレベルのACLは全く考慮されません。またCellレベルのAPIアクセスでのトランスセルトークンのように他のユニットにまたがったようなアクセスもできません。

ユニットマスタートークン（Unit Master Token (UMT)）

ユニットマスタートークンはユニットに設定したそのままの値がトークンになるというシンプルな使い方で設定でき、そのトークンでユニットに関するあらゆる操作ができるというきわめて強い権限を持ったトークンです。

このトークンは開発やテストの時に使うことを想定したものであり、特殊なケースを除き多くの場合本番運用ではセキュリティ的観点から無効化すべきものです。

設定の方法

personium-unit-config.propertiesの「io.personium.core.masterToken=」に任意の文字列を設定することでそれがマスタートークンとして認識されます。デフォルトの設定では無効となっていますが、空文字列を設定することでも設定の無効化となります。

Unitユーザトークン（Unit User Token (UUT)）

UUTは以下の情報をつめたSAML Assertionに基づくOAuth2のBearerトークンです。

要素・属性名内容
IssueInstant認証した時刻
issuerユニットが認めたURL。
personium-unit-config.propertiesの「io.personium.core.unitUser.issuers=」に認める任意のURLを記述
Subject\NameIDUnitユーザ名。任意の文字列。
audienceユニットルートURL
attributeUnit User Role

このトークンを発行されたアクセス主体をUnitユーザとよび、このようなSAMLアサーションを発行する認証プロセスをUnitユーザ認証と呼びます。

また、CellでのAccount認証でp_targetにユニットのルートURLを与えることで発行されるトランスセルトークンは、UUTの要件を満たしており、 ユニットの設定に特定のCellのURLを含めることでそのCellはUUT発行者となりうる。

例
CellでUUTを発行する場合
personium-unit-config.propertiesのio.personium.core.unitUser.issuers={UnitURL}/{Cell}/を設定

curl "{UnitURL}/{Cell}/__token" -X POST \
-d 'grant_type=password&username=user&password=pass&p_target={UnitURL}/'
  • io.personium.core.unitUser.issuers は複数URL設定可能です。
  • UUTは通常、CellのCRUD以外のアクセス権限を持っていません。
  • Cellの内容を操作したい場合、後述のUnitユーザロール(CellContentsReader, CellContentsAdmin)を付与する必要があります。

Unitユーザの種類

ユニットアドミン（Unit Admin）

ユニット全体に対して操作が可能なUnitユーザを特にユニットアドミンと呼びます。ユニットマスタートークンでのアクセスや、後述するUnitAdminロールのついたUUTでのアクセスはユニットアドミンとなります。

  • Cell検索時、そのユニット上のすべてのCellが対象になる
  • そのユニット上のすべてのCellに対して削除が可能。
  • X-Personium-Unit-Userヘッダに任意の文字列を指定することで、その文字列をUnitユーザ名とするUnitユーザとして動くことも可能です。

例

{UnitURL}/{UnitUserName} というUnitユーザ名をオーナーとするCell作成

curl "{UnitURL}/__ctl/Cell" -X POST \
-H "Authorization: Bearer token" \
-H "X-Personium-Unit-User: {UnitURL}/{UnitUserName}" \
-d '{"Name":"cell1"}'

{UnitURL}/{UnitUserName} というUnitユーザ名をオーナーとするCell一覧を取得

curl "{UnitURL}/__ctl/Cell" -X GET \
-H "Authorization: Bearer token" \
-H "X-Personium-Unit-User: {UnitURL}/{UnitUserName}"

Unitユーザ（Unit User）

オーナーが一致するCellに対して操作が可能なユーザ。 Cellの検索を実施するとオーナーが一致するCellのみが検索されます。

・Cell作成時、自身が持ち主であるという情報とともにCellが作成される。
・Cell検索時、自身が作成したCell以外は検索されない。
・Cell削除時、自身が作成したCell以外の削除は失敗する。

unituser

ユニットレベル制御エンティティ（Cell）のオーナー属性

Cellにはオーナー（owner）という隠し属性が存在します。 オーナーはCell作成時に設定したら変更は行えない。

Unitユーザロール（Unit User Role）

PersoniumのユニットはUnitユーザトークン内のattribute要素の値として特定の文字列が設定されていたとき、これをUnitユーザのロールとして認識します。これをUnitユーザロールと呼びます。（その他の文字列が設定されていたとしてもこれを認識はせず無視します。）

なお、Unit管理用のCellを作成してこれをUnitユーザトークン発行元として登録して用いたときは、Boxに紐づけないロールとしてこれらロールを作成してアカウントと紐づけることで、UnitユーザロールのついたUnitユーザトークンを発行可能です。

Unitユーザロールには以下のものがあります。

UnitAdminロール

{UnitUserName}/__role/__/UnitAdmin

UnitAdminロールが付与されている場合、そのユーザはユニットアドミンとなります。
各種Unit管理業務は、このロールのトークンを用いてAPI呼び出しを行うべきです。

CellContentsReaderロール

{UnitUserName}/__role/__/CellContentsReader

CellContentsReaderロールが付与されている場合、そのユーザのUnitユーザトークンはCellの内容のRead権限を持ちます。内容参照しか行わずデータの登録や書き換えにつながる処理を実行することはできません。

CellContentsAdminロール

{UnitUserName}/__role/__/CellContentsAdmin

CellContentsAdminロールが付与されている場合、そのユーザのUnitユーザトークンはCellの内容の全権限を持ちます。 Unitユーザに"UnitAdminロール"、及び"CellContentsAdminロール"を付与することで、そのユーザのUnitユーザトークンはユニットマスタートークンと同等の権限を持つこととなります。

Version 1.6.3 以前の仕様

Unitユーザロールについて

  • Version 1.6.3 以前で唯一存在したunitAdminロールの先頭文字は小文字です。以下文字列が有効となります。

    {UnitUserName}/__role/__/unitAdmin

  • CellContentsReaderロール、CellContentsAdminロールは存在しません。

  • Unitユーザは特に何もUnitユーザロールがなくても自身の作成したCellに対してはすべての権限を持ちます。（CellContentsAdminロール相当）

  • ユニットアドミンはユニット上のすべてのCellに対してすべての権限を持ちます。

X-Personium-Unit-Userヘッダの制限

  • ユニットマスタートークン使用時以外はX-Personium-Unit-Userヘッダは有効ではありません。
  • unitAdminロールが付与されたトークンでのアクセス時もX-Personium-Unit-Userヘッダは有効ではありません。
← Unit管理者向けガイドデータの管理 →