代行承認の使用法

ZAUTHORIZE.mac テンプレートからの作業

管理ユーティリティ・ソース・コードがインストールされているインスタンスでは、ルーチン ZAUTHORIZE.mac の SAMPLES ネームスペースで、システムが提供する ZAUTHORIZE ルーチンを使用できます。管理ユーティリティ・ソース・コードをインストールするには、Caché データベース・エンジンを含む、開発向けインストール、サーバのインストール、またはカスタム・インストールのいずれかのインストール・タイプを選択します。

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

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

2. ZAUTHORIZE のシステムが提供するコードでコメントを確認します。そこには、カスタム版のルーチンを実装する方法に関する重要なガイダンスが記載されています。

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

新しいバージョンの Caché にアップグレードする前に、ZAUTHORIZE.mac を確認し、現在の承認コードで新機能をサポートするための変更が必要かどうかを判断してください。

ZAUTHORIZE シグニチャ

代行承認用に構成されると、システムは承認が発生した後、自動的に ZAUTHORIZE を呼び出します。Caché は、必要に応じて ZAUTHORIZE シグニチャで定義されたパラメータの値を提供します。ZAUTHORIZE のシグニチャは以下のとおりです。

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

  // authorization code
  // optional code to specify user account properties and roles
}

以下はその説明です。

• ServiceName — ユーザから Caché への接続を仲介しているサービスの名前を指定する文字列 (%Service_Console や %Service_CSP　など)。

• Namespace — 接続が確立される Caché サーバ上のネームスペースを指定する文字列。これは、スタジオや ODBC の接続など、%Service_Bindings のみで使用されます。その他のサービスの場合、この値は "" (引用符で囲んだ空の文字列) とする必要があります。

• Username — 特権が決定されるユーザを指定する文字列。

• Password — 使用しているアカウントに関連付けられたパスワードを指定する文字列。これは、Kerberos K5API 認証メカニズムのみで使用されます。その他のメカニズムの場合、この値は "" (引用符で囲んだ空の文字列) とする必要があります。

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

• Properties — 参照渡し。Username で指定したアカウントの特性を指定する返り値の配列。詳細は、“ZAUTHORIZE とユーザ・プロパティ” を参照してください。

ZAUTHORIZE による承認コード

ZAUTHORIZE の目的は、認証されたユーザのロールと他の特性を確立または更新することです。承認コードのコンテンツはアプリケーションに固有です。これには、ユーザが記述した ObjectScript コード、クラス・メソッド、または $ZF コールアウトを含めることができます。

ZAUTHORIZE は、Properties 配列の値を設定することによりロール情報を指定します。この配列は、ZAUTHORIZE に参照渡しされます。通常、設定する値のソースは、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 エラーのメッセージも表示されます。現在のパスワードから新しいパスワードへの変更をユーザに要求する場合、このエラーを返します。

代行承認とユーザ・タイプ

代行承認を使用する認証メカニズムでユーザが最初に Caché にログインすると、システムは OS (オペレーティング・システム) または Kerberos のタイプのユーザ・アカウントを作成します。(この値は、[ユーザ] ページ ([システム管理] > [セキュリティ] > [ユーザ]) にあるユーザのテーブルの [タイプ] 列に表示されません。)ZAUTHORIZE ルーチンは、アカウント作成の時点で、その後のログインのため、そのユーザのロールを指定します。

代行承認を使用せずにログインを試みると、ログインは失敗します。これは、代行承認のみがユーザ・タイプを OS または Kerberos として指定するためです。代行承認なしでこれらの認証メカニズムを使用する場合、ユーザは "Caché パスワードユーザ" のタイプとして認証されます。ユーザが持つことのできるタイプは 1 つのみで、あるタイプのユーザは別のタイプに関連付けられたメカニズムを使用してログインすることができないため、ログインは失敗します (代行認証および LDAP 認証も同じ理由で失敗します)。

ユーザ・タイプの概説は、“ユーザ” の章の “ユーザ・タイプについて” を参照してください。