C 用のエージェント API
エージェント API は、ポリシー サーバと連携して、ポリシー サーバの認証および認可の機能を活用するためのカスタム エージェント アプリケーションを作成します。また、アプリケーション固有データを送信するためのセキュアな通信トンネルを構築することもできます。エージェント API を直接または(別のエージェントを介して)間接的に使用して構築されるアプリケーションを作成する開発者は、以下に示す実装特有の詳細を意識する必要がありません。
casso11jp
エージェント API は、ポリシー サーバと連携して、ポリシー サーバの認証および認可の機能を活用するためのカスタム エージェント アプリケーションを作成します。また、アプリケーション固有データを送信するためのセキュアな通信トンネルを構築することもできます。エージェント API を直接または(別のエージェントを介して)間接的に使用して構築されるアプリケーションを作成する開発者は、以下に示す実装特有の詳細を意識する必要がありません。
- LDAP ディレクトリ、SQL データベース、Windows ドメインなどのユーザ ネームスペース
- ユーザ名とパスワードによる単純な認証方式や、PKI システムの複雑な認証方式
- グループ メンバシップまたは個別のプロファイルデータに基づく認可
エージェント API のその他の利点としては、全面的なセッション管理サポート、自動暗号化キー ロールオーバ、リアルタイム ポリシー更新などがあります。
エージェント API には、ポリシー サーバへのローカルまたはリモート アクセス タイプがあります。
CA Single Sign-on
エージェントについてCA Single Sign-on
エージェントはエージェント API のクライアントです。SiteMinder エージェントは、ポリシー サーバによって提供されるアクセス制御ポリシーを適用します。ポリシー サーバは、リソースに関する情報を持たない汎用のポリシー エンジンです。エージェントは、リソースの解釈を定義し、許可のないユーザからリソースを保護するゲート キーパーとして機能します。各種のリソースを保護するためにさまざまなエージェント タイプが用意されています。一部のエージェント タイプは、
CA Single Sign-on
製品の一部として出荷される事前定義された標準エージェントです。たとえば、Web サーバに HTTP アクセス制御を提供する Web エージェントなどです。また、エージェント API を使用して、カスタム エージェントを実装することもできます。エージェント API を使用してアプリケーションを作成する際に、コンテキストに応じたさまざまな方法でユーザの認証および認可を行うカスタム エージェントを作成できます。たとえば、以下の機能を実装する FTP 転送のエージェントを作成できます。
- (基本的な名前とパスワードの認証ではなく)証明書ベースの認証
- 個々のユーザの認可レベルに基づいたアップロードおよびダウンロード
SDK を使用してカスタム エージェントを構築する場合は、その SDK のバージョンに対応したバージョンの
CA Single Sign-on
ポリシー サーバでカスタム エージェントを実行する必要があります。エージェント初期化
エージェントがユーザに代わって作業を実行できるようになるには、先に Sm_AgentApi_Init() をコールすることにより 1 つまたは複数のポリシー サーバへの接続を初期化する必要があります。Sm_AgentApi_Init() をコールすることにより、フェールオーバ モードや接続プール サイズなどの接続パラメータを指定できます。このコールは TCP 接続を作成するものであり、通常、エージェント インスタンス 1 つにつき 2 回以上実行する必要はありません。
複数の API インスタンスを初期化できます(個別のポリシー ストアを複数使用するポリシー サーバと連係して操作する場合など)。
初期化直後、エージェントは、構造体 Sm_AgentApi_ManagementContext_t で設定されたコマンド SM_AGENTAPI_MANAGEMENT_SET_AGENT_INFO を使用して Sm_AgentApi_DoManagement() をコールすることにより、ポリシー サーバにそのバージョン情報を通知する必要があります。実際の情報は、エージェントに関する十分な情報(ビルド番号、バージョン番号など)が含まれる任意の文字列を使用できます。文字列はポリシー サーバ ログに記録されます。
エージェント ディスカバリ
Single Sign-On
管理者は、エージェント ディスカバリを使用して、数年にわたって展開されているエージェントを含め、さまざまなタイプのエージェントのインスタンスを追跡できます。エージェント インスタンスは、任意のタイプのエージェント(たとえば Web エージェント、カスタム エージェント、ERP エージェント)が可能です。エージェント ディスカバリの認識範囲に含めるためには、エージェントがアクティブで、ポリシー サーバと通信中であることが必要です。5.x 以降のエージェントのみ追跡できます。r12.5 以前に作成されたエージェントの場合、エージェントの識別に IP アドレスとトラステッド ホストの組み合わせが使用されます。同じエージェントでも、この組み合わせが変わると、1 つエージェントに対して複数のエントリが生じることになります。
各 r12.5 エージェント インスタンスは固有の GUID により識別されます。GUID は設定ファイルに保存されています。Sm_AgentApi_SetAgentInstanceInfo() 関数は、エージェント ディスカバリのプロセスにおいて中心的な役割を果たします。Sm_AgentApi_SetAgentInstanceInfo() 関数は、そのエージェント インスタンスに対して指定された GUID が設定にあることを判別します。GUID が検出された場合、そのエージェントはすでに検出済みであり、追跡が可能です。GUID が検出されない場合、この関数は、そのエージェント インスタンスに対して GUID を作成し、後で呼び出すことができるように、この GUID を設定ファイルに書き込みます。複数のエージェント インスタンスで 1 つの設定ファイルを共有することはできません。
エージェント API は、エージェント情報を登録するために以下を提供します。
int SM_EXTERN Sm_AgentApi_SetAgentInstanceInfo (const void* pHandle,Sm_AgentApi_AgentDiscovery_t arrParams[], int nCount);
pHandle は、Sm_AgentApi_Init によって生成されるハンドルであり、すべてのエージェント API 呼び出しで使用されます。
- arrParams[] は、m_AgentApi_AgentDiscovery_t データ タイプによって定義される名前/値ペアの配列です。
- nCount は、arrParams で渡される要素数です。
SmAgentAPi.h の以下のマクロは、arrParams で渡すことができる、サポートされる名前付き要素を定義します。これらはすべてオプションです。また、エージェントは、関連する情報を必要に応じて提供します。
#define SM_AGENT_INSTANCE_AGENTPRODUCTTYPE "AGENTPRODUCTTYPE"
例: WebAgent
#define SM_AGENT_INSTANCE_AGENTPRODUCTVERSION "AGENTPRODUCTVERSION"
例: 1.0
#define SM_AGENT_INSTANCE_AGENTPRODUCTSUBTYPE "AGENTPRODUCTSUBTYPE"
例: IIS
#define SM_AGENT_INSTANCE_AGENTPRODUCTOSTYPE "AGENTPRODUCTOSTYPE"
例: Linux
#define SM_AGENT_INSTANCE_AGENTIDFILE "AGENTIDFILE"
一意の GUID を格納するために使用される、書き込み権限が付与されたテキスト ファイルへの有効なパス。空のファイルへのパスが渡された場合、エージェント API は新しい GUID を生成し、このファイルに書き込みます。今後、エージェント インスタンスを一意に識別するために、この GUID を読み取りおよび使用できます。
#define SM_AGENT_INSTANCE_ACONAME "ACONAME"
エージェントによって使用される有効な ACO 名。
#define SM_AGENT_INSTANCE_HCONAME "HCONAME"
エージェントによって使用される有効な HCO 名。
#define SM_AGENT_INSTANCE_FIPSMODE "FIPSMODE"
ホスト登録がエージェントによって使用される場合、SmHost.conf 内の値ストア。
Sm_AgentApi_SetAgentInstanceInfo が正常に呼び出された後、AgentAPI は、ハートビートなど、バックグラウンドでポリシー サーバへの定期的な呼び出しを行います。エージェントからこの API を初めて呼び出すと、ポリシー サーバによって使用されるエージェント ディスカバリ テーブルに、新しい一意のレコードが作成されます。GUID が利用可能な場合、このレコードは GUID によってインデックス付けされます。有効な GUID が使用されるようにするため、エージェント ID ファイルを提供することをお勧めします。この値がない場合、エージェント インスタンスを
CA Single Sign-on
エージェント システムにある一意のエンティティとして追跡および保持できません。正しい呼び出しシーケンスは、以下のとおりです。
Sm_AgentApi_InitSm_AgentApi_SetAgentInstanceInfo..other calls to PS..Sm_AgentApi_Uninit
pAgentApiHandle を作成するために Sm_AgentApi_Init が先に呼び出されていることを前提とするソースの例を以下に示します。
Sm_AgentApi_AgentDiscovery_t arrParams[8] = {{SM_AGENT_INSTANCE_AGENTPRODUCTTYPE, "CustomAgent"},{SM_AGENT_INSTANCE_AGENTPRODUCTVERSION, "1.0"},{SM_AGENT_INSTANCE_AGENTPRODUCTSUBTYPE, "IIS"},{SM_AGENT_INSTANCE_AGENTPRODUCTOSTYPE, "Windows"},{SM_AGENT_INSTANCE_AGENTIDFILE, "c:\idfile.txt"},{SM_AGENT_INSTANCE_ACONAME, "MyACO"},{SM_AGENT_INSTANCE_HCONAME, "MyHCO"},{SM_AGENT_INSTANCE_FIPSMODE, "COMPAT"}};int nCount = 8;// Call the Agent API to send the dataint nResult = Sm_AgentApi_SetAgentInstanceInfo(pAgentApiHandle, arrParams, nCount);switch (nResult){case SM_AGENTAPI_NOCONNECTION:case SM_AGENTAPI_FAILURE:case SM_AGENTAPI_TIMEOUT:{// put error handling herebreak;}case SM_AGENTAPI_NO:{// The call was refused - probably not properly formatted. This return indicates// that the call ran on the PS and returned an explicit NO response, as opposed to// some other connection or protocol error that might generate the conditions above.break;}case SM_AGENTAPI_YES:{// Successbreak;}} // switch (nResult)
エージェント API を使用してリソースにアクセスする方法
エージェント API が初期化された後、エージェントは、そのユーザからの要求の受け付け(URL に対する GET 要求を受信するなど)を開始できます。
以下の手順は、エージェントがリソースへのアクセスを許可するために必要な操作を説明しています。エージェントのパフォーマンスを向上するために、ほとんどの手順は結果をキャッシュできるようになっています。エージェントは、最小限のキャッシュをするか最大限のキャッシュするかを選択できます。
ユーザにリソースへのアクセスを許可する方法
- リソースにアクセスするためのユーザの要求を受理します。これはアプリケーション固有の要求です。たとえば、Web エージェントは、特定 URL に対する GET 要求を受理できます。
- Sm_AgentApi_IsProtected() をコールすることにより、要求されたリソースが保護されているかどうかを判別します。リソースが保護されている場合、ポリシー サーバは、ユーザの身元を検証するためにユーザから取得される必要がある必須の認証情報を返します。リソースが保護されていない場合、要求されたリソースへのアクセスが許可されます。この手順の結果はキャッシュできます。Sm_AgentApi_Login() をコールすることにより、ユーザからの必要な認証情報を収集し、ユーザを認証します。認証が成功した後、ポリシー サーバは、セッションを作成し、固有のセッション ID とセッション仕様が含まれるレスポンス属性を返します。これらのレスポンス属性は、ポリシーによって制御され、ユーザ プロファイル データ、静的または動的な権限、多数の事前定義済み認証状態属性のほか、ポリシー管理者によって指定された他のデータを含めることができます。エージェントは、ユーザ セッション情報をキャッシュし、セッション有効期限を追跡することにより、セッション管理を実行できるようになります。
- Sm_AgentApi_Authorize() をコールすることにより、要求されたリソースへのアクセス権がユーザに付与されていることを検証します。認可が成功した後、ポリシー サーバは、リソース固有の権限が含まれるレスポンス属性を返します。これらのレスポンス属性は、ポリシーによって制御され、ユーザ プロファイル データ、静的または動的な権限、ポリシー管理者によって指定された他のデータを含めることができます。要求されたリソースに対するユーザの認可情報が利用可能になり、これをキャッシュしておくことで今後の要求の速度を向上できます。
- (オプション)エージェントがそのキャッシュから認可を実行する場合は、Sm_AgentApi_Audit() をコールすることにより、認証および認可のトランザクションをログ記録します。
- ユーザの身元が既知であり、認可が検証され、必要な資格が取得されている場合に、リソースへのアクセスをユーザに許可します。
- (オプション) Sm_AgentApi_DoManagement() をコールすることにより、管理要求を発行します。これは、ポリシー サーバで更新コマンドをポーリングするために必要に応じて実行される手順です。エージェントでは、コマンドに応じて暗号化キーを更新したり、キャッシュをクリアすることができます。
- API インスタンスごとに Sm_AgentApi_UnInit() をコールすることにより、すべての API インスタンスを解放します。これにより、すべてのポリシー サーバへの TCP 接続が閉じられます。
エージェント API で提供されるキャッシュ機能では、セッション有効期間は適用されません。ユーザ セッションやリソース固有権限をキャッシュするように選択すると、エージェントには各ユーザ要求中に独自のセッション管理を実行する必要性が生じることになります。これは、エージェント上でキャッシュすることにより、セッションの検証やリソース認可またはその両方を実行するためにポリシー サーバとやり取りする必要がなくなるためです。
カスタム エージェントのコンパイルおよびリンク
カスタム エージェントを有効にして
CA Single Sign-on
とやり取りするには、SmAgentAPI.h を使用してエージェント アプリケーションをコンパイルし、以下に示すプラットフォーム固有のライブラリにリンクします。UNIX プラットフォームでは、ライブラリ検索パスを指定する環境変数にライブラリを追加する必要があります。変数には、複数のディレクトリをコロンで区切って指定できます。これらの変数も以下に示します。プラットフォーム | ライブラリ | ディレクトリ | 変数名 |
Windows | SmAgentAPI.lib | <install_path>\sdk\lib\win32\ | |
Solaris | libsmagentapi.so | <install_path>/sdk/bin | LD_LIBRARY_PATH |
HP-UX | libsmagentapi.so | <install_path>/sdk/bin | SHLIB_PATH: |
AIX | libsmagentapi.so | <install_path>/sdk/bin | LIBPATH |
Linux | libsmagentapi.so | <install_path>/sdk/bin | LD_LIBRARY_PATH |
注:
Microsoft Visual C++ を使用してエージェント API アプリケーションを構築する場合は、必ず ws2_32.lib とリンクしてください。