代行認証

代行認証の背景

InterSystems IRIS では、代行認証がサポートされます。代行認証を使用すると、企業の既存の認証システムなど、カスタムのメカニズムを実装して、インターシステムズのセキュリティに含まれる認証アクティビティやロール管理アクティビティを置き換えることができます。アプリケーション開発者は、代行認証コードのコンテンツを完全に制御します。代行認証は、InterSystems IRIS のインスタンスの %SYS ネームスペースで ZAUTHENTICATE ルーチンが検出された場合に行われます。このようなルーチンが存在する場合、InterSystems IRIS はこれを使用して、新規コードと既存のコードのいずれかを呼び出してユーザを認証します。InterSystems IRIS には ZAUTHENTICATE.mac ルーチンがあり、これは ZAUTHENTICATE ルーチンを作成するためのテンプレートとして機能します。

代行認証の動作

ユーザがログインを試行して、InterSystems IRIS が代行認証を呼び出す場合、イベントのシーケンスは以下のようになります。

1. サービスまたはアプリケーションが代行認証を使用する場合、ログイン試行によって ZAUTHENTICATE ルーチンが自動的に呼び出されます。このルーチンの認証コードは、任意のユーザ定義の ObjectScript、クラス・メソッド、または $ZF コールアウト・コードにできます。

2. 次に行う手順は、認証が成功するかどうか、および今回が ZAUTHENTICATE を使用した最初のログインであるかどうかによって異なります。

   • ZAUTHENTICATE が成功し、今回がこのメカニズムを使用した初めてのユーザ認証である場合、そのユーザはタイプを “代行ユーザ” として InterSystems IRIS ユーザのリストに追加されます。ZAUTHENTICATE によってロールまたは他の特性が設定されると、そのロールまたは特性がそのユーザのプロパティの一部になります。

   • ZAUTHENTICATE が成功し、今回が最初のログインでない場合、ZAUTHENTICATE によってそのユーザのプロパティが更新されます。

   • ZAUTHENTICATE が失敗すると、アクセス拒否のエラーが表示されます。ユーザはシステムにアクセスできません。この原因を調べる手順は次のとおりです。

     1. ユーザ・プロファイルの [ログイン失敗の理由] フィールドの内容をチェックします。

     2. さらに、監査ログで %System/%Login/LoginFailure イベントをチェックして、詳細な情報を確認します。監査や LoginFailure イベントが有効になっていない場合は、これらを両方とも有効にしてログイン失敗の状況を再現する必要がある場合があります。

3. インスタンスと関連サービスの 2 要素認証が有効な場合は、ユーザの PhoneNumber および PhoneProvider プロパティが設定されていることが確認されます。これらのプロパティが設定されている場合は、2 要素認証が実行されます。これらのプロパティが設定されていない場合は、2 要素認証に進むことはできず、ユーザは認証されません。

4. [ユーザ] ページ ([システム管理] > [セキュリティ] > [ユーザ]) で、ユーザ・リストの [タイプ] 列に代行ユーザとしてユーザが表示されます。管理ポータルに表示されるユーザのプロパティは読み取り専用です。InterSystems IRIS から編集することはできません (これらの情報はすべて InterSystems IRIS の外部から取得されるため)。

   Note:

   InterSystems IRIS パスワード・ユーザが、同時に代行ユーザになることはできません。

認証コードの基礎

インターシステムズが提供するサンプル・ルーチン ZAUTHENTICATE.mac をコピーして変更することができます。このルーチンは GitHub の Samples-Security サンプルに含まれています (https://github.com/intersystems/Samples-SecurityOpens in a new tab)。"InterSystems IRIS で使用するサンプルのダウンロード" で説明されているようにサンプル全体をダウンロードすることもできますが、単に GitHub でルーチンを開いて、その内容をコピーする方が簡単です。

独自の ZAUTHENTICATE.mac を作成するには、以下の手順を実行します。

1. ZAUTHENTICATE.mac をテンプレートとして使用するには、その内容を %SYS ネームスペースの ZAUTHENTICATE.mac ルーチンにコピーして保存します。

2. ZAUTHENTICATE.mac サンプル内のコメントを確認します。そこには、カスタム版のルーチンを実装する方法に関する重要なガイダンスが記載されています。

3. ユーザ・アカウントの特性を設定するには、カスタム認証コードと必要なコードを追加してルーチンを編集します。

シグニチャ

ZAUTHENTICATE のシグニチャは以下のとおりです。

ZAUTHENTICATE(ServiceName, Namespace, Username, Password, Credentials, 
        Properties) PUBLIC {

    // authentication 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 — 検証されるユーザが入力したパスワードを表す文字列。

• Credentials — 参照渡し。今回のバージョンの InterSystems IRIS では、実装されていません。

• Properties — 参照渡し。Username で指定したアカウントの特性を定義する返り値の配列。

InterSystems IRIS が ZAUTHENTICATE を呼び出すと、これらの引数の値がルーチンに提供されます。

認証コード

認証コードのコンテンツはアプリケーションに固有です。認証が成功すると、ルーチンから $$$OK マクロが返されます。失敗した場合はエラー・コードが返されます。返り値の詳細は、"返り値とエラー・メッセージ" を参照してください。

GetCredentials エントリ・ポイント

ZAUTHENTICATE は GetCredentials エントリ・ポイントを含んでいます。エントリ・ポイントは代行認証がサービスに対して有効となるたびに、ユーザ名およびパスワードの入力が要求される前に呼び出されます。ユーザからユーザ名およびパスワードを得る代わりに、(アプリケーション開発者が作成した) 関数のコードがユーザ名およびパスワードを指定します。その後、返されたユーザ名およびパスワードは、ユーザが入力したかのように通常の方法にて認証されます。このメカニズムを使用することで、ユーザ名およびパスワードをエントリ・ポイント内さらには認証コード内で、プロセスの $roles に対して提供することができます。

このエントリ・ポイントより返されるユーザ名とパスワードは、アプリケーション開発者が選択する任意のメカニズムにより取得できます。これらは、グローバルから取得することも、外部の DLL または LDAP 呼び出しから取得することも、または単純にルーチン内で設定することもできます。さらに、アプリケーション開発者は、ターミナル接続やログイン・ページなどでユーザ名およびパスワードの入力を要求するコードを提供することもできます。

GetCredentials エントリ・ポイントの呼び出しがある場合、戻り値およびその他の要素によって次の動作が決まります。

• コードが Username および Password の値を設定し、成功ステータス ($$$OK) も返した場合は、以下のように動作します。

  • さらにユーザ名とパスワードの入力が求められることはありません。

  • 認証プロセスが続行されます。

  Important:

  アクセス・ポイントから $$$OK が返された場合、コードは Username および Password の値を設定する必要があります。それ以外の場合、ユーザはシステムへのアクセスを拒否され、エラーが監査ログに書き込まれます。

• エントリ・ポイントからエラー・ステータス $SYSTEM.Status.Error($$$GetCredentialsFailed) が返された場合は、通常のユーザ名とパスワードの入力が求められます。

• エントリ・ポイントからその他のエラー・ステータスが返された場合は、以下のように動作します。

  • ユーザはシステムへのアクセスを拒否されます。

  • エラーが監査ログに記録されます。

GetCredentials エントリ・ポイントの以下の例では、コードは各種サービスに対してさまざまな動作を実行します。

• %Service_Console では、ユーザに情報を要求せずに、プロセスのユーザ名とパスワードをそれぞれ _SYSTEM および SYS に設定します。

• %Service_Bindings では、ユーザにユーザ名とパスワードの入力を強制します。

• Web アプリケーションでは、使用中のアプリケーションが /csp/ サンプル・アプリケーションであるかどうかをチェックします。そうである場合は、ユーザ名とパスワードを AdminUser および Test に設定します。他の Web アプリケーションである場合は、アクセスはすべて拒否されます。

• その他のどのサービスの場合も、アクセスは拒否されます。

最後に、Error エントリ・ポイントは必要に応じてクリーンアップを行います。

このコードは以下のとおりです。

GetCredentials(ServiceName,Namespace,Username,Password,Credentials) Public {

  // For console sessions, authenticate as _SYSTEM.
  If ServiceName="%Service_Console" {
    Set Username="_SYSTEM"
    Set Password="SYS"
    Quit $SYSTEM.Status.OK()
  }

  // For a web application, authenticate as AdminUser.
  If $isobject($get(%request)) { 
    If %request.Application="/csp/samples/" {
      Set Username="AdminUser"
      Set Password="Test"
      Quit $System.Status.OK()
    }
  }

  // For bindings connections, use regular prompting.
  If ServiceName="%Service_Bindings" {
    Quit $SYSTEM.Status.Error($$$GetCredentialsFailed)
  }

  // For all other connections, deny access.
  Quit $SYSTEM.Status.Error($$$AccessDenied)
}

詳細は、ZAUTHENTICATE.mac の、このエントリ・ポイントのコメントを参照してください。

ロールと他のユーザ特性の値の設定

最初の認証が成功すると、ZAUTHENTICATE は認証されたユーザのロールと他の特性を確立できます。以降のログインでは、ユーザ・レコードのこれらの要素を更新できます。

これを行うために、ZAUTHENTICATE のコードにより Properties 配列の値が設定されます (Properties は、ZAUTHENTICATE への参照によって渡されます)。通常、設定する値のソースは、ZAUTHENTICATE が使用できるユーザ情報のリポジトリです。

返り値とエラー・メッセージ

ルーチンは以下のいずれかの値を返します。

• 成功 — $$$OK。ユーザ名とパスワードの組み合わせが正常に認証されたことを示します。

• 失敗 — $SYSTEM.Status.Error($$$ERRORMESSAGE)。認証が失敗したことを示します。

ZAUTHENTICATE は、システム定義またはアプリケーション固有のエラー・メッセージを返すことができます。これらのメッセージはすべて、%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) — “サービス Servicename のログインは無効です” のエラー・メッセージ

• $SYSTEM.Status.Error($$$ServiceLoginsDisabled) — “ログインは無効です” のエラー・メッセージ

• $SYSTEM.Status.Error($$$ServiceNotAuthorized,ServiceName) — “ユーザはサービスを許可されていません” のエラー・メッセージ

カスタム・メッセージを生成するには、$SYSTEM.Status.Error() メソッドを使用して、このメソッドに $$$GeneralError マクロを渡し、2 番目の引数として任意のカスタム・テキストを指定します。以下はその例です。

$SYSTEM.Status.Error($$$GeneralError,"Any text here")

エラー・メッセージが呼び出し元に返されると、そのメッセージは監査データベース (LoginFailure イベント監査が有効な場合) にログとして記録されます。表示されるエラー・メッセージは $SYSTEM.Status.Error($$$AccessDenied) のみです。ただし、$$$PasswordChangeRequired エラーのメッセージも表示されます。現在のパスワードから新しいパスワードへの変更をユーザに要求する場合、このエラーを返します。

システムの状態

代行認証を使用して最初に認証されるユーザは、“代行ユーザ” というタイプで [ユーザ] ページ ([システム管理] > [セキュリティ] > [ユーザ]) のユーザ・テーブルに表示されます。システム管理者が管理ポータル (またはその他の InterSystems IRIS のネイティブ機能) を使用して明示的にユーザを作成した場合、そのユーザのタイプは “InterSystems IRIS パスワード・ユーザ” になります。ユーザが代行認証を使用してログインを試行し、認証が正常に行われる場合でも、そのユーザが既に (代行ユーザではなく) InterSystems IRIS ユーザとして存在することを InterSystems IRIS が検出すると、ログインは失敗します。

パスワードの変更

ZAUTHENTICATE ルーチンには、エントリ・ポイント ChangePassword も含まれており、そこにはユーザのパスワードを変更するコードが含まれています。このエントリ・ポイントのシグニチャは以下のとおりです。

ChangePassword(Username,NewPassword,OldPassword,Status) Public {}

各項目の内容は次のとおりです。

• Username は、パスワードを変更するユーザを指定する文字列です。

• NewPassword は、ユーザのパスワードの新しい値を指定する文字列です。

• OldPassword は、ユーザのパスワードの古い値を指定する文字列です。

• Status (参照によって渡される) は、InterSystems IRIS の状態値を受信します。受信した値では、パスワード変更が成功したことを示すか、ルーチンの失敗の原因となったエラーを指定します。