diff --git a/website/translated_docs/ja/plugin-developer/Personium_AuthenticationPluginDeveloperManual.md b/website/translated_docs/ja/plugin-developer/Personium_AuthenticationPluginDeveloperManual.md index acc9ed91..9016c4d8 100644 --- a/website/translated_docs/ja/plugin-developer/Personium_AuthenticationPluginDeveloperManual.md +++ b/website/translated_docs/ja/plugin-developer/Personium_AuthenticationPluginDeveloperManual.md @@ -12,84 +12,115 @@ Personiumの認証Pluginを開発する上で必要となる情報を記述し 認証Pluginの詳細は[認証Pluginのセットアップ](../server-operator/setup_authentication_plugins.md)をご参照ください。 このドキュメントでは、認証Pluginの作成手順を説明します。 -## 開発の方法 +## 認証Pluginの概要 -具体的にはPluginでは以下の3点を定義します。 +本章では、認証Pluginの概要を説明します。 -1. どのようなアカウントType値に対応すべきなのか -1. どのようなgrant_type値に対応すべきなのか -1. トークンエンドポイントのgrant_type以外の入力パラメタ値をどのように評価して、結果としてどのような主体として認識すべきなのか +### クラス構造 -即ちPlugin作者は、上記3点の情報を具体的なJavaコードとして実装します。 -Personiumでは認証Pluginが上記3の応答として返却した認証済み識別主体情報(AuthenticatedIdentityオブジェクト)を以下の観点でさらに評価して、 -トークン発行の可否判断や、発行トークンの内容決定、トークン発行処理を行います。 +google版の認証Pluginを例に認証Pluginのクラス構造図を以下に示します。 -- getAccountName() で取得できる文字列をName属性にもつAccountが存在するか -- 存在する場合、ヒットしたAccountのtype値に上記1の文字列が含まれているか +![クラス構造図](assets/plugin_01.png "Pluginクラス構造図") -## セキュリティ上の配慮 +> **注意:** 認証処理の戻り値 +> - 認証に成功した場合は、AuthenticatedIdentityが返却されます。 +> - 認証に失敗した場合は、PluginExceptionまたはnullが返却されます。 -当然のことながら、Plugin作者は上記2の「パラメタ値評価」においては一般的にアクセス主体が適切な認証プロセスを経るように実装を行う必要があります。 -例えば、入力値を一切チェックせずに本来保護されるべき特定の主体(ゲスト等でない実在の人物など) -として認識してしまうようなPluginを作成し、これをUnitに配置してしまうことは重大なセキュリティ問題を引き起こします。 -従ってPlugin作者はセキュアな実装を行うこと、Plugin利用者(Unit管理者)はセキュアであると信じられるPluginのみを用いることが必要です。 +### 動作概要 ---- +google版の認証Pluginを例に、認証PluginがPersoniumCoreApplicationによってどのようにロードされ認証プロセスが呼び出されるのかを示します。 -以下、google版の認証Pluginを例に説明します。 +![Pluginの動作](assets/plugin_02.png "pluginの動作") -## Pluginのクラス構造 +1. Plugin初期化処理 + PersoniumCoreApplicationクラスでPluginManagerが呼出され、すべてのPluginを読み込みます。 -作成Pluginの枠線部分が作成の対象です。 +2. 認証Pluginの選択 + TokenEndPointResourceクラスで指定されたのGrantTypeのPluginを選択します。 -認証Pluginのクラス構造図を以下に示します。 -![クラス構造図](assets/plugin_02.png "Pluginクラス構造図") +3. 認証プロセスの呼び出し + 選択されたPluginのauthenticateメソッドを実行して認証処理を行います。 -> **注意:** 認証処理の戻り値 -> - 認証に成功した場合は、AuthenticatedIdentityが返却されます。 -> - 認証に失敗した場合は、PluginExceptionまたはnullが返却されます。 +### 認証結果の取り扱い + +認証Pluginのauthenticateメソッドは、TokenEndpointResourceから渡されたパラメタの評価を行い、認証されたアクセス主体を認証済み識別主体情報(AuthenticatedIdentityオブジェクト)として返却します。 + +PersoniumではAuthenticatedIdentityオブジェクトを以下の観点で評価して、トークン発行の可否判断や、発行トークンの内容決定、トークン発行処理を行います。 + +- getAccountName()で取得できる文字列をName属性にもつAccountが存在するか +- 存在する場合、getAccountType()で取得できる文字列が、ヒットしたAccountのAccountType値に含まれているか + +### セキュリティ上の配慮 + +認証Plugin作者はTokenEndpointResourceから与えられたパラメタの評価において、アクセス主体が適切な認証プロセスを経るように実装を行う必要があります。 +例えば、入力値を一切チェックせずに本来保護されるべき特定の主体(ゲスト等でない実在の人物など)として認識してしまうような認証Pluginを作成し、これをUnitに配置してしまうことは重大なセキュリティ問題を引き起こします。 +従って認証Plugin作者はセキュアな実装を行うこと、認証Plugin利用者(Unit管理者)はセキュアであると信じられる認証Pluginのみを用いることが必要です。 + +## 開発の方法 + +Pluginでは以下の3点を定義します。 + +1. どのような`AccountType`値に対応すべきか +1. どのような`grant_type`値に対応すべきか +1. パラメタ値をどのように評価して、結果としてどのような主体として認識すべきか + +上記3点の情報を決定したのち、`io.personium.plugin.base.auth.AuthPlugin`インタフェースを実装したクラスとして実装します。 + +### AuthPluginインタフェース + +認証PluginはAuthPluginインタフェースを実装し、以下のメソッドを実装してください。 + +- getType() + PluginのTypeを返す。認証Pluginは`auth`を返す。 +- getGrantType() + 対応するgrant_type値を返す。 +- getAccountType() + 対応するAccountのType値を返す。 +- authenticate() + 認証処理を行う。認証結果はAuthenticatedIdentityオブジェクトとして返却する。 -## Pluginの動作 +## パッケージング・配置 -認証Pluginの動作を以下に示します。 +実装したクラスは以下の仕様に従ってjarファイルを作成し、[Unit設定](../server-operator/unit_config_list.md)の`plugin.path`で指定されたディレクトリに配置することで、認証Pluginとして利用可能になります。 -![Pluginの動作](assets/plugin_01.png "pluginの動作") +### jarファイル仕様 - 1. Plugin初期化処理 -  PersoniumCoreApplicationクラスでPluginManagerが呼出され、すべてのPluginを読み込みます。 +jarファイルには、実装したクラスの他に以下の属性を持つマニフェストを同梱します。 - 2. 認証プロセスの呼び出し -  TokenEndPointResourceクラスで対象のGrantTypeのPluginを選択します。 -  選択したPluginのauthenticateメソッドを実行します。 +#### Plugin-Class属性 -> **注意:** -> - PersoniumPluginは、pluginsフォルダに配置するだけで実行可能です。 -> - 認証Pluginは、Typeに”auth”とGrantTypeに各プロバイダを指定し、authenticateメソッドを記述することで、対象のpluginが選択されauthenticateメソッドが実行されます。 +ロードするクラスを以下の例のように指定してください。 +``` +Plugin-Class: io.personium.plugin.auth.sample.SampleAuthPlugin +``` -### 1.Plugin初期化処理 -#### [PersoniumCoreApplication.java](https://github.com/personium/personium-core/blob/master/src/main/java/io/personium/core/rs/PersoniumCoreApplication.java) -pm = new PluginManager(); -PluginManagerクラスを生成します。 +この際、指定できるクラスは以下の2種類です。 + +- 認証Plugin本体 + - 上記仕様に従って実装されたプラグインクラス + - インタフェース`io.personium.plugin.base.auth.AuthPlugin`を実装したクラス +- 認証Pluginを初期化するクラス + - 上記仕様に従って実装されたプラグインクラスの初期化方法を定め、インスタンス化するクラス + - インタフェース`io.personium.plugin.base.auth.AuthPluginLoader`を実装したクラス + +**AuthPluginLoaderについて** + +Plugin-Class属性に「認証Plugin本体」を指定した場合、クラスのデフォルトコンストラクタが呼ばれインスタンス化されますが、 +同一クラスを複数のパラメタで初期化して使用するケースではAuthPluginLoaderインタフェースを実装したクラスを指定してください。 + +AuthPluginLoaderを実装するクラスには以下のメソッドを実装してください。 + +- loadInstances() + プラグインクラスのインスタンス化を行う。AuthPluginのインスタンスのListを返却する。 -### 2.認証プロセスの呼び出し -#### [TokenEndPointResource.java](https://github.com/personium/personium-core/blob/master/src/main/java/io/personium/core/rs/cell/TokenEndPointResource.java) -callAuthPlugins()メソッドで認証プロセスを呼び出しています。 --- ## サンプル実装 -- [personium-plugin-sample](https://github.com/personium/personium-plugin-sample) +以下にサンプル実装を示します。 -最低限実装すべきメソッドは以下です。 -- getType() - - PluginのTypeを返す。現状は"auth"のみ。 -- getGrantType() - - 対応するgrant_type値を返す。 -- getAccountType() - - 対応するAccountのType値を返す。 -- authenticate() - - 認証処理。 +- [personium-plugin-sample](https://github.com/personium/personium-plugin-sample) -## Pluginの作成手順 +## Pluginのセットアップ手順 -[認証Pluginのセットアップ](../server-operator/setup_authentication_plugins.md)をご参照ください。 +- [認証Pluginのセットアップ](../server-operator/setup_authentication_plugins.md)をご参照ください。 diff --git a/website/translated_docs/ja/server-operator/unit_config_list.md b/website/translated_docs/ja/server-operator/unit_config_list.md index 5465abdd..ba6c8293 100644 --- a/website/translated_docs/ja/server-operator/unit_config_list.md +++ b/website/translated_docs/ja/server-operator/unit_config_list.md @@ -23,8 +23,13 @@ io.personium.configurationFile={ファイル名まで含めたPath} personium-unit-config.propertiesが正しく読み取られたかどうかを確認するには、起動ログをご確認ください。 -#### Unit設定ファイルのキー名について -すべてのキーは、以下のキープレフィックスを持ちます。 +## コア設定 + +Unitの基本設定を行います。 + +### コア設定のキー名について + +コア設定のキーは、以下のプレフィックスを持ちます。 ``` io.personium.core. ``` @@ -212,7 +217,7 @@ http://{engine.host}:{engine.port}/{engine.path} #### OpenID Connect |キー|説明|値|デフォルト値|使用コンポーネント|備考| |:--|:--|:--|:--|:--|:--| -|oidc.google.trustedClientIds|Google OpenID Connectにおいて、このUnitが信頼するClientID
スペース区切りで複数指定可能|文字列|*|core|"*"を指定した場合全てのClientIDを信頼する
将来的にPlugin独自設定として移動予定| +|oidc.google.trustedClientIds|Google OpenID Connectにおいて、このUnitが信頼するClientID
スペース区切りで複数指定可能|文字列|*|core|v1.7.22以前。"*"を指定した場合全てのClientIDを信頼する
v1.7.23以降はプラグイン設定に移動| #### CellSnapshot |キー|説明|値|デフォルト値|使用コンポーネント|備考| @@ -248,3 +253,28 @@ http://{engine.host}:{engine.port}/{engine.path} |:--|:--|:--|:--|:--|:--| |introspect.username|ユーザ名|文字列||core|Resource ServerからToken Introspectionにアクセスする際のBasic認証用
v1.7.4以降| |introspect.password|パスワード|文字列||core|Resource ServerからToken Introspectionにアクセスする際のBasic認証用
v1.7.4以降| + +## プラグイン設定 + +Unitのプラグインの設定を行います。 + +### プラグイン設定のキー名について + +プラグイン設定のキーは、以下のプレフィックスを持ちます。 +``` +io.personium.plugin. +``` + +### OpenID Connect認証連携設定 + +OpenID Connect認証連携プラグイン(以下、OIDC認証連携プラグイン)は複数のconfigIdを定義することで複数のID Providerに対応することができます。分けたい設定ごとに`[configId]`を読み替えて記述してください。 + +|キー|説明|値|記載例|備考| +|:--|:--|:--|:--|:--| +|oidc.[configId].enabled|当該configIdで指定されたOIDC認証連携プラグインの設定を有効にするフラグ|boolean|true|v1.7.23以降| +|oidc.[configId].pluginName|OIDC認証連携プラグインを識別するための名前|文字列|Google OpenID Connect auth|v1.7.23以降。
同一configIdにのみ適用| +|oidc.[configId].configURL|OIDC認証連携プラグインが参照する設定用URL|文字列|https://accounts.google.com/.well-known/openid-configuration|v1.7.23以降。ID Providerから提供されるURLを指定する。OpenID Connect Discovery 1.0に対応。
同一configIdにのみ適用| +|oidc.[configId].trustedClientIds|OIDC認証連携プラグインが信頼するClientID
スペース区切りで複数指定可能|文字列|*|v1.7.23以降。"*"を指定した場合全てのClientIDを信頼する。
同一configIdにのみ適用| +|oidc.[configId].accountType|OIDC認証連携プラグインが認証した結果、返却されるaccountType|文字列|oidc:google|v1.7.23以降
同一configIdにのみ適用| +|oidc.[configId].accountNameKey|OIDC認証連携プラグインがアカウント名として参照するClaimsのキー|文字列|email|v1.7.23以降。
同一configIdにのみ適用| +|oidc.[configId].grantType|OIDC認証連携プラグインが対応付けされるgrantType|文字列|urn:x-personium:oidc:google|v1.7.23以降。
同一configIdにのみ適用|