代行承認
代行承認の使用法
InterSystems IRIS® データ・プラットフォームでは、ユーザ定義の承認コードの使用がサポートされています。このメカニズムを、代行承認といいます。
代行承認の概要
管理者は、代行承認により、インターシステムズのセキュリティの一部であるロール割り当ての動作に代わるカスタムのメカニズムを導入できます。例えば、ユーザ定義の承認コードが、外部データベースのユーザのロールを検索し、InterSystems IRIS にその情報を提供することができます。
代行承認を使用するには、以下の手順を実行します。
-
ZAUTHORIZE ルーチンで、代行 (ユーザ定義) 承認コードを作成します。
-
InterSystems IRIS インスタンスに対し、代行承認を使用するようインスタンスを構成します。
代行承認は、Kerberos およびオペレーティング・システム・ベースの承認でのみサポートされます。
ZAUTHORIZE.mac による代行承認は、代行認証と組み合わせて使用できません。代行認証のルーチン ("代行認証の使用法" で説明している ZAUTHENTICATE) は、承認をサポートします。ZAUTHENTICATE を使用する場合、認証と承認のコードを分離することもできます。
HealthShare® で認証を使用している場合は、インターシステムズが提供する ZAUTHENTICATE ルーチンOpens in a new tabを使用する必要があります。独自のルーチンは作成できません。
代行 (ユーザ定義) 承認コードの作成
代行承認コードの作成に関連するトピックは、以下のとおりです。
ZAUTHORIZE.mac テンプレートからの開始
インターシステムズが提供するサンプル・ルーチン ZAUTHORIZE.mac をコピーして変更することができます。このルーチンは GitHub の Samples-Security サンプルに含まれています (https://github.com/intersystems/Samples-SecurityOpens in a new tab)。"InterSystems IRIS で使用するサンプルのダウンロード" で説明されているようにサンプル全体をダウンロードすることもできますが、単に GitHub でファイルを開いて、その内容をコピーする方が簡単です。
独自の ZAUTHORIZE.mac を作成するには、以下の手順を実行します。
-
ZAUTHORIZE.mac をテンプレートとして使用するには、その内容を %SYS ネームスペースの ZAUTHORIZE.mac ルーチンにコピーして保存します。
-
ZAUTHORIZE.mac サンプル内のコメントを確認します。そこには、カスタム版のルーチンを実装する方法に関する重要なガイダンスが記載されています。
-
ユーザ・アカウントの特性を設定するには、カスタム承認コードと必要なコードを追加してルーチンを編集します。
InterSystems IRIS では ZAUTHORIZE の承認コードに対する制約を行わないため、アプリケーション・プログラマは、コードが十分に安全であるかどうかを確認する必要があります。
新しいバージョンの InterSystems IRIS にアップグレードする前に、ZAUTHORIZE.mac を確認し、現在の承認コードで新機能をサポートするための変更が必要かどうかを判断してください。
ZAUTHORIZE シグニチャ
代行承認用に構成されると、システムは承認が発生した後、自動的に ZAUTHORIZE を呼び出します。InterSystems IRIS は、必要に応じて ZAUTHORIZE シグニチャで定義されたパラメータの値を提供します。ZAUTHORIZE のシグニチャは以下のとおりです。
ZAUTHORIZE(ServiceName, Namespace, Username, Password,
Credentials, Properties) PUBLIC {
// authorization code
// optional code to specify user account properties and roles
}
以下はその説明です。
-
ServiceName — ユーザから InterSystems IRIS への接続を仲介しているサービスの名前を指定する文字列 (%Service_Console や %Service_WebGateway など)。
-
Namespace — 目的とする接続先の InterSystems IRIS サーバにあるネームスペースを指定する文字列。これは、スタジオや ODBC の接続など、%Service_Bindings のみで使用されます。その他のサービスの場合、この値は "" (引用符で囲んだ空の文字列) とする必要があります。
-
Username — 特権が決定されるユーザを指定する文字列。
-
Password — 使用しているアカウントに関連付けられたパスワードを指定する文字列。これは、Kerberos K5API 認証メカニズムのみで使用されます。その他のメカニズムの場合、この値は "" (引用符で囲んだ空の文字列) とする必要があります。
-
Credentials — 参照渡し。今回のバージョンの InterSystems IRIS では、実装されていません。
-
Properties — 参照渡し。Username で指定したアカウントの特性を指定する返り値の配列。詳細は、"ZAUTHORIZE とユーザ・プロパティ" を参照してください。
ZAUTHORIZE による承認コード
ZAUTHORIZE の目的は、認証されたユーザのロールと他の特性を確立または更新することです。承認コードのコンテンツはアプリケーションに固有です。これには、ユーザが記述した ObjectScript コード、クラス・メソッド、または $ZF コールアウトを含めることができます。
ZAUTHORIZE は、Properties 配列の値を設定することによりロール情報を指定します。この配列は、ZAUTHORIZE に参照渡しされます。通常、設定する値のソースは、ZAUTHORIZE が使用できるユーザ情報のリポジトリです。
InterSystems IRIS では ZAUTHORIZE の承認コードに対する制約を行わないため、アプリケーション・プログラマは、コードが十分に安全であるかどうかを確認する必要があります。
ZAUTHORIZE とユーザ・プロパティ
Properties 配列の要素は、Username パラメータで指定されたユーザに関連付けられた属性の値を指定します。通常、ZAUTHORIZE 内のコードにより、この要素の値が設定されます。Properties 配列の要素は以下のとおりです。
-
Properties("Comment") — 任意のテキスト。
-
Properties("FullName") — ユーザの名前と姓。
-
Properties("NameSpace") — ターミナル・ログインの既定のネームスペース。
-
Properties("Roles") — ユーザが InterSystems IRIS で保持するコンマ区切りのロール・リスト。
-
Properties("Routine") — ターミナル・ログインに対して実行されるルーチン。"" の値は、ターミナルがプログラマ・モードで実行されることを示します。
-
Properties("Password") — ユーザのパスワード。
-
Properties("Username") — ユーザのユーザ名。
各要素については、この後のセクションでそれぞれ詳しく説明します。
承認後に Properties 配列のメンバの値を操作することはできません。
ZAUTHORIZE が Properties("Comment") の値を返すと、その文字列が InterSystems IRIS におけるユーザ・アカウントの Comment プロパティの値になります(このプロパティは、"ユーザ・アカウントのプロパティ" で説明しています)。呼び出し元のルーチンに値が渡されない場合、ユーザ・アカウントの Comment の値は NULL 文字列になり、管理ポータルの関連フィールドにはコンテンツが表示されません。
ZAUTHORIZE が Properties("FullName") の値を返すと、その文字列が InterSystems IRIS におけるユーザ・アカウントの Full name プロパティの値になります(このプロパティは、"ユーザ・アカウントのプロパティ" で説明しています)。呼び出し元のルーチンに値が渡されない場合、ユーザ・アカウントの Full name の値は NULL 文字列になり、管理ポータルの関連フィールドにはコンテンツが表示されません。
ZAUTHORIZE で Properties("Namespace") の値を設定すると、その文字列が InterSystems IRIS におけるユーザ・アカウントの Startup Namespace プロパティの値になります(このプロパティは、"ユーザ・アカウントのプロパティ" で説明しています)。呼び出し元のルーチンに値が渡されない場合、ユーザ・アカウントの Startup Namespace の値は NULL 文字列になり、管理ポータルの関連フィールドにはコンテンツが表示されません。
InterSystems IRIS に接続すると、Startup Namespace の値 (Properties("Namespace") の値で指定されたもの) は、ローカル・アクセス (コンソール、ターミナル、Telnet など) に認証されたユーザの最初のネームスペースを決定します。Startup Namespace に値が指定されない場合、ローカル・アクセスに認証されたユーザの最初のネームスペースは以下のように決定されます。
-
USER ネームスペースが存在する場合、これが最初のネームスペースになります。
-
USER ネームスペースが存在しない場合、最初のネームスペースは %SYS ネームスペースになります。
ユーザが最初のネームスペースに対する適切な特権を保持していない場合、アクセスは拒否されます。
ZAUTHORIZE で Properties("Password") の値を設定すると、その文字列が InterSystems IRIS におけるユーザ・アカウントの Password プロパティの値になります(このプロパティは、"ユーザ・アカウントのプロパティ" で説明しています)。呼び出し元のルーチンに値が渡されない場合、ユーザ・アカウントの Password の値は NULL 文字列になり、管理ポータルの関連フィールドにはコンテンツが表示されません。
ZAUTHORIZE がパスワードを返す場合、パスワード認証が有効であれば、システムにログインできます。これは、代行認証からパスワード認証への移行を支援するために使用可能なメカニズムですが、複数の認証メカニズムを使用する点に関して通常と同じように注意が必要です。詳細は、"カスケード認証" を参照してください。
ZAUTHORIZE で Properties("Roles") の値を設定すると、その文字列によってユーザの割り当て先の Roles が指定されます。この値はコンマ区切りのロール・リストを含む文字列です。呼び出し元のルーチンに値が渡されない場合、ユーザ・アカウントに関連付けられたロールはありません。これは、管理ポータルに示されます。ユーザのロールに関する情報は、[ユーザ編集] ページの [ロール] タブおよびユーザのプロファイルで確認できます。
Properties("Roles") で返されるロールが定義されない場合、ユーザはロールに割り当てられません。
したがって、ログインしたユーザは以下のようにロールに割り当てられます。
-
ロールが Properties("Roles") に示され、InterSystems IRIS インスタンスで定義される場合、ユーザはそのロールに割り当てられます。
-
ロールが Properties("Roles") に示され、InterSystems IRIS インスタンスで定義されない場合、ユーザはそのロールに割り当てられません。
-
ユーザは、_PUBLIC ユーザに関連付けられたロールには常に割り当てられます。また、すべてのパブリック・リソースにアクセスできます。_PUBLIC ユーザの詳細は、"_PUBLIC アカウント" を参照してください。パブリック・リソースの詳細は、"サービスとそのリソース" を参照してください。
ZAUTHORIZE で Properties("Routine") の値を設定すると、その文字列が InterSystems IRIS におけるユーザ・アカウントの Startup Tag^Routine プロパティの値になります(このプロパティは、"ユーザ・アカウントのプロパティ" で説明しています)。呼び出し元のルーチンに値が渡されない場合、ユーザ・アカウントの Startup Tag^Routine の値は NULL 文字列になり、管理ポータルの関連フィールドにはコンテンツが表示されません。
Properties("Routine") に値がある場合、この値によって、ターミナル・タイプのサービス (コンソール、ターミナル、Telnet など) でログイン後に自動的に実行するルーチンが指定されます。Properties("Routine") に値がない、または値が "" の場合、ログインは、プログラマ・モードへのアクセス権の有無に従って、プログラマ・モードでターミナル・セッションを開始します。
ZAUTHORIZE で Properties("Username") の値を設定すると、その文字列が InterSystems IRIS におけるユーザ・アカウントの Name プロパティの値になります(このプロパティは、"ユーザ・アカウントのプロパティ" で説明しています)。これにより、アプリケーション・プログラマは、ログイン・プロンプトでエンドユーザが入力した内容を正規化できます (正規化されたユーザ名は大文字と小文字のみ異なります)。
Properties("Username") の値を呼び出し元のルーチンに渡す明示的な呼び出しがない場合、正規化は行われず、プロンプトでエンドユーザが入力する値が、変更されずに、そのユーザ・アカウントの Name プロパティの値としてそのまま使用されます。
ユーザ情報のリポジトリ
ZAUTHORIZE は、グローバルや外部ファイルなど、ユーザ情報のリポジトリであればどのような種類でも参照できます。認証されたユーザをこの情報で作成または更新できるように、ルーチンのコードによって Properties 配列で外部プロパティを設定します。例えば、あるリポジトリにロールやネームスペースなどの情報が含まれる一方で、ZAUTHORIZE コードは InterSystems IRIS がその情報を利用できるようにする必要があります。
リポジトリ内の情報が変更されると、このアクションを実行するコードが ZAUTHORIZE にある場合、この情報は InterSystems IRIS ユーザ情報に伝播されます。また、このようなコードがある場合、リポジトリでユーザのロールが変更されなければなりません。セッション中にユーザのロールを変更した場合、その変更は次のログインまで有効になりません。次のログインの時点で、そのユーザのロールは ZAUTHORIZE によってリセットされます。
ZAUTHORIZE の返り値とエラー・メッセージ
ルーチンは以下のいずれかの値を返します。
-
成功 — $SYSTEM.Status.OK()。これは、ZAUTHORIZE が正常に実行されたことを示します。ルーチン内のコードにより、Username および Password に関連付けられたユーザ認証の成功、Username に関連付けられたユーザ承認の成功、またはその両方を示します。
-
失敗 — $SYSTEM.Status.Error($$$ERRORMESSAGE)。承認が失敗したことを示します。ZAUTHORIZE がエラー・メッセージを返すと、LoginFailure イベント監査が有効であれば、このメッセージは監査ログに記録されます。エンドユーザには、$SYSTEM.Status.Error($$$AccessDenied) エラー・メッセージのみが表示されます。
ZAUTHORIZE は、システム定義またはアプリケーション固有のエラー・メッセージを返すことができます。これらのメッセージはすべて、%SYSTEM.StatusOpens in a new tab クラスの Error メソッドを使用します。このメソッドは、$SYSTEM.Status.Error として呼び出され、エラーの状況に応じて、1 つまたは 2 つの引数を取ります。
使用可能なシステム定義のエラー・メッセージは以下のとおりです。
-
$SYSTEM.Status.Error($$$AccessDenied) — “アクセスが拒否されました” のエラー・メッセージ
-
$SYSTEM.Status.Error($$$InvalidUsernameOrPassword) — “ユーザ名またはパスワードが無効です” のエラー・メッセージ
-
$SYSTEM.Status.Error($$$UserNotAuthorizedOnSystem,Username) — “ユーザ username は許可されていません” のエラー・メッセージ
-
$SYSTEM.Status.Error($$$UserAccountIsDisabled,Username) — “ユーザ username アカウントが無効です” のエラー・メッセージ
-
$SYSTEM.Status.Error($$$UserInvalidUsernameOrPassword,Username) — “ユーザ username の名前またはパスワードは無効です” のエラー・メッセージ
-
$SYSTEM.Status.Error($$$UserLoginTimeout) — “ログインタイムアウト” のエラー・メッセージ
-
$SYSTEM.Status.Error($$$UserCTRLC) — “ログインは中止されました” のエラー・メッセージ
-
$SYSTEM.Status.Error($$$UserDoesNotExist,Username) — “ユーザ username は存在しません” のエラー・メッセージ
-
$SYSTEM.Status.Error($$$UserInvalid,Username) — “ユーザ名 username が無効です” のエラー・メッセージ
-
$SYSTEM.Status.Error($$$PasswordChangeRequired) — “パスワードの変更が必要です” のエラー・メッセージ
-
$SYSTEM.Status.Error($$$UserAccountIsExpired,Username) — “ユーザ username のアカウントは失効しました” のエラー・メッセージ
-
$SYSTEM.Status.Error($$$UserAccountIsInactive,Username) — “ユーザ username のアカウントはアクティブではありません” のエラー・メッセージ
-
$SYSTEM.Status.Error($$$UserInvalidPassword) — “無効なパスワードです” のエラー・メッセージ
-
$SYSTEM.Status.Error($$$ServiceDisabled,ServiceName) — “サービス username のログインは無効です” のエラー・メッセージ
-
$SYSTEM.Status.Error($$$ServiceLoginsDisabled) — “ログインは無効です” のエラー・メッセージ
-
$SYSTEM.Status.Error($$$ServiceNotAuthorized,ServiceName) — “ユーザはサービスを許可されていません” のエラー・メッセージ
これらのエラー・コードを使用するには、ZAUTHORIZE.mac にある #Include %occErrors 文をアンコメントします。
カスタム・メッセージを生成するには、$SYSTEM.Status.Error() メソッドを使用して、このメソッドに $$$GeneralError マクロを渡し、2 番目の引数として任意のカスタム・テキストを指定します。以下に例を示します。
$SYSTEM.Status.Error($$$GeneralError,"Any text here")
エラー・メッセージが呼び出し元に返されると、そのメッセージは監査データベース (LoginFailure イベント監査が有効な場合) にログとして記録されます。表示されるエラー・メッセージは $SYSTEM.Status.Error($$$AccessDenied) のみです。ただし、$$$PasswordChangeRequired エラーのメッセージも表示されます。現在のパスワードから新しいパスワードへの変更をユーザに要求する場合、このエラーを返します。
代行承認を使用するためのインスタンスの構成
カスタマイズされた ZAUTHORIZE ルーチンを作成したら、次に、インスタンスの関連サービスまたはアプリケーションでそのルーチンを有効にします。手順は以下のとおりです。
-
ターミナルまたはコンソール・ウィンドウの %SYS ネームスペースから、^SECURITY ルーチンを実行します。
-
^SECURITY で [システムパラメータの設定] を選択し、その下で [認証オプション編集] を選択し、さらにその下で [Kerberos認証を許可] または [オペレーティングシステム認証を許可] を選択します(代行承認は、これら 2 つの認証メカニズムに対してのみサポートされています)。
-
[オペレーティングシステム認証を許可] を選択した場合、[O/S 認証に代行承認を許可] を選択します。[Kerberos認証を許可] を選択した場合、[Kerberos に代行承認を許可] を選択します。
これらのいずれかを選択すると、InterSystems IRIS は %SYS ネームスペースで ZAUTHORIZE.mac ルーチンを起動します (このルーチンが存在する場合)。
InterSystems IRIS が ZAUTHORIZE を呼び出すのは、ユーザ認証後のみです。
代行承認とユーザ・タイプ
代行承認を使用する認証メカニズムでユーザが最初に InterSystems IRIS にログインすると、InterSystems IRIS は OS (オペレーティング・システム) または Kerberos のタイプのユーザ・アカウントを作成します(この値は、[ユーザ] ページ ([システム管理] > [セキュリティ] > [ユーザ]) にあるユーザのテーブルの [タイプ] 列に表示されません。)ZAUTHORIZE ルーチンは、アカウント作成の時点で、その後のログインのため、そのユーザのロールを指定します。
代行承認を使用せずにログインを試みると、ログインは失敗します。これは、代行承認のみがユーザ・タイプを OS または Kerberos として指定するためです。代行承認なしでこれらの認証メカニズムを使用する場合、ユーザはパスワード・ユーザ・タイプとして認証されます。ユーザが持つことのできるタイプは 1 つのみで、あるタイプのユーザは別のタイプに関連付けられたメカニズムを使用してログインすることができないため、ログインは失敗します(代行認証および LDAP 認証も同じ理由で失敗します)。
ユーザ・タイプの一般情報は、"ユーザ・タイプについて" を参照してください。
承認後 — システムの状態
ユーザが正常に承認されると、InterSystems IRIS セキュリティ・データベースは次のいずれかの方法で更新されます。
-
そのユーザの最初のログインである場合、ZAUTHORIZE によって返されたプロパティを使用して、入力されたユーザ名に対するユーザ・レコードがセキュリティ・データベースに作成されます。
-
そのユーザが以前にログインしたことがある場合、この関数によって返されるプロパティを使用して、セキュリティ・データベースのユーザ・レコードが更新されます。
初めてのユーザかどうかに関係なく、ログインするプロセスは $ROLES システム変数の値を Properties("Roles") の値に設定します。ターミナル・ログインの場合、ネームスペースは Properties("NameSpace") の値に設定され、起動ルーチンは Properties("Routine") の値に設定されます。