アクセス・サーバーでは、保護対象とするリソースへのアクセスを制限するために、認証と認可の両方の制御が利用されます。認証の制御には、認証ルールが使用されます。認証ルールでは認証スキームが使用され、認証スキームでは、ユーザーがリソースへのアクセス試行時に入力した資格証明をテストするため、1つ以上のプラグインが使用されます。プラグインは、アクセス・サーバーのインストールの一部として提供されるものを使用することも、カスタム・プラグインを使用することもできます。
この章では、カスタム認証プラグインの作成について説明します。内容は次のとおりです。
アクセス・システムで保護されるWebサーバーのリソースがブラウザからリクエストされると、そのリソースが保護されているかどうか、また保護されている場合には当該ユーザーが認証を受ける必要があるかどうかが、アクセス・サーバーによってチェックされます。ユーザーがまだログインしていない場合は、新規にログインするようアクセス・サーバーから求められ、認証チャレンジがブラウザに送信されます。認証チャレンジでは、認証スキームに定義されているチャレンジ・メソッドが使用されます。認証スキームは認証ルールの一部であり、認証ルールはリソースを保護するアクセス・ポリシーの一部です。認証スキームを実行すると、1つの認証プラグイン、または複数の連鎖するプラグインが起動されます。複数の連鎖するプラグインは、スキームに指定されている順序で実行されます。
すべてのスキームは同じ汎用フローに従います。ブラウザは、認証チャレンジに応答して、ユーザーから資格証明を取得します。資格証明にはユーザー名およびパスワード、またはクライアント証明書などがあります。クライアント証明書認証などの場合には、ユーザーのかわりにブラウザにより資格証明が生成されます。ブラウザは、資格証明を、チャレンジに設定されている書式でサーバーに送信します。アクセス・サーバーでは、資格証明を、処理で使用するために名前と値のペアのセットに書式設定しなおし、認証リクエストとして処理します。
ユーザーの資格証明は、スキーム内の単一プラグインか各プラグインへの入力となります。出力は、認証の承認、続行、拒否または終了を示すステータスと、資格証明のセットです。この資格証明は、元の情報と異なる場合があります。
認証が失敗した場合、アクセス・サーバーの監査ファイルがプラグインにより指定されていると、そのファイルに結果メッセージが記録されます。認証スキームの終了時には、必ず結果として、有効なユーザーDNが1つのみ生成されるか、ユーザーDNは生成されないかのいずれかになります。
認証が成功した場合は、当該ユーザーのプロファイルDN、ユーザーのブラウザのIPアドレス、認証スキームのレベルおよびCookieの有効期限が含まれたセッションCookieが、アクセス・サーバーにより作成されます。また、認証スキームに定義された認証アクションに基づいて、アクセス・サーバーによりHTTPヘッダー変数が設定されることもあります。CookieやHTTPの情報がブラウザに戻されると、アクセス権が付与されます。
認証が成功しなかった場合には、アクセス・サーバーによってHTTPの戻りステータス401(権限なし)が設定されます。これは、認証されなかったアクセスに対する標準的なレスポンスで、この場合、リソースへのアクセスが拒否されます。
事前定義済の認証プラグインのみを使用する認証スキームが作成できます。「標準プラグイン」を参照してください。また、開発者が独自のプラグインを作成して、それを単独で、または標準プラグインと組み合せてスキーム内で使用することもできます。
ここでは、10g(10.1.4.0.1)における変更と下位互換性について説明します。
10g(10.1.4.0.1)のC用認証プラグインAPIでは、プラグイン処理にUTF-8エンコーディングが使用されます。旧リリースのC用認証プラグインAPIでは、アクセス・サーバーとカスタム・プラグインとの間で交換されるデータにLatin-1エンコーディングが使用されていました。
古いアクセス・サーバーを10g(10.1.4.0.1)にアップグレードする場合、アクセス・サーバーのglobalparams.xmlファイルで「="IsBackwardCompatible" Value="false"」が自動的に設定されます。下位互換性のあるアクセス・サーバーでは、データをそのままLatin-1エンコーディングで認証プラグインに送信し、そのデータがプラグイン側でもLatin-1エンコーディングで設定されるものと想定しています。プラグインのデータのエンコーディングには変更はありません。
アップグレードした環境に新しい10g(10.1.4.0.1)のアクセス・サーバーを追加する場合、アクセス・サーバーのglobalparams.xmlファイルで「="IsBackwardCompatible" Value="false"」を手動で設定し、古いプラグインとインタフェースとの通信、および古いWebGateとカスタム・アクセス・ゲートとの通信を有効にする必要があります。
次の各項では、プラグインAPIの開発環境について、サポート・ファイルのロケーションと主要なコンポーネントなどを説明します。
アクセス・システムのアクセス・サーバー・コンポーネントのインストール時には、アクセス・サーバー・コンポーネントをインストール・ディレクトリASInstall_Dirに配置します。これは、たとえば次のようなロケーションです。
C:/COREid/access/oblix
認証プラグインAPIのサンプル・ファイルは、このディレクトリ内の次のロケーションにインストールされます。
AccessServer_install_dir
/access/oblix/sdk/authentication/samples
samplesディレクトリ内には、authn_apiというサブディレクトリがあります。
ソース・コードのビルドと実行に必要なファイルが、すべてsamplesディレクトリに含まれているわけではありません。たとえば、ヘッダー・ファイル、インクルード・ファイルなどは含まれていません。
authn_apiは、単純な認証プラグイン例のソース・コードであり、サンプルmakeファイルとなっています。1レベル下のincludeディレクトリには、ヘッダー・ファイルauthn_api.hがあります。
authn_api.hファイルには、次の2種類の重要な情報が含まれています。
アクセス・サーバーからすべての認証プラグインに提供されるユーティリティ・セットの定義
APIのデータおよび関数の定義
注意: このファイルには、APIの適切なビルドおよび操作に不可欠な定義があります。アクセス・サーバーがプラグインをロードする際には、プラグイン内にauthn_api.hの5つの関数のセットが実装されているものと想定しています。このファイルに情報を追加することは可能ですが、既存の内容は削除しないでください。 |
ビルドの手順
samplesディレクトリ下で、authn_apiディレクトリの内容を別のディレクトリ(たとえばmyplugin)にコピーします。
新規ディレクトリ内においてauthn.cファイルの内容を変更するか、追加でファイルを作成するかまたはその両方を行って、作成するプラグインに固有の、必要な機能を実装します。
makeファイルを変更して、Cコンパイラおよびauthn_api.hファイルへの実際のパスを指定し、またすべてのソース・コードがインクルードされてコンパイルされるようにします。
makeファイルを実行します。(説明した例はUNIXでのみ使用できます。Windows環境では独自に作成する必要があります。)
これにより、*.soまたは*.dllというプラグインが新しく作成されます。
作成したプラグインは、アクセス・サーバーを稼働するシステム内の次のディレクトリに格納する必要があります。
ASInstall_Dir
/lib
アクセス管理者は、プラグインを認証スキーム内に適切に構成するために、プラグインのファイル名とその必須およびオプションのデータ名を把握している必要があります。認証スキームの構成の詳細は、『Oracle Access Managerアクセス管理ガイド』を参照してください。「Cの認証プラグインの例」の後に、この例を実際に示す認証スキーム構成の画面があります。
この項では、C APIで使用される様々なタイプの定数データおよび変数データについて説明します。
authn_api.hには、一部の関数で引数用の固定値として使用される値がいくつか事前に定義されています。
#define OB_AN_PLUGIN_VERSION "8.0" #define ObAnPluginRequestResource "Resource" #define ObAnPluginRequestOperation "Operation" #define ObAnPluginRequesterDN "RequesterDn"
値の名前 | 意味 |
---|---|
OB_AN_PLUGIN_VERSION | ObAnPluginGetVersionをコールした場合、必ずこの値がアクセス・サーバーに戻されます。ヘッダー・ファイル内の値は製品のリリースに応じた値となります。 |
ObAnPluginRequestResource | ホスト名とポートの後のリソース。例: /basic/page.htm 。 |
ObAnPluginRequestOperation | リソースに対して実行する操作。 |
ObAnPluginRequesterDN | DNが認証プラグインで設定されている場合、ここでの定義によって他のプラグインからそのDNにアクセスできます。DNを設定する認証プラグインの名前は常にcredential_mappingです。
DNは、カスタム認証プラグインでも、SetCredFnをコールして事前設定できます。 |
ObAnPluginRequesterIP | このリクエストを発行したクライアントのIPアドレス。 |
アクセス・サーバーおよびAPIでは、ハンドルとも呼ばれるポインタを使用して、アクセス・サーバーがプラグインで使用するために保持しているデータ構造体を操作できます。これらのハンドルの名前と説明を次の表に示します。すべての構造体の内容に関する説明は、「C構造体」を参照してください。リスト、名前、値および項目といった用語は、ObAnPluginInfo構造体の内部で相互関係があるデータを表しています。
データ型/名前 | 目的 |
---|---|
void const*ObAnPluginSVData_t |
単一値を持つ名前が格納されているデータ構造体へのハンドル。ObAnPluginInfo構造体からのCredsおよびActionInfoの検索に使用します。 |
void*ObAnPluginMVData_t |
複数の値を持ちうる名前が格納されているデータ構造体へのハンドル。ObAnPluginInfo構造体からのParamsおよびContextの検索に使用します。 |
char** ObAnPluginStatusMsg_t |
プラグインの関数が結果を報告するために戻すNULL終了文字列。 |
void const* ObAnPluginList_t |
ObAnPluginInfo構造体のParamsまたはContextメンバーのデータの一部である、複数の値を持つ名前の項目からなるリストを指すハンドル。このハンドルを取得するには、GetData関数を使用します。 |
void const*ObAnPluginListItem_t |
複数の値を持つ名前のリストにおける現在の項目を指すハンドル。このハンドルを取得するには、GetFirstItem関数またはGetNext関数を使用します。 |
struct ObAnPluginInfo*ObAnPluginInfo_t |
ObAnPluginInfo構造体を指すハンドル。この構造体にはアクセス・サーバーからの情報と、プラグインで生成されたデータが含まれます。 |
struct ObAnServerContext*ObAnServerContext_t |
ObAnServerContext構造体を指すハンドル。この構造体にはアクセス・サーバーに関する一般情報が含まれています。 |
アクセス・サーバーおよびAPIが通信用として使用する関数の多くは、ステータス値を戻すようになっています。これらの戻り値は、この項で説明するように、複数のカテゴリにわたって事前に定義されています。
このカテゴリの値は、APIがアクセス・サーバーに実行するアクションを通知するために戻すアクション・フラグです。
typedef enum { ObAnSuccessRedirect = 0, ObAnFailRedirect = 1, ObAnSuccessProfileAttrs = 2, ObAnFailProfileAttrs = 3, ObAnSuccessFixedVals = 4, ObAnFailFixedVals = 5 } ObAnActionType_t;
名前 | 説明 |
---|---|
ObAnSuccessRedirect |
認証が成功した場合に、認証ルールに定義されたとおりにリダイレクションURLを設定するようアクセス・サーバーへ通知します。 |
ObAnFailRedirect |
認証が失敗した場合に、認証ルールに定義されたとおりにリダイレクションURLを設定するようアクセス・サーバーへ通知します。 |
ObAnSuccessProfileAttrs |
認証が成功した場合に、認証ルールで指定された値(プラグインで追加されることもある)を使用して、アクション用のプロファイル属性を設定するようアクセス・サーバーへ通知します。 |
ObAnSuccessProfileAttrs |
認証が失敗した場合に、認証ルールで指定された値(プラグインで追加されることもある)を使用して、アクション用のプロファイル属性を設定するようアクセス・サーバーへ通知します。 |
ObAnSuccessFixedVals |
認証が成功した場合に、認証ルールに定義された固定値(プラグインで追加されることもある)を設定するようアクセス・サーバーへ通知します。 |
ObAnFailFixedVals |
認証が失敗した場合に、認証ルールに定義された固定値(プラグインで追加されることもある)を設定するようアクセス・サーバーへ通知します。 |
プラグインでは、認証の試行結果を示すために、このカテゴリの値のいずれかをアクセス・サーバーへ戻す必要があります。
typedef enum { ObAnPluginstatusContinue = 0, ObAnPluginstatusAllowed = 1, ObAnPluginstatusDenied = 2, ObAnPluginstatusAbort = 3 }ObAnPluginstatus_t;
値の名前 | 意味 |
---|---|
ObAnPluginStatusContinue |
プラグインは正常終了した場合にこのコードを戻します。
アクセス・サーバーは、リターン・コードContinueを、現行プラグインが成功し、認証スキームのステップにおける次のプラグインの処理を行う必要があることを示すものとして解釈します。 認証スキームのすべてのプラグインからこの結果コードが戻されると、認証は成功になります。 |
ObAnPluginStatusAllowed |
プラグインは、認証が成功した場合にこのコードを戻します。
アクセス・サーバーでは、リターン・コードAllowedを、資格証明の処理終了と認証の成功を示すものとして解釈します。 認証スキームにおける後続のステップの認証プラグインは、アクセス・サーバーで処理されません。 |
ObAnPluginStatusDenied |
プラグインは、認証が失敗した場合にこのコードを戻します。
アクセス・サーバーでは、リターン・コードDeniedを、資格証明の処理終了と認証の失敗を示すものとして解釈します。 認証が失敗したため、認証スキームの後続のステップにおける認証プラグインはアクセス・サーバーで処理されません。 |
ObAnPluginStatusAbort |
プラグインは、その処理で致命的なエラーが発生した場合にこのコードを戻します。
アクセス・サーバーでは、リターン・コードAbortを、プラグインを含むステップのみの終了ではなく、認証スキームで指定された認証プロセスの終了を示すものとして解釈します。 初期化中にAbortが戻された場合、アクセス・サーバーによってログに状態が書き込まれますが、プロセスは終了しません。 |
プラグインがアクセス・サーバーに組込み関数の1つを実行するように求めると、アクセス・サーバーではその関数の実行が試みられ、このカテゴリの値のいずれかが戻されます。
typedef enum { ObAnASStatusSuccess = 0, ObAnASStatusFailed }ObAnASStatus_t;
値の名前 | 意味 |
---|---|
ObAnASStatusSuccess |
アクセス・サーバーで操作が正常に実行されました。 |
ObAnASStatusFailed |
アクセス・サーバーで操作が実行されませんでした。このエラーの原因で最も多いのは、変更が許可されていない値をプラグインで変更しようとしたというものです。たとえば、単一の値のみが許可されている配列メンバーである名前に、2つ目の値を追加しようとした場合などです。 |
アクセス・サーバーでは、関連するデータ項目を名前付きの構造体にまとめ、メモリーを割り当てて転送します。構造体は開発者からは不透明です。つまり、構造体を使用してアクセス・サーバーと情報をやり取りすることはできますが、構造体の編成方法や構造体に含まれるデータの形式は変更できません。構造体の内容は、場合によっては変更できます。
認証プラグインAPIで使用される構造体を次に示します。
この構造体は、プラグインで必要となるアクセス・サーバーに関する情報を転送するために使用します。
struct ObAnServerContext { char *AccessServerInstallDir; char *AccessServerAnPluginAPIVersion; };
ObAnServerContext_tは、この構造体のハンドルです。
この構造体に保持されているデータは読取り専用です。
データ型/名前 | 目的 |
---|---|
AccessServerInstallDir |
アクセス・サーバーのインストール・ディレクトリへのパス。例: COREid/Access。
|
AccessServerAnPluginAPIVersion |
アクセス・サーバーのインスタンスでサポートされる認証プラグインAPIのうち、最も古いバージョン。 |
この構造体には、使用する認証ルールで設定されたデータがアクセス・サーバーによって格納されます。次に、構造体はプラグインに提供されます。プラグインでは、処理の進行とともに、構造体内部のデータが変更され、場合によっては新規データが追加されます。認証スキーム内で複数のプラグインが実行される場合は、ルール内の最初のプラグインに対する変数情報を設定してスキーム内の1つのプラグインから別のプラグインに情報を渡す手段ともなります。
struct ObAnPluginInfo { ObAnPluginsVData_t Creds; ObAnPluginMVData_t Params; ObAnPluginMVData_t Context; ObAnPluginsVData_t ActionInfo; };
ObAnPluginInfo_tはこの構造体を指すハンドルです。
構造体からのデータの抽出や構造体へのデータの格納には、「アクセス・サーバーによって提供される関数(C API)」に記載されている関数を使用します。
データ型/名前 | 目的 |
---|---|
Creds |
リソースへのアクセスを試行するエンティティ(ユーザーまたはアプリケーション)から送信されたすべての情報。このデータにはプラグインによる追加や変更が可能です。このデータは次のプラグインへと順に渡されます。したがって、このデータは、プラグインが認証スキームでその次に指定されているプラグインと通信するためにも使用できます。構造体のリスト内には、Resource、Operation、RequesterDNおよびRequesterIPという4つの事前定義された名前がアクセス・サーバーによって用意されています。 |
Params |
プラグイン構成に指定されているパラメータ。このデータは、プラグイン内部では追加や変更が可能ですが、次のプラグインには渡されません。 |
Context |
プラグインで作成されたデータ。このデータにはプラグインによる追加や変更が可能です。このデータは次のプラグインへと順に渡されます。 |
ActionInfo |
プラグイン構成に指定されているアクション情報。このデータにはプラグインによる追加や変更が可能です。アクションを設定して次のプラグインへ渡すことも可能ですが、アクション情報は最終的にアクセス・サーバーで使用されることに留意しておく必要があります。 |
ObAnPluginInfo構造体の編成を理解することは、認証プラグインAPIの機能を理解するための鍵になります。この構造体は、ネストされた4つの配列(構造体メンバー)からなる配列と考えることもできます。各メンバーには、1つ以上の名前が格納されます。
ObAnPluginSVData_t型の構造体メンバーの配列は、名前と各名前に関連付けられた単一の値のセットからなります。たとえば、credsメンバーは次のような構造を持つと考えることができます。
名前 | 値 |
---|---|
Resource | 1つの値 |
Operation | 1つの値 |
RequesterDN | 1つの値 |
RequesterIP | 1つの値 |
ユーザーが作成した資格証明の名前 | 1つの値 |
値を取得するには、値を取得する資格証明の名前を入力引数としてGetCredFnを使用します。この関数により、単一の値が戻されます。アクションについてもGetActionFnで同様の操作ができます。
ObAnPluginMVData_t型の構造体メンバーでは、それぞれの名前に対応するハンドルがあり、1つ以上の項目からなるリストを指しています。各項目には、値に加えて、リスト内の次の項目を指すハンドルがあります。次の項目を指すハンドルがNULLに設定されている場合、リストの最後であることを示します。
paramsメンバーの動作は、次のダイアグラムのようになります。GetDataFnを使用して、params配列内の特定のパラメータ名に関するリストを指すポインタを取得します。次に、GetFirstFnを使用して、リスト内の最初の項目に関する情報を指すハンドルを取得します。ここでGetValueFnを使用することで項目1の値が戻され、GetNextFnを使用することで項目2の情報を指すハンドルが戻される、というように続いていきます。
この構造体には、プラグインでObAnPluginInfo構造体のデータを操作するために使用される、アクセス・サーバーで使用可能な関数のブロックを指すハンドルが用意されています。
struct ObAnPluginFns { ObASPluginGetFirstItem_t GetFirstItemFn; ObASPluginGetValue_t GetValueFn; ObASPluginGetNext_t GetNextFn; ObAnPluginGetData_t GetDataFn; ObAnPluginsetData_t SetDataFn; ObAnPluginGetCred_t GetCredFn; ObAnPluginsetCred_t SetCredFn; ObAnPluginGetAction_t GetActionFn; ObAnPluginSetAuthnUid_t SetAuthnUidFn };
ObAnPluginFns_tはこの構造体を指すハンドルです。
この構造体はObAnPluginFnの実装時に参照します。関数については、別途「アクセス・サーバーによって提供される関数(C API)」で説明します。
このAPIでアクセス・サーバーとの通信に使用される関数には2つのタイプがあります。1つのタイプは、アクセス・サーバーによって提供される関数で、アクセス・サーバーを参照することでコールされます。もう1つのタイプは、プラグインに実装する関数です。実装には、authn_api.h内のプロトタイプを使用します。
これらの関数を使用するには、コードに指定したObAnPluginFns型の構造体のメンバーとしてコールする必要があります。たとえば、ObAnPluginFnを実装し、ObAnPluginFnsタイプの変数名をpFnBlockに設定した場合、pFnBlock→GetCredFnのように、構造体内の位置を参照することによってGetCredFnをコールします。
この関数では、ObAnPluginInfo構造体のParamsメンバーまたはContextメンバーの複数値データからなるリストへのハンドルが戻されます。プラグインがハンドルの取得後にそのリストから情報を抽出するには、リスト操作関数をGetFirstItemFns、GetValueFn、GetNextFn、GetValueFnなどのように使用する必要があります。
この関数の書式は次のとおりです。
ObAnPluginList_t GetDataFn( ObAnPluginMVData_t prequesterinfo, const char* pName );
表6-1で、この関数の入力パラメータについて説明します。
表6-1 入力パラメータ
変数名 | 目的 |
---|---|
|
プラグインに渡すObAnPluginInfo構造体の複数値メンバーへのハンドル。 |
|
この名前の項目からなるリストを取得します。 |
出力パラメータ
この関数には出力パラメータはありません。
この関数からは、指定した名前の値からなるリストへのハンドルが戻されます。ハンドルの値がNULLの場合、指定した名前はこの構造体のメンバーにはありません。
この関数では、ObAnPluginInfo構造体のParamsメンバーまたはContextメンバーの名前に値が設定されます。アクセス・サーバーによって名前がすでに存在しているかどうかがチェックされ、replaceフラグの値に応じて値が追加されるか、上書きされます。
この関数の書式は次のとおりです。
ObAnASStatus_t SetDataFn( ObAnPluginMVData_t pRequesterContext, const char* pName, const char* pValue, const int replace );
表6-2で、この関数の入力パラメータについて説明します。
表6-2 入力パラメータ
変数名 | 目的 |
---|---|
|
プラグインに渡すObAnPluginInfo構造体の書込み可能な複数値メンバーへのハンドル。 |
|
値を設定する情報の名前。 |
|
挿入する値。 |
|
名前の既存の値を置換するかまたはそれに追加するかを指定します。整数値0を指定すると、追加になります。0以外の値は、pNameの現在の第1の値を置換するリクエストとなります。 |
出力パラメータ
この関数には出力パラメータはありません。
この関数では、ObAnASStatus_tカテゴリの値のうちのいずれかが戻されます。
注意: replaceオプションは、リスト内の最初の項目にのみ適用されます。 |
この関数では、複数値データからなるリストの最初の項目へのハンドルが戻されます。これは、完全なリストへのハンドルがGetDataFnを使用して取得された後で行われます。GetValueFnを使用して値を要求するには、少なくともこの最初のステップであるGetFirstItemFnを実行する必要があります。この完全なリストへのハンドルは、リスト内の最初の項目へのハンドルではありません。
この関数の書式は次のとおりです。
ObAnPluginListItem_t GetFirstItemFn( ObAnPluginList_t plist );
表6-3で、この関数の入力パラメータについて説明します。
出力パラメータ
この関数には出力パラメータはありません。
この関数では、項目の値が文字型で戻されます。
この関数では、GetFirstItemFnまたは以前のGetNextFnの使用により取得されている現在の項目へのハンドルを基に、複数値からなるリスト内の次の項目へのハンドルが取得されます。
この関数の書式は次のとおりです。
ObAnPluginListItem_t GetNextFn( ObAnPluginListItem_t pItem );
表6-4で、この関数の入力パラメータについて説明します。
出力パラメータ
この関数には出力パラメータはありません。
この関数では、リスト内の次の項目へのハンドルが戻されます。戻された値がNULLの場合、リストの最後に到達したことを示します。
この関数では、資格証明情報のハンドルおよび名前を基に、資格証明の名前の値が取得されます。ユーザーの認証レベルは、ユーザーがログインしたスキームやリソースによって限定されます。たとえば、ユーザーがActive Directoryまたはリバース・プロキシのどちらからログインしたかに基づいて認証レベルを設定できます。この情報をカスタム・プラグインで抽出するには、資格証明リストに設定されているObAuthentSchemeLevel変数をアクセス・サーバーに問い合せます。
資格証明の名前に対して、1つの値のみを戻すことができます。
この関数の書式は次のとおりです。
const char *GetCredFn( ObAnPluginSVData_t pCreds, const char* pName );
表6-5で、この関数の入力パラメータについて説明します。
出力パラメータ
この関数には出力パラメータはありません。
この関数では、資格証明の値が戻されます。値が見つからない場合はNULLが戻されます。
schemeLevel = pFnBlock->GetCredFn(pInfo->Creds, "ObAuthentSchemeLevel");
この関数では、資格証明情報へのハンドル、変更する資格証明の名前および格納する値を基に、プラグインに渡す資格証明情報のうち、指定された名前の値が設定されます。名前がすでに存在する場合は、現在の値が上書きされます。存在しない場合は、名前と値が追加されます。
この関数の書式は次のとおりです。
ObAnASStatus_t SetCredFn( ObAnPluginSVData_t pCreds, const char* pName, const char* pValue );
表6-6で、この関数の入力パラメータについて説明します。
出力パラメータ
この関数には出力パラメータはありません。
次の関数では、ObAnASStatus_tカテゴリの値のうちのいずれかが戻されます。
schemeLevel = pFnBlock->GetCredFn(pInfo->Creds, "ObAuthentSchemeLevel"); if(schemeLevel != NULL){ schemeLevelAsInt = atoi(schemeLevel); schemeLevelAsInt +=10; itoa(schemeLevelAsInt, buff, 10); pFnBlock->SetCredFn(pInfo->Creds, "ObAuthentSchemeLevel", buff);
例6-1でUIDの設定を説明します。
この関数では、アクション情報へのハンドル、取得するアクションの名前およびタイプを基に、アクション情報を取得します。アクションの名前とタイプの組合せに対して、1つの値のみを戻すことができます。
この関数の書式は次のとおりです。
const char *AnGetAction( ObAnPluginSVData_t pActionInfo, const char* pName, ObAnActionType_t pActionType);
表6-7で、この関数の入力パラメータについて説明します。
表6-7 入力パラメータ
変数名 | 目的 |
---|---|
|
プラグインに渡すアクション情報へのハンドル |
|
取得するアクション情報のキーまたは名前 |
|
取得するアクション情報のタイプ |
出力パラメータ
この関数には出力パラメータはありません。
この関数では、アクションとタイプの組合せに対する値が戻されます。値が見つからない場合はNULLが戻されます。
この関数では、アクション情報へのハンドル、変更するアクションの名前、格納する値およびアクションのタイプを使用して、プラグインに渡すアクション情報の値を設定します。名前とタイプの組合せがすでに存在する場合は、その値が上書きされます。存在しない場合は、名前と値が追加されます。
この関数の書式は次のとおりです。
ObAnASStatus_t SetActionFn( ObAnPluginSVData_t Creds, const char* pName, const char* pValue ObAnActionType pActionType);
表6-8で、この関数の入力パラメータについて説明します。
表6-8 入力パラメータ
変数名 | 目的 |
---|---|
|
プラグインに渡すアクション情報へのハンドル |
|
設定するアクション情報のキーまたは名前 |
|
アクションに書き込む値 |
|
設定するアクション情報のタイプ |
出力パラメータ
この関数には出力パラメータはありません。
この関数では、ObAnASStatus_tカテゴリの値のうちのいずれかが戻されます。
この関数では、現在のユーザーの認証で内部的に使用されるUIDが設定されます。UIDがすでに設定されている場合は、その値が上書きされます。設定されていない場合は、値が追加されます。
警告: この関数は廃止されます。かわりにSetCredFnを使用してください。 |
この関数の書式は次のとおりです。
ObAnASStatus_t SetAuthnUidFn( char* pUid );
表6-9で、この関数の入力パラメータについて説明します。
出力パラメータ
この関数には出力パラメータはありません。
この関数では、ObAnASStatus_tカテゴリの値のうちのいずれかが戻されます。
開発者は、この項に記載されているすべての関数を、authn_api.h内に提供されているプロトタイプを使用してプラグイン内に実装する必要があります。アクセス・サーバーではこれらがすべて存在するものと想定し、存在しない場合にはプラグインの実行を拒否します。
各関数のOBDLLEXPORTエントリは必須です。このエントリにより、アクセス・サーバーがプラグイン内でこれらの関数を見つけてコールできるようになります。
アクセス・サーバーではこれらの関数がこの順序でコールされます。
GetVersion: プラグインの初回のロード時にコールされます。
Init: プラグインの初回のロード時にコールされます。
DeAllocStatusMessage: ステータス・メッセージを戻す他の任意の関数に続いて自動的にコールされます。
Fn: プラグインの使用時に毎回コールされます。
Terminate: アクセス・サーバーの停止時またはプラグインのアンロード時にコールされます。
この関数は、プラグインがロードされた直後にアクセス・サーバーからコールされます。プラグインからは、そのビルド時に使用されたライブラリのバージョン番号が戻されます。アクセス・サーバーでは、このバージョンを使用して、プラグインがサポート可能かどうかを判断します。つまり、古いバージョンのアクセス・サーバーがより新しいバージョンのAPIのサポートを求められていないかや、新しいバージョンのアクセス・サーバーがサポートの終了したバージョンのプラグインと連携するように求められていないかが、アクセス・サーバーで把握されます。
この関数の書式は次のとおりです。
OBDLLEXPORT
const char* ObAnPluginGetVersion(void)
;
この関数には入力パラメータはありません。
出力パラメータ
この関数には出力パラメータはありません。
この関数からは、認証プラグインのバージョンが戻されます。これは、authn_api.hファイルの次の行で設定されている値です。
#define OB_AN_PLUGIN_VERSION "X.X"
この関数は、アクセス・サーバーにより、バージョンが確認された直後にコールされます。この関数ではプラグインの作業領域が初期化されます。初期化作業には、データベースへの接続やプラグインのグローバル・データの初期化といったタスクがあります。この関数と、pResultの文字列を戻す他の2つの関数で、pResultの文字列を戻すためのメモリーを割り当てることも必要になります。このメモリーの割当ては、アクセス・サーバーで自動的にObAnPluginDeallocStatusMsg関数がコールされることによって解除されます。
この関数の書式は次のとおりです。
OBDLLEXPORT ObAnPluginStatus_t ObAnPluginInit( ObAnServerContext_t pServerContext, ObAnPluginStatusMsg_t pResult );
表6-10で、この関数の入力パラメータについて説明します。
表6-11で、この関数の出力パラメータについて説明します。
この関数からは、ObAnPluginStatus_tカテゴリのObAnPluginStatusContinueまたはObAnPluginStatusAbortのいずれかの値を戻す必要があります。
この関数は、アクセス・サーバーの終了直前にアクセス・サーバーからコールされます。この関数は、プラグイン内で設定した作業領域を消去し、プラグインで開いたデータベースなど他のアプリケーションとの接続を解除するために、記述する必要があります。
この関数の書式は次のとおりです。
OBDLLEXPORT ObAnPluginStatus_t ObAnPluginTerminate( ObAnServerContext_t pServerContext, ObAnPluginstatusMsg_t pResult);
表6-12で、この関数の入力パラメータについて説明します。
表6-13で、この関数の出力パラメータについて説明します。
この関数からは、ObAnPluginStatus_tカテゴリのObAnPluginStatusContinueまたはObAnPluginStatusAbortという2つの値のいずれかを戻す必要があります。
この関数は、プラグイン情報およびサーバー・コンテキストを使用して実際のカスタム認証作業を実行するようプラグインにリクエストするために、アクセス・サーバーからコールされます。また、この関数では、プラグイン情報の一部を、スキーム内の後続の認証プラグインで使用するために変更することもできます。
この関数の書式は次のとおりです。
OBDLLEXPORT ObAnPluginStatus_t ObAnPluginFn( ObAnServerContext_t pServerContext, ObAnPluginFns_t pFuncBlock, ObAnPluginInfo_t pData ObAnPluginstatusMsg pResult );
表6-14で、この関数の入力パラメータについて説明します。
表6-14 入力パラメータ
変数 | 目的 |
---|---|
|
アクセス・サーバーのコンテキスト情報。 |
|
アクセス・サーバーに付属する関数のブロックへのハンドル。プラグインがデータを操作するために必要となります。 |
|
プラグインに渡すデータへのハンドル。 |
表6-15で、この関数の出力パラメータについて説明します。
この関数では、ObAnPluginstatus_tカテゴリの4つの値のうちいずれかを戻してください。
これらの実装されている関数の、これ以外の関数から、pResult文字列が送信された場合、アクセス・サーバーでは自動的にこの関数をコールして、プラグインによりメッセージの作成用に割り当てられたメモリーが削除されます。これは必ず行われるようにする必要があります。
この関数の書式は次のとおりです。
OBDLLEXPORT void ObAnPluginDeallocStatusMsg( ObAnPluginstatusMsg_t pStatusMsg );
表6-16で、この関数の入力パラメータについて説明します。
出力パラメータ
この関数には出力パラメータはありません。
この関数は何も戻しません。
例6-2は、C認証プラグイン関数の基本的な使用例を示しています。
例6-2 認証プラグインの例
/* * Copyright (c) 2005, Oracle Inc. All Rights Reserved. * * authn_api.c * Custom Authentication plugin. * * This implementation of the 5 authentication functions is built * into a DLL named SimpleAPI, and then, in a slightly modified * form, into a DLL called SimpleAPI2. * The differences between the two forms of the plugin are these: * 1) the second form writes the number 2 into all of its * log messages * 2) the second form does not make a check on the param * values or write context data back to the info structure. * * It shows: * * 1. Example implementations of all 5 functions. * 2. Examples for extracting data from many of the structures. * 3. An example of writing new data to the info structure. * 3. A simple way to log results for testing. */ #include "authn_api.h" #include <stdio.h> #include <string.h> #include <stdlib.h> #include <iostream.h> #include <malloc.h> #include <fstream.h> #ifdef _WIN32 #undef strcasecmp #define strcasecmp stricmp #endif /* * Implementation of ObAnPluginGetVersion * * The data logged by this function appears only once, when the * Plugin is first loaded. * */ OBDLLEXPORT const char* ObAnPluginGetVersion(void) { FILE *file = fopen("d:\\ANtestfile.txt", "a+"); fprintf (file, "\n%s%s\n", "sending Authn version, which is ",OB_AN_PLUGIN_VERSION); fclose(file); return OB_AN_PLUGIN_VERSION; } /* * Implementation of ObAnPluginInit * * The logged data appears only once, when the Plugin is first loaded. * */ OBDLLEXPORT ObAnPluginStatus_t ObAnPluginInit( ObAnServerContext_t pContext, ObAnpluginStatusMsg_t pResult) { // Values to be read in by this function are initialized. ObAnpluginStatus_t rtval; const char* pASPluginVersion = NULL; const char* pASInstallDir = NULL; FILE *file = fopen("d:\\ANtestfile.txt", "a+"); fprintf (file, "\n%s\n", "initializing"); if(pContext != NULL) { pASPluginVersion = pContext->AccessServerAnPluginAPIVersion; pASInstallDir = pContext->AccessServerInstallDir; fprintf (file, "\n%s%s\n", " version is ",pASPluginVersion); fprintf (file, "\n%s%s\n", " AS directory is ", pASInstallDir); } if((pASPluginVersion != NULL) && (strcmp(pASPluginVersion, OB_AN_PLUGIN_VERSION) == 0)) { rtval = ObAnPluginStatusContinue; *pResult = strdup("Success version check"); } else { /* * return failure, because the version provided by the AS * is not what was expected. */ rtval = ObAnPluginStatusAbort; } fclose(file); return rtval; } /* * Implementation of ObAnPluginTerminate * The logged data appears only when the Access Server terminates. */ OBDLLEXPORT ObAnPluginStatus_t ObAnPluginTerminate( ObAnServerContext_t pContext, ObAnPluginStatusMsg_t pResult) { FILE *file = fopen("d:\\ANtestfile.txt", "a+"); fprintf (file, "\n%s\n", "terminating gracefully"); *pResult = strdup("Success, terminated"); fclose(file); return ObAnPluginStatusContinue; } /* * Implementation of ObAnPluginDeallocStatusMsg * The logged data appears following each other function * that provides a presult. */ OBDLLEXPORT void ObAnPluginDeallocStatusMsg( ObAnPluginStatusMsg_t pResult) { FILE *file = fopen("d:\\ANtestfile.txt", "a+"); fprintf (file, "\n%s\n", "deallocating"); if(pResult != NULL && *pResult != NULL) { free(*pResult); *pResult = NULL; } fclose(file); } /* * Implementation of ObAnPluginFn */ OBDLLEXPORT ObAnpluginstatus_t ObAnPluginFn( ObAnServerContext_t pContext, ObAnPluginFns_t pFnBlock, ObAnPluginInfo_t pInfo, ObAnPluginStatusMsg_t pResult) { // rtval is initialized to allow continuing to the next // plugin ObAnPluginStatus_t rtval = ObAnPluginStatusContinue; ObAnPluginList_t list; ObAnPluginListItem_t item; ObAnASStatus_t writeres=100; // These are initialized, and get overwritten with real data // if any is found below const char* Resource; const char* Operation; const char* UserDN; const char* con1 = "cdummy1"; const char* con2 = "cdummy2"; const char* con3 = "cdummy3"; const char* param1 = "pdummy1"; /* this initialization is key to the example*/ const char* param2 = NULL; const char* param3 = "pdummy3"; FILE *file = fopen("d:\\testfilen_fn.txt", "a+"); fprintf (file, "\n%s\n", "Starting Fn"); // This is an example of getting data from the Creds member // of Info, using the predefined names Resource =pFnBlock->GetCredFn (pInfo->Creds,ObAnPluginRequestResource); Operation=pFnBlock->GetCredFn (pInfo->Creds,ObAnPluginRequestOperation); UserDN =pFnBlock->GetCredFn (pInfo->Creds,ObAnPluginRequesterDN); fprintf (file, "\n%s%s\n", "resource is ",Resource); fprintf (file, "\n%s%s\n", "operation is ",Operation); fprintf (file, "\n%s%s\n", "user DN is ",UserDN); // This set of code tries to extract the context information. // list = pFnBlock->GetDataFn(pInfo->Context,"isthereany"); // For the first use of the plugin, none has been set. // There is no context data, and no context name called isthereany. // // For the second use of the plugin, context data may be present // and if so will be read in. if (list != NULL){ fprintf(file, "\n%s\n","found context data!!"); item = pFnBlock->GetFirstItemFn(list); if (item != NULL){ con1 = pFnBlock->GetValueFn(item); item = pFnBlock->GetNextFn(item); if (item != NULL){ con2 = pFnBlock->GetValueFn(item); item = pFnBlock->GetNextFn(item); if (item != NULL){ param3 = pFnBlock->GetValueFn(item); } } } } fprintf (file, "\n%s%s\n", "first context is ",con1); fprintf (file, "\n%s%s\n", "second context is ",con2); fprintf (file, "\n%s%s\n", "third context is ",con3); // This set of code extracts the param information. // The value of param2, which is set, or not, in the Authentication // Scheme, controls the test. list = pFnBlock->GetDataFn(pInfo->Params,"myparam"); if (list != NULL){ item = pFnBlock->GetFirstItemFn(list); if (item != NULL){ param1 = pFnBlock->GetValueFn(item); item = pFnBlock->GetNextFn(item); if (item != NULL){ param2 = pFnBlock->GetValueFn(item); item = pFnBlock->GetNextFn(item); if (item != NULL){ param3 = pFnBlock->GetValueFn(item); } } } } fprintf (file, "\n%s%s\n", "first param is ",param1); fprintf (file, "\n%s%s\n", "second param is ",param2); fprintf (file, "\n%s%s\n", "third param is ",param3); *pResult = strdup("Success"); // -----> The second form of the plugin omits the code from here // If there is a value set for param2 under the myparam // name in the authentication scheme, then the logic here // returns allowed to the Access Server, and the next plugin // will not be used. // If there is no value set for param2, then the logic here // sets a value in the context data, which will be seen by the // next plugin. if (param2 != NULL){ rtval = ObAnPluginStatusAllowed; fprintf (file, "\n%s\n", "second param is not NULL"); } else { fprintf (file, "\n%s\n", "second param was NULL"); writeres=pFnBlock->SetDataFn (pInfo->Context, "isthereany", "context1", 0); fprintf (file, "\n%s%i\n", "AS returned", writeres); } // -----> to here fclose(file); return rtval; }
次のスクリーン・ショットは、このプラグイン例を使用する認証スキームを示しています。myparamパラメータ名に、2つ目の値が入力されていないことに注目してください。
このバージョンの認証スキームに対してこのサンプル・コードから得られるトレース情報は、次のとおりです。
sending Authn version, which is 5.0 initializing version is 5.0 AS directory is d:\netscape\server4\ws41sp6\docs\techpubs_fcs88\as\access deallocating in 2, sending Authn version, which is 5.0 in 2, initializing version is 5.0 AS directory is d:\netscape\server4\ws41sp6\docs\techpubs_fcs88\as\access Starting Fn resource is /test3 operation is GET user DN is cn=Rohit Valiveti,ou=Sales,ou=Dealer1k1,ou=Latin America,ou=Ford,o=Company,c=US first context is cdummy1 second context is cdummy2 third context is cdummy3 first param is thedata1 second param is (null) third param is pdummy3 second param was NULL AS returned 0 in 2, Starting Fn resource is /test3 operation is GET user DN is cn=Rohit Valiveti,ou=Sales,ou=Dealer1k1,ou=Latin America,ou=Ford,o=Company,c=US found context data!! first context is context1 second context is cdummy2 third context is cdummy3 first param is pdummy1 second param is (null) third param is pdummy3
次の各項では、プラグインAPIの開発環境について、サポート・ファイルのロケーションと主要なコンポーネントなどを説明します。
マネージ・コードAPI用サポート・ファイルのロケーション
アクセス・システムのアクセス・サーバー・コンポーネントのインストール時には、アクセス・サーバー・コンポーネントをインストール・ディレクトリASInstall_Dirに配置します。これは、たとえば次のようなロケーションです。
C:/COREid/access/oblix
認証プラグインAPIのサンプル・ファイルは、このディレクトリ内の次のロケーションにインストールされます。
ASInstall_Dir
/sdk/managed/authn++
authn_apiは、単純な認証プラグイン例のソース・コードであり、サンプル・プロジェクト・ファイルとなっています。このファイルには、APIのビルドおよび操作に不可欠な定義があります。アクセス・サーバーは、プラグインをロードする際、プラグイン内にauthn_api.hの4つの関数のセットが実装されているものと想定しています。
ビルドの手順
samplesディレクトリ下で、authn_apiディレクトリの内容を別のディレクトリ(たとえばmyplugin)にコピーします。
新規ディレクトリ内においてauthn.cファイルの内容を変更するか、追加でファイルを作成するかまたはその両方を行って、作成するプラグインに固有の、必要な機能を実装します。
開発したすべてのソース・コードがインクルードされコンパイルされるよう、プロジェクトを変更します。
プロジェクトをビルドします。
これにより、*.dllというプラグインが新しく作成されます。
プラグインの格納と例の実装の詳細は、「マネージ・コードAPIのプラグインのディレクトリ」を参照してください。
作成したプラグインは、アクセス・サーバーを稼働するシステム内の次のディレクトリに格納する必要があります。
ASInstall_Dir
/lib
アクセス管理者は、プラグインを認証スキーム内に適切に構成するために、プラグインのファイル名とその必須およびオプションのデータ名を把握している必要があります。プラグインをマネージ・コードとして記述する場合は、アクセス・サーバーがプラグインを正しく実行できるように、プラグインをマネージ・コードとして明示的に識別する必要があります。また、コードを実行する名前空間も明示する必要があります。
「Cの認証プラグインの例」の後に、サンプル・ページがあります。サンプル・ページには、この例をサポートする認証スキームが示されています。マネージ・コードの認証プラグインには、obtype="managed"とobnamespace="namespace"の2つのプラグイン・パラメータを指定する必要があります(ここで、namespaceはマネージ・コードの名前空間)。たとえば、マネージ・コードを使用する場合、authn_apiプラグインの「パラメータ」テキスト・ボックスに、次を入力します。
obtype="managed", obnamespace="sample"
認証スキームの構成の詳細は、『Oracle Access Managerアクセス管理ガイド』を参照してください。
この項では、C APIで使用される様々なタイプの定数データおよび変数データについて説明します。
managed_plugin_interface.hには、一部の関数で引数用の固定値として使用される値がいくつか事前定義されています。
pubic_value class AnDefines { static string *ObAnPluginResourceRequest = S"Resource"; static string *ObAnPluginRequestOperation = S"Operation"; static string *ObAnPluginRequesterIP = S"RequesterIP"; static string *ObAnPluginRequesterDN = S"RequesterDN"; static string *OB_AN_PLUGIN_VERSION = S"8.0"; };
値の名前 | 意味 |
---|---|
OB_AN_PLUGIN_VERSION |
ObAnPluginGetVersionをコールする場合は、この値をアクセス・サーバーに戻す必要があります。ヘッダー・ファイル内の値は製品のリリースに応じた値となります。 |
ObAnPluginRequestResource |
ホスト名とポートの後のリソース。例: /basic/page.htm 。 |
ObAnPluginRequestOperation |
リソースに対して実行する操作。 |
ObAnPluginRequesterDN |
DNが認証プラグインで設定されている場合、ここでの定義によって他のプラグインからそのDNにアクセスできます。DNを設定する認証プラグインの名前は常にcredential_mappingです。
DNは、カスタム認証プラグインでも、SetCredFnをコールして事前設定できます。 |
ObAnPluginRequesterIP |
このリクエストを発行したクライアントのIPアドレス。 |
アクセス・サーバーおよびAPIでは、インタフェースを使用して、プラグインで使用できるようアクセス・サーバーが管理するデータ構造を操作します。これらのインタフェースの名前と説明を、次の各項で説明します。
インタフェース | 目的 |
---|---|
IObAnPluginSVData |
単一値データを取得するための関数が用意されているインタフェース。ObAnPluginInfoインタフェースからのCredsおよびActionInfoの検索に使用します。 |
IObAnPluginMVData |
複数値データのための関数が用意されているインタフェース。ObAnPluginInfoインタフェースからのParamsおよびContextの検索に使用します。 |
IObASPluginListItem |
リスト内の項目を指すインタフェース。 |
IObAnPluginInfo |
アクセス・サーバーからの情報とプラグインで生成されたデータを取得する関数が用意されているインタフェース。 |
IObAnServerContext |
アクセス・サーバーに関する一般情報を取得する関数が用意されているインタフェース。 |
アクセス・サーバーでは、関連するデータ項目を名前付きの構造体にまとめ、メモリーを割り当てて転送します。構造体は開発者からは不透明です。つまり、構造体を使用してアクセス・サーバーと情報をやり取りすることはできますが、構造体の編成方法や構造体に含まれるデータの形式は変更できません。構造体の内容は、場合によっては変更できます。
認証プラグインAPIで使用されるインタフェースを次に示します。
このインタフェースでは、プラグインで必要となるアクセス・サーバー関連の情報が提供されます。
public _gc _interface IObAnServerContext { _property String* get_AccessServerInstallDir(); _property String* get_AccessServerAnPluginAPIVersion(); };
データ型/名前 | 目的 |
---|---|
get_AccessServer InstallDir |
アクセス・サーバーのインストール・ディレクトリへのパス。例: COREid/Access。/oblixディレクトリが含まれていないことに注意してください。 |
get_AcessServerAn PluginAPIVersion |
アクセス・サーバーのインスタンスでサポートされる認証プラグインAPIのうち、最も古いバージョン。 |
アクセス・サーバーにより、認証ルールで設定されたデータを持つオブジェクトが作成され、このインタフェースがプラグインに提供されます。プラグインでは、処理の進行とともに、構造体内部のデータが変更され、場合によっては新規データが追加されます。認証スキーム内で複数のプラグインが実行される場合は、ルール内の最初のプラグインに対する変数情報を設定してスキーム内の1つのプラグインから別のプラグインに情報を渡す手段ともなります。
public _gc _interface IObAnPluginInfo { IObAnPluginSVData* get_Creds(); IObAnPluginMVData* get_Params(); IObAnPluginMVData* get_Context(); IObAnPluginSVData* get_ActionInfo(); };
関数 | 目的 |
---|---|
get_Creds |
このcreds関連の関数の構成要素は、リソースへのアクセスを試行しているユーザーまたはアプリケーションから送信されたすべての情報です。このデータにはプラグインによる追加や変更が可能です。このデータは次のプラグインへと順に渡されます。したがって、このデータはプラグインにおいて、認証スキーム内で次に指定されているプラグインとの通信に使用できます。構造体のリスト内には、Resource、Operation、RequesterDNおよびRequesterIPという4つの事前定義された名前がアクセス・サーバーによって用意されています。 |
get_Params |
プラグイン構成に指定されているパラメータ。このデータは、プラグイン内部では追加や変更が可能ですが、次のプラグインには渡されません。 |
get_Context |
プラグインで作成されたデータ。このデータにはプラグインによる追加や変更が可能です。このデータは次のプラグインへと順に渡されます。 |
get_ActionInfo |
プラグイン構成に指定されているアクション情報。このデータにはプラグインによる追加や変更が可能です。アクションを設定して次のプラグインへ渡すことも可能ですが、アクション情報は最終的にアクセス・サーバーで使用されることに留意しておく必要があります。 |
このインタフェースは、ネストされた4つの配列(構造体メンバー)からなる配列と考えることもできます。各メンバーには、1つ以上の名前が格納されます。
値を取得するには、値を取得する資格証明の名前を入力引数としてIObAnPluginSVDataインタフェース内のGetCred関数を使用します。この関数により、単一の値が戻されます。GetActionも同様に操作できます。
IObAnPluginSVData型の構造体メンバーの配列は、名前と各名前に関連付けられた単一の値のセットからなります。たとえば、credsメンバーは次のような構造を持つと考えることができます。
名前 | 値 |
---|---|
Resource | 1つの値 |
Operation | 1つの値 |
RequesterDN | 1つの値 |
RequesterIP | 1つの値 |
ユーザーが作成した資格証明の名前 | 1つの値 |
関数 | 目的 |
---|---|
GetCred |
この関数では、資格証明情報のハンドルおよび名前を基に、資格証明の名前の値が取得されます。ユーザーの認証レベルは、ユーザーがログインしたスキームやリソースによって限定されます。たとえば、ユーザーがActive Directoryまたはリバース・プロキシのどちらからログインしたかに基づいて認証レベルを設定できます。この情報をカスタム・プラグインで抽出するには、資格証明リストに設定されているObAuthntSchemeLevel変数をアクセス・サーバーに問い合せます。 |
SetCred |
この関数では、資格証明情報へのハンドル、変更する資格証明の名前、および格納する値を基に、プラグインに渡す資格証明情報のうち、指定された名前の値が設定されます。名前がすでに存在する場合は、現在の値が上書きされます。存在しない場合は、名前と値が追加されます。 |
GetAction |
この関数では、アクション情報へのハンドル、取得するアクションの名前およびタイプを基に、アクション情報を取得します。アクションの名前とタイプの組合せに対して、1つの値のみを戻すことができます。 |
SetAction |
この関数では、アクション情報へのハンドル、変更するアクションの名前、格納する値およびアクションのタイプを使用して、プラグインに渡すアクション情報の値を設定します。名前とタイプの組合せがすでに存在する場合は、その値が上書きされます。存在しない場合は、名前と値が追加されます。 |
IObAnPluginMVDataインタフェースには、1つ以上の項目からなるリストに含まれているオブジェクトを操作するための関数が用意されています。各項目には値があります。
関数 | 目的 |
---|---|
get_Data |
この関数では、IObAnPluginInfoインタフェースのParamsメンバーまたはContextメンバーの複数値データからなるリストへのハンドルが戻されます。プラグインがハンドルの取得後にそのリストから情報を抽出するには、リスト操作関数をGetFirstItemFns、GetValueFn、GetValueFnなどのように使用する必要があります。 |
set_Data |
この関数では、資格証明情報へのハンドル、変更する資格証明の名前および格納する値を基に、プラグインに渡す資格証明情報のうち、指定された名前の値が設定されます。名前がすでに存在する場合は、現在の値が上書きされます。存在しない場合は、名前と値が追加されます。 |
アクセス・サーバーおよびAPIが通信用として使用する関数の多くは、ステータス値を戻すようになっています。これらの戻り値は、ここで説明するように、複数のカテゴリですべて事前に定義されています。
このカテゴリの値は、APIがアクセス・サーバーに実行するアクションを通知するために戻すアクション・フラグです。
_value enum ActionType { ObAnSuccessRedirect = 0, ObAnFailRedirect = 1, ObAnSuccessProfileAttrs = 2, ObAnFailProfileAttrs = 3, ObAnSuccessFixedVals = 4, ObAnFailFixedVals = 5 };
名前 | 説明 |
---|---|
ObAnSuccessRedirect |
認証が成功した場合に、認証ルールに定義されたとおりにリダイレクションURLを設定するようアクセス・サーバーへ通知します。 |
ObAnFailRedirect |
認証が失敗した場合に、認証ルールに定義されたとおりにリダイレクションURLを設定するようアクセス・サーバーへ通知します。 |
ObAnSuccessProfileAttrs |
認証が成功した場合に、認証ルールで指定された値(プラグインで追加されることもある)を使用して、アクション用のプロファイル属性を設定するようアクセス・サーバーへ通知します。 |
ObAnFailProfileAttrs |
認証が失敗した場合に、認証ルールで指定された値(プラグインで追加されることもある)を使用して、アクション用のプロファイル属性を設定するようアクセス・サーバーへ通知します。 |
ObAnSuccessFixedVals |
認証が成功した場合に、認証ルールに定義された固定値(プラグインで追加されることもある)を設定するようアクセス・サーバーへ通知します。 |
ObAnFailFixedVals |
認証が失敗した場合に、認証ルールに定義された固定値(プラグインで追加されることもある)を設定するようアクセス・サーバーへ通知します。 |
プラグインでは、認証の試行結果を示すために、このカテゴリの値のいずれかをアクセス・サーバーへ戻す必要があります。
_value enum ObAnPluginStatus { ObAnPluginstatusContinue = 0, ObAnPluginstatusAllowed = 1, ObAnPluginstatusDenied = 2, ObAnPluginstatusAbort = 3 };
値の名前 | 意味 |
---|---|
ObAnPluginStatusAbort |
この値は、認証の処理で致命的なエラーが発生したことを示すために設定します。この認証リクエストの処理は、このプラグインで停止します。 |
ObAnPluginStatusAllowed |
資格証明が処理され、認証が成功しました。これより後の認証プラグインは処理されません。 |
ObAnPluginStatusDenied |
資格証明が処理され、認証が失敗しました。処理はこの関数で停止します。認証は失敗になります。 |
ObAnPluginStatusContinue |
認証の処理は、この関数の後も続行します。認証スキーム内のすべてのプラグインからこの値が戻された場合、認証は成功したことになります。 |
プラグインがアクセス・サーバーに組込み関数の1つを実行するように求めると、アクセス・サーバーではその関数の実行が試みられ、このカテゴリの値のいずれかが戻されます。
_value enum ASStatus{ bAnASStatusSuccess = 0, bAnASStatusFailed };
値の名前 | 意味 |
---|---|
ObAnASStatusSuccess |
アクセス・サーバーで操作が正常に実行されました。 |
ObAnASStatusFailed |
アクセス・サーバーで操作が実行されませんでした。このエラーの原因で最も多いのは、変更が許可されていない値をプラグインで変更しようとしたというものです。たとえば、単一の値のみが許可されている配列メンバーである名前に、2つ目の値を追加しようとした場合などです。 |
開発者は、この項で説明するすべての関数を、managed_plugin_interface.h内に用意されているプロトタイプに従ってプラグイン内に実装する必要があります。
認証プラグインには、次のような関数を含んだクラスを定義する必要があります。
public _gc class ObAuthzPlugin { public: ObAuthnPlugin(); String* ObAnPluginGetVersion(); IObAuthnPlugin::Status ObAnPluginInit Oblix::IObAnServerContext* context, String* msg); ObAuthnPlugin::Status ObAnPluginFN(Oblix::IObAnServerContext* context, Oblix::IObAnPluginInfo* info); IObAuthnPlugin::Status ObAnPluginTerminate (Oblix::IObAnServerContext* context, String* msg); };
アクセス・サーバーではこれらの関数がこの順序でコールされます。
ObAnPluginGetVersion: プラグインの初回のロード時にコールされます。
ObAnPluginInit: プラグインの初回のロード時にコールされます。
ObAnPluginFn: 毎回のプラグイン使用時にコールされます。
ObAnPluginTerminate: アクセス・サーバーの停止時またはプラグインのアンロード時にコールされます。
この関数は、プラグインがロードされた直後にアクセス・サーバーからコールされます。プラグインからは、そのビルド時に使用されたライブラリのバージョン番号が戻されます。アクセス・サーバーでは、このバージョンを使用して、プラグインがサポート可能かどうかを判断します。つまり、古いバージョンのアクセス・サーバーがより新しいバージョンのAPIのサポートを求められていないかや、新しいバージョンのアクセス・サーバーがサポートの終了したバージョンのプラグインと連携するように求められていないかが、アクセス・サーバーで把握されます。
この関数の書式は次のとおりです。
OBDLLEXPORT const char* ObAnPluginGetVersion(void);
入力パラメータ
この関数には入力パラメータはありません。
出力パラメータ
この関数には入力パラメータはありません。
この関数からは、認証プラグインのバージョンが戻されます。これは、authn_api.hファイルの次の行で設定されている値です。
#define OB_AN_PLUGIN_VERSION "X.X"
この関数は、アクセス・サーバーにより、バージョンが確認された直後にコールされます。この関数ではプラグインの作業領域が初期化されます。初期化作業には、データベースへの接続やプラグインのグローバル・データの初期化といったタスクがあります。この関数と、pResultの文字列を戻す他の2つの関数で、pResultの文字列を戻すためのメモリーを割り当てることも必要になります。このメモリーの割当ては、アクセス・サーバーで自動的にObAnPluginDeallocStatusMsg関数がコールされることによって解除されます。
この関数の書式は次のとおりです。
OBDLLEXPORT ObAnPluginStatus_t ObAnPluginInit( ObAnServerContext_t pServerContext, ObAnPluginStatusMsg_t pResult };
入力パラメータ
変数 | 目的 |
---|---|
pServerContext |
アクセス・サーバーのコンテキスト情報 |
出力パラメータ
変数 | 目的 |
---|---|
pResult |
関数によって報告される結果メッセージ |
この関数からは、ObAnPluginStatus_tカテゴリのObAnPluginStatusContinueまたはObAnPluginStatusAbortのいずれかの値を戻す必要があります。
この関数は、アクセス・サーバーの終了直前にアクセス・サーバーからコールされます。この関数は、プラグイン内で設定した作業領域を消去し、プラグインで開いたデータベースなど他のアプリケーションとの接続を解除するために、記述する必要があります。
入力パラメータ
変数 | 目的 |
---|---|
pServerContext |
アクセス・サーバーのコンテキスト情報 |
出力パラメータ
変数 | 目的 |
---|---|
pResult |
関数によって報告される結果メッセージ |
この関数からは、ObAnPluginStatus_tカテゴリのObAnPluginStatusContinueまたはObAnPluginStatusAbortという2つの値のいずれかを戻す必要があります。
この関数は、プラグイン情報およびサーバー・コンテキストを使用して実際のカスタム認証作業を実行するようプラグインにリクエストするために、アクセス・サーバーからコールされます。また、この関数では、プラグイン情報の一部を、スキーム内の後続の認証プラグインで使用するために変更することもできます。
入力パラメータ
変数 | 目的 |
---|---|
pServerContext |
アクセス・サーバーのコンテキスト情報。 |
pFuncBlock |
アクセス・サーバーに付属する関数のブロックへのハンドル。プラグインがデータを操作するために必要となります。 |
pData |
プラグインに渡すデータへのハンドル。 |
出力パラメータ
変数 | 目的 |
---|---|
pData |
プラグインによって変更されたデータのハンドル |
pResult |
関数によって報告される結果メッセージ |
この関数では、ObAnPluginstatus_tカテゴリの4つの値のうちいずれかを戻してください。
プラグインの単体テストでは、この章にあげた例のように結果をファイルへ書き込むのが最善の方法です。pResultのテキストは、認証が失敗した場合に、Solarisで動作するアクセス・サーバーの監査ログにのみ、取得されます。結果をファイルに書き込む場合、ファイルを格納するディレクトリに書き込むための適切な権限があることを確認してください。
パフォーマンスに関する責務は開発者にあり、プラグインの設計時に考慮する必要があります。1つの認証リクエストの処理に要する合計時間は、リクエストの処理時に起動されるすべてのプラグインのパフォーマンスによって決まります。
プラグインは、アクセス・サーバーによって信頼されています。事前構成情報をプラグインに提供する場合、アクセス・チェックは実行されません。
プラグイン内に、メモリーまたはアクセスの違反、分断またはバス・エラー・フォルトといったコーディング上の問題があると、アクセス・サーバーが失敗する可能性があります。
プラグインではオプションのパラメータを使用できます。通常、これらのパラメータは、アクセス管理者がスキームの作成時に入力します。プラグインは、これらのパラメータの値が指定されない状況にも問題なく対応できる必要があります。
リクエストが理由なく失敗したように見える場合は、共有ライブラリへのパスが正しいかどうかを確認します。共有ライブラリはASInstall_Dir/
libにある必要があります。また、認証スキームで参照している共有ライブラリ名の綴りが正しいかどうかも確認します。
ObAuthnplug-inInit関数をコールしてもAbortが戻されないことを確認します(認証の失敗に対する監査をオンにして、監査ログに何も記録されていないことを確認します)。
アクセス・システムの標準インストールには、認証プラグインがいくつか含まれています。この項では、これらのプラグインについて説明します。これらのプラグインを独自のカスタム・プラグインと併用することで、認証スキームを作成できます。
アクセス・システムでは、チャレンジ・メソッドがいくつかサポートされています(Basic、X.509証明書およびフォーム)。詳細は、『Oracle Access Managerアクセス管理ガイド』を参照してください。ここで説明する各プラグインと各プラグインで使用できるチャレンジ・メソッドは、次のとおりです。
資格証明マッピング: すべてのメソッド
パスワード検証: Basic、フォーム
証明書デコード: X.509証明書
選択フィルタ: すべてのメソッド
NT/Windows 2000: Basic、フォーム
SecurID: フォーム
このプラグインの詳細は次のとおりです。
特性 | 説明 |
---|---|
名前 | credential_mapping |
目的 | ユーザーが入力した情報をディレクトリ内の有効な識別名(DN)にマップすること。 |
結果 | 指定した条件にDNが1つのみ一致した場合に、認証スキームの実行が続行されます。obMappingBaseおよびobMappingFilterが資格証明のリストに追加され、資格証明内のUIDがDNの値に設定されます。DNが戻されないかまたは複数のDNが戻されると、認証は失敗します。 |
依存性 | DNを使用する必要がある場合には、このプラグインがスキーム内に存在する必要があります。 |
obMappingBase : LDAP検索用のベースDN。省略するか空白にした場合は、ディレクトリ・ベースが使用されます。 |
|
obMapping Filter : LDAP検索用のフィルタ。このパラメータは必須です。 |
|
パラメータ | ObDomain : Active Directoryフォレストの特定のディレクトリに対する認証を、Basic認証メソッドで行う場合にのみ使用されます。このパラメータの値は、構成済ディレクトリ・サーバー・プロファイル名のうちの1つです。
|
パラメータ例 | obMappingBase="o=Company,c=US",obMappingFilter="(&(objectclass=inetOrgPerson)(uid=%userid%))" |
デフォルトでは、資格証明マッピングのキャッシュはオンになっています。次の表に、obEnableCredentialCacheの値を示します。
obEnableCredentialCache
値 | 解釈 |
---|---|
値なし | 資格証明マッピングのキャッシュはオン |
true | 資格証明マッピングのキャッシュはオン |
false | 資格証明マッピングのキャッシュはオフ |
次に、資格証明マッピングのキャッシュをオフにしたcredential_mapping認証プラグインの例を示します。
credential_mapping obMappingBase="%domain%",obMappingFilter="(&(&(objectclass=user)(samaccountname= %userid%))(|(!(obuseraccountcontrol=*))(obuseraccountcontrol=ACTIVATED)))",obdom ain="domain",obEnableCredentialCache="false"
obEnableCredentialCacheパラメータを設定する手順
「システム・コンソール」で、「アクセス・システム構成」を選択します。
「認証スキーム」をクリックします。
変更する「認証スキーム」を選択します。
「変更」をクリックします。
credential_mappingプラグインにobEnableCredentialCache="false"パラメータを追加します。
注意: 認証リクエストのコンテキスト固有のデータの詳細や、リクエストされた元のURLをパスワード変更サーブレットに渡すフォーム・ベース認証の詳細は、『Oracle Access Managerアクセス管理ガイド』を参照してください。 |
このプラグインの詳細は次のとおりです。
特性 | 説明 |
---|---|
名前 | validate_ password |
目的 | ブラウザに入力されたパスワードをディレクトリ内のユーザーのパスワードに照らして検証すること。 |
結果 | ユーザーが入力したパスワードがそのユーザーのディレクトリ・エントリ内のパスワードに一致した場合、認証スキームの実行が続行されます。一致しない場合は、認証が失敗します。資格証明のリストには何も追加されません。 |
依存性 | このプラグインには有効な識別名(DN)が必要なため、credential_mappingプラグインをコールした後でコールすることをお薦めします。 |
パラメータ | obCredentialPassword : パスワード・フィールドの名前を指定します。このパラメータは最初にリストする必要があります。
|
パラメータ例 | obCredentialPassword="password"obAnonUser="cn=anonymous, o=Company, c=US" |
このプラグインの詳細は次のとおりです。
特性 | 説明 |
---|---|
名前 | cert_decode |
目的 | X.509証明書をデコードし、その証明書の要素であるサブジェクトと発行者のDNを抽出すること。 |
結果 | 証明書のデコードが成功すると、各要素ごとに、接頭辞がcertSubjectまたはcertIssuerの資格証明が挿入されます。たとえば、証明書のサブジェクト名がgivenName=somenameの場合、プラグインによって資格証明certSubject.givenName=somenameが資格証明リストに追加されます。デコードが失敗すると、認証は失敗します。 |
依存性 | ブラウザから資格証明の一部としてX.509証明書を提示する必要があります。 |
パラメータ | なし。 |
注意 | このプラグインの詳細は、『Oracle Access Managerアクセス管理ガイド』を参照してください。 |
このプラグインの詳細は次のとおりです。
特性 | 説明 |
---|---|
名前 | Selection Filter Plug-In |
目的 | ユーザーの資格証明にフィルタを適用すること。 |
結果 | 資格証明がフィルタで指定されている基準を満たしている場合は、その資格証明は受け入れられ、認証が続行されます。満たしていない場合は、認証が失敗します。 |
依存性 | このプラグインを実行する前に、ObSelectionfilterに代入するデータが資格証明内に存在している必要があります。たとえば、この表に示されているパラメータ例の場合、certIssuer情報を提供するためcert-decodeをselection-filterの前に実行する必要があります。 |
パラメータ | obSelectionFilter : ユーザーの資格証明に適用するフィルタ。 |
パラメータ例 | obSelectionFilter="(%certIssuer.CN%=Verisign Class I CA)" |
このプラグインの詳細は次のとおりです。
特性 | 説明 |
---|---|
名前 | authn_windows |
目的 | 資格証明内のユーザー名、パスワードおよびドメインをNTドメイン、Windows 2000ドメインまたはWindows 2000 Kerberosに対して認証すること。Basicチャレンジ・メソッドを使用する場合、ドメインを「ユーザー名」フィールドに入力する必要があります。一方、フォーム・チャレンジ・メソッドを使用する場合は、ユーザー向けのフォームに別途ドメイン名を入力するフィールドを用意します。 |
依存性 | Basicチャレンジ・メソッドを使用する場合、ドメイン名は「ドメイン\名前」の形式でユーザー名フィールドに入力する必要があります。フォーム・チャレンジ・メソッドを使用する場合は、ドメイン専用のフィールドを設けるようフォームを設計します。 |
パラメータ | ntusername : ユーザー名指定用のパラメータ名。
|
パラメータ例 | ntusername="userid"
|
このプラグインの詳細は次のとおりです。
特性 | 説明 | |||
---|---|---|---|---|
名前 | authn_securid | |||
目的 | ユーザーのSecurIDトークンからの資格証明をSecurID ACE Serverに問い合せて認証すること。SecurIDのネクスト・トークンコード・モードおよびNew PINモードの操作をサポートすること。 | |||
結果 | ACE Serverから成功が戻された場合は、認証が続行されます。成功が戻されなかった場合は、認証は失敗します。 | |||
依存性 | なし。 | |||
パラメータ | 名前 | デフォルト | 必須/オプション | コメント |
fullformdir |
なし | 必須 | SecurIDフォームへのフルパス。 | |
machine |
なし | 必須 | SecurID認証を行うWebサーバーの名前。これは、SecurID認証をすべてリダイレクトする場合のリダイレクト先とするWebサーバー名です。例: securid.abc.com:8888。 | |
username |
login | オプション | サンプルのフォームを使用する場合は、この値をloginに設定します。この値は、このプラグインではcredsチャレンジ・パラメータに入力し、資格証明マッピング・プラグインではObMappingFilterパラメータに入力します。 | |
passcode |
password | オプション | サンプルのフォームを使用する場合は、この値をpasswordに設定します。別の値を指定するには、プラグインのcredsチャレンジ・パラメータに指定する必要があります。 | |
formdir |
<WebGate_install_ dir>/ securid-forms/ | オプション | WebGateのインストール先からSecurIDフォームへの相対パス。最後にスラッシュ(/)が必要です。別のパスを使用するには、このパラメータおよびfullformdirに新規の値を使用して、プラグインの構成時にformチャレンジ・パラメータの値を変更します。 | |
httpType |
http:// | オプション | SecurID認証を処理するWebサーバーの種類。有効な値はhttp://およびhttps://の2つです。 | |
choiceLabel |
choice | オプション | ユーザーによって選択されるPIN生成方法を表示する、HTMLフォーム上のフィールド名。これは、credsチャレンジ・パラメータを使用して設定します。 | |
newpinLabel |
newpin | オプション | ユーザーによって入力される新しいPINを表示する、HTMLフォーム上のフィールド名。これは、credsチャレンジ・パラメータを使用して設定します。 | |
newpinLabel2 |
newpin2 | オプション | ユーザーによって再入力される新しいPINを表示する、HTMLフォーム上のフィールド名。これは、credsチャレンジ・パラメータを使用して設定します。 | |
パラメータ例 | fullformdir= "<WebGate_install_dir> /access/oblix/securid-forms/"machine="securid.abc.com:8888 " |