C 用のディレクトリ API

ディレクトリ API を使用すると、カスタム ネームスペースを使用するユーザ ディレクトリを管理することができます。ディレクトリ API は、stmndr によってサポートされないタイプのデータベースやディレクトリに格納されているデータにアクセスします。ディレクトリ API では以下が実行できます。
sm1252sp1jjp
ディレクトリ API を使用すると、カスタム ネームスペースを使用するユーザ ディレクトリを管理することができます。ディレクトリ API は、
CA Single Sign-on
によってサポートされないタイプのデータベースやディレクトリに格納されているデータにアクセスします。ディレクトリ API では以下が実行できます。
  • サポートされないディレクトリ エントリ(ユーザ)をポリシーに追加する
  • サポートされないディレクトリ エントリの管理
CA Single Sign-on
は、ユーザ ディレクトリに対する以下のネームスペースをサポートします。
  • LDAP
  • ODBC
  • Microsoft Windows NT
  • カスタム
LDAP、ODBC および NT ネームスペースはディレクトリ API なしで使用できます。別のタイプのユーザ ディレクトリにアクセスするには、ディレクトリ API でディレクトリのインターフェースを作成します。
ディレクトリ API には、ポリシー サーバへのローカル アクセス タイプがあります。
前提条件
ディレクトリ API を使用する前に、管理 UI に移動し、カスタム ネームスペースでユーザ ディレクトリ オブジェクトを作成および設定します。
ディレクトリ API を使用するには、以下が必要です。
  • 以下のタスクのいずれかの経験がある、1 人以上のアプリケーション開発者
    • C プログラミング言語でのコーディング
    • 共有ライブラリの構築
    • 必要なディレクトリ タイプのベンダーによって提供される、関連 API の使用
  • 共有ライブラリを構築するためのサポートされた開発環境。
    リンクが必要ないので、サポートされる開発環境の制限リストはありません。たとえば、GNU Compiler Collection (GCC) を使用できます。ディレクトリ API は以下の開発環境でテスト済みです。
    • UNIX プラットフォーム: Sun Visual WorkShop C++ 5.0
    • Windows プラットフォーム: Microsoft Visual C++6.0
  • ポリシー サーバ
    ポリシー サーバはディレクトリ API アプリケーションの構築には必要ありませんが、ディレクトリ API を呼び出すときにアプリケーションを使用するためにはポリシー サーバが必要です。
ディレクトリ API を使用する方法
前提条件を満たしたら、以下の手順に従います。
  1. ディレクトリ API で提供されたサンプルを確認します。
  2. ディレクトリ API を実装するためにソース コードを記述します。
  3. ソース コードから共有ライブラリを構築します。
  4. 以下のデフォルトの場所に共有ライブラリを配置します。
    • UNIX プラットフォームでは、
      CA Single Sign-on
      lib ディレクトリ
    • Windows プラットフォームでは、
      CA Single Sign-on
      bin ディレクトリ
    オプションで、別の場所に共有ライブラリを配置できます(ポリシー サーバがその場所にアクセスできる場合)。別の場所を使用する場合は、
    CA Single Sign-on
    [ユーザ ディレクトリ]ダイアログ ボックスの[ライブラリ]フィールドで共有ライブラリへの完全修飾パスを指定します。
サンプル ディレクトリ アプリケーションで使用される構造
サンプル ディレクトリ API アプリケーションは以下に存在します。
<install_path>\sdk\samples\smdirapi\smdirapi.cpp
ディレクトリ API にはディレクトリ インスタンス ハンドル、ディレクトリ プロバイダ ハンドルおよびディレクトリ エントリ(ユーザ)インスタンス ハンドルが含まれます。これらのハンドルは、「初期化および解放関数」にリストされた初期化関数から返されます。
サンプル コードは、これらのハンドルを管理するために以下の構造を使用します。
ハンドル タイプ
データ構造
ディレクトリ インスタンス
DirHandle_t
ディレクトリ プロバイダ
ProviderHandle_t
ディレクトリ エントリ(ユーザ)インスタンス
UserHandle_t
ディレクトリ インスタンス ハンドル
SmDirInitDirInstance() が呼び出されるとき、サンプルは DirHandle_t をインスタンス化します。その後、ハンドルはディレクトリ操作関数に渡されます。
全プロセスを通して同じ値を使用する必要はありません。値は変更することが許可されています。
DirHandle_t の定義は以下のとおりです。
typedef struct DirHandle_s
{
   char nTag;
   bool bValid;
   char szErrMsg[ERRMSG_SIZE];
   char* pszUniqueKey;
   char* pszParameter;
   char* pszUsername;
   char* pszPassword;
   int bRequireCredentials;
   int bSecureConnection;
   int nSearchResults;
   int nSearchTimeout;
} DirHandle_t;
SmDirReleaseInstance() が呼び出されるとき、サンプルは DirHandle_t を解放します。ディレクトリ インスタンス ハンドルとユーザ インスタンス ハンドルを区別するために
nTag
の値が使用されます。
ディレクトリ プロバイダ ハンドル
サンプルは、ポリシー サーバとディレクトリ API の間の橋渡しをするためにプロバイダ ハンドル構造 ProviderHandle_t を定義します。プロバイダ ハンドルは、
CA Single Sign-on
がライブラリをロードするときからのデータをポリシー サーバがシャットダウンするまで保存するために使用できます。
SmDirInit() が呼び出される場合、サンプルは ProviderHandle_t をインスタンス化します。その後、このハンドルはほぼすべての後続の関数に渡されます。全プロセスを通して同じ値を使用する必要はありません。値は変更することが許可されています。
SmDirRelease() が呼び出されるとき、サンプルは ProviderHandle_t を解放します。
ProviderHandle_t の例については、サンプル コードで関数 SmDirInit() を参照してください。この例に従うことができますが、必須ではありません。ProviderHandle_t には、ユーザのパスワードなど、プロセスの始めに設定し、使用したい情報を含めることができます。
ディレクトリ エントリ(ユーザ)インスタンス ハンドル
サンプルは、SmDirInitUserInstance() が呼び出される場合に UserHandle_t をインスタンス化します。その後、このハンドルはディレクトリ エントリ(ユーザ)操作関数に渡されます。これらの関数のリストについては、「ディレクトリ エントリ(ユーザ)」上の「操作」を参照してください。
全プロセスを通して同じ値を使用する必要はありません。値は変更することが許可されています。
UserHandle_t の定義は以下のとおりです。
typedef struct UserHandle_s
{
   char nTag;
   bool bValid;
   char szErrMsg[ERRMSG_SIZE];
   DirHandle_t* phDir;
   char* pszUserDn;
} UserHandle_t;
SmDirReleaseInstance() が呼び出されるとき、サンプルは UserHandle_t を解放します。
ハンドル タイプを区別する方法
SmDirReleaseInstance() などの一部の関数は、ディレクトリ インスタンス ハンドルまたはディレクトリ エントリ(ユーザ)インスタンス ハンドルのいずれかを渡される場合があります。サンプル コードは、ディレクトリ インスタンス ハンドルとディレクトリ エントリ(ユーザ)インスタンス ハンドルを区別する方法を提供します。
nTag
が[DirHandle_t]および[UserHandle_t]の両方の最初のフィールドであることに注目してください。SmDirInitDirInstance() が呼び出される場合、
nTag
は DirHandle_t で 0 に設定されます。SmDirInitUserInstance が呼び出される場合、
nTag
は UserHandle_t で 1 に設定されます。
いずれかのタイプのハンドルを受け入れる関数が呼び出される場合、どのタイプのハンドルが渡されたかを判断するために
nTag
の値が確認されます。
エクスポートされた API 列挙
SmApi.h には、ディレクトリ API によって使用される以下の列挙が含まれます。
  • Sm_DirApi_Capability_t(ディレクトリ機能)
  • Sm_PolicyResolution_t(ポリシー解決)
ディレクトリ機能
Sm_DirApi_Capability_t は、カスタム ディレクトリに対して設定できる機能を列挙します。
以下の表は、Sm_DirApi_Capability_t で列挙されたディレクトリ機能のリストを示しています。表の後に各機能の説明が示されます。
名前
Sm_DirApi_Capability_ForceResetUserPassword
0x00000001
Sm_DirApi_Capability_ChangeUserPassword
0x00000002
Sm_DirApi_Capability_DisableUser
0x00000004
Sm_DirApi_Capability_SetUserAttributes
0x00000008
Sm_DirApi_Capability_Recursive
0x00000010
カスタム ディレクトリが特定の機能を持つためには、その機能に対して必須ユーザ属性を定義する必要があります。たとえば、ユーザ パスワードを変更するように
CA Single Sign-on
を有効にするには、パスワード属性を識別する必要があります。  
CA Single Sign-on
は、次にその属性を使用してユーザ パスワードを取得および設定します。
  • Sm_DirApi_Capability_ForceResetUserPassword。カスタム ディレクトリはユーザ パスワード リセットを強制できます。
    CA Single Sign-on
    がパスワードのリセットを強制できるようにするには、以下のユーザ属性を定義します。
    • パスワード属性。ユーザ パスワードを取得および設定するために
      CA Single Sign-on
      が使用できる属性。管理 UI で、[ユーザ ディレクトリ]ダイアログ ボックス上の[ユーザ属性]タブの[パスワード属性]フィールドにこの属性名を入力します。サンプル内では、属性名は password です。
    • 無効フラグ。ユーザの無効状態を取得および設定するために
      CA Single Sign-on
      が使用できる属性。管理 UI で、[ユーザ ディレクトリ]ダイアログ ボックス上の[ユーザ属性]タブの[無効フラグ]フィールドにこの属性名を入力します。サンプル内では、属性名は Disabled です。
    ユーザがパスワードの変更を強制される場合、ポリシー サーバは SmDirSetUserDisabledState() を呼び出します。サンプル コードで、ユーザの[無効フラグ]は Sm_Api_Disabled_PWMustChange(無効の理由)に設定されます。
  • Sm_DirApi_Capability_ChangeUserPassword。カスタム ディレクトリはユーザ パスワードを変更できます。パスワードを変更するには、パスワード属性を識別する必要があります。これは、ユーザ パスワードを取得および設定するために
    CA Single Sign-on
    が使用できる属性です。管理 UI で、[ユーザ ディレクトリ]ダイアログ ボックス上の[ユーザ属性]タブの[パスワード属性]フィールドにこの属性名を入力します。
    CA Single Sign-on
     ポリシー サーバは、SmDirChangeUserPassword() を呼び出して、カスタム ディレクトリ内の[パスワード]フィールドの値を変更できるようにします。
  • Sm_DirApi_Capability_DisableUser。カスタム ディレクトリはユーザ アカウントを無効にできます。ユーザを無効にするには、無効フラグを識別する必要があります。これは、ユーザの無効状態を取得および設定するために
    CA Single Sign-on
    が使用できる属性です。管理 UI で、[ユーザ ディレクトリ]ダイアログ ボックス上の[ユーザ属性]タブの[無効フラグ]フィールドにこの属性名を入力します。
    管理者がユーザ アカウントを無効または有効にするために管理 UI を使用する場合、またはパスワード サービスがユーザ アカウントを無効にする場合、ポリシー サーバは SmDirSetUserDisabledState() を呼び出します。
    CA Single Sign-on
    で、ユーザ アカウントは多くの理由で無効になり、これらの理由はデータ構造 Sm_Api_DisabledReason_t のメンバによって表されます。
  • Sm_DirApi_Capability_SetUserAttributes。  
    CA Single Sign-on
    はカスタム ディレクトリでユーザ属性を設定できます。
    ポリシー サーバは、SmDirSetUserAttr() を呼び出して、ユーザが
    CA Single Sign-on
    を使用してカスタム ディレクトリでユーザ属性を設定できるようにします。
  • Sm_DirApi_Capability_Recursive。カスタム ディレクトリには再帰をサポートする機能があります。たとえば、カスタム ディレクトリはネストされたグループをサポートする場合があります。
    ディレクトリ API 内の以下の関数が、再帰的なフラグを保持するためのパラメータを持っています。
    • SmDirGetUserGroups()
    • SmDirValidateUserPolicyRelationship()
ポリシー サーバにディレクトリ機能に関する情報を送信するには、関数 SmDirQueryVersion() を実装します。Sm_DirApi_Capability_t に列挙された 1 つ以上の値を渡すには、機能パラメータ(
pnCapabilites
)を使用します。  
CA Single Sign-on
は次にこれらの機能をチェックします。
たとえば、ユーザがパスワードの変更を試行した場合、ポリシー サーバは、SmDirQueryVersion() を呼び出して機能 Sm_DirApi_Capability_ChangeUserPassword を確認します。カスタム ディレクトリにその機能がない場合、ユーザはエラー メッセージを受信します。
ディレクトリ機能を設定する例は、サンプル コードに示されています。まず、
*pnCapabilities
をゼロに初期化し、次に以下のように
*pnCapabilities
を設定します。
*pnCapabilities = 
   *pnCapabilities | Sm_DirApi_Capability_
<supported_capability>
;
例:
*pnCapabilities =
   *pnCapabilities | Sm_DirApi_Capability_ChangeUserPassword;
*pnCapabilities =
   *pnCapabilities | Sm_DirApi_Capability_DisableUser;
CA Single Sign-on
による使用を対象としたフィールドで他のアプリケーションがデータを変更することがないようにしてください。たとえば、
CA Single Sign-on
ユーザの無効な状態を保持するフィールドのデータを他のアプリケーションが変更することがないようにしてください。
ポリシー解決
Sm_PolicyResolution_t は、SmApi.h で定義され、2 つのポリシー オブジェクト間の関係を説明する値を列挙します。以下のディレクトリ API 関数が Sm_PolicyResolution_t を使用します。
  • SmDirAddEntry()
  • SmDirGetDirObjInfo()
  • SmDirRemoveEntry()
  • SmDirValidateUserPolicyRelationship()
ディレクトリ アプリケーションの構築
ディレクトリ API アプリケーションを構築する場合、SmAPI.h ファイルを含めます。ソース コードには以下のステートメントが含まれる必要があります。
#include "SmApi.h"
ディレクトリ API を実装する共有ライブラリを構築する場合、他の共有ライブラリまたはインポート ライブラリにもリンクしている必要はありません。ディレクトリ API は、インクルード ファイル SmApi.h で定義されたエクスポート可能な関数を持つ共有ライブラリとして構築されます。
一般的なデータ型と構造
データ型と構造はディレクトリ API で使用されますが、他の
CA Single Sign-on
API によって使用される場合もあります。
Sm_Api_DisabledReason_t は、ユーザ アカウントが無効になる理由を列挙します。
以下のディレクトリ API 関数は Sm_PolicyResolution_t を使用します。
  • SmDirGetUserDisabledState()
  • SmDirSetUserDisabledState()
ユーザ アカウントが有効または無効になる場合、ポリシー サーバは SmDirSetUserDisabledState() を呼び出します。この呼び出しは、Sm_Api_DisabledReason_t で列挙されるとおり、カスタム ディレクトリ内で 1 つ以上の無効の理由に対して無効フラグを設定する機会を与えます。ユーザ アカウントが無効または有効にされる場合、SmDirGetUserDisabledState() は無効の理由を返します。SmDirGetUserDisabledState() を実装するとき、カスタム ディレクトリが無効なフラグをサポートしない場合は、Sm_Api_Disabled_Enabled を返します。
注:
ユーザのアカウントは複数の理由で無効になる場合があります。たとえば、[ユーザは次回ログイン時にパスワード変更が必要]チェック ボックスが選択され、管理者が[無効]をクリックする場合、nDisabledReason は Sm_Api_Disabled_PWMustChange ビットおよび Sm_Api_Disabled_AdminDisabled ビットの両方を保持します。
無効なフラグは
CA Single Sign-on
ユーザ属性です。管理 UI で、[ユーザ ディレクトリ]ダイアログ ボックスの[ユーザ属性]タブ上で、[無効フラグ]フィールド内に属性の名前を入力します。サンプル内では、属性名は Disabled です。
構造 Sm_Api_Context_t は、
CA Single Sign-on
ログ記録ユーティリティ、トレース ユーティリティおよびエラー ユーティリティに関数ポインタを与えます。
Sm_Api_Reason_t は、認証失敗などアクセス イベントの理由を列挙します。ユーザが認証に対する認証情報を提供する場合、ユーザ名と DN を検証するポリシー サーバは SmDirAuthenticateUser() を呼び出します。この呼び出しは、アクセス イベントに関する情報を返す機会を与えます。
初期化およびリリース関数
オブジェクトを初期化するために、ポリシー サーバは、以下の表内の関数を呼び出します。
関数名
CA Single Sign-on
ポリシー サーバによって初期化されるオブジェクト
ディレクトリ プロバイダ。プロバイダ ハンドルを設定します。
ディレクトリ インスタンス。ディレクトリ インスタンス ハンドルを設定します。
ディレクトリ エントリ(ユーザ)インスタンス。ユーザ エントリ インスタンス ハンドルを設定します。
ディレクトリ プロバイダの初期化
ポリシー サーバの起動後に最初にカスタム ディレクトリ プロバイダが必要になるとき、ポリシー サーバは SmDirInit() を呼び出してディレクトリ プロバイダを初期化します。この時点で、サンプル コードで示されるようにプロバイダ ハンドルを設定します。ポリシー サーバは、ポリシー サーバ サービスのいずれかが開始(または再度開始)されるまで SmDirInit() を再度呼び出すことはしません。
SmDirInit() は、各カスタム ディレクトリ プロバイダ ライブラリ(.dll または .so)に対して 1 度呼び出されます。
ディレクトリ インスタンスの初期化
ポリシー サーバは、ディレクトリ インスタンスを初期化するために SmDirInitDirInstance() を呼び出します。サンプル コードで示されるようにディレクトリ インスタンス ハンドルを設定します。
このディレクトリ プロバイダ ライブラリを使用して、SmDirInitDirInstance() がディレクトリ インスタンスにつき 1 回呼び出されます。  
CA Single Sign-on
は、(検索またはプロパティの取得などの操作を実行するために)ディレクトリ コンテキストを必要とする場合に、認証または許可要求を処理する間に関数を呼び出します。この関数は、通常要求の初めに呼び出されます。
ディレクトリ エントリ(ユーザ)インスタンスの初期化
ポリシー サーバ は SmDirInitUserInstance() を呼び出すことによりユーザ インスタンスを初期化します。サンプル コードで示されるようにディレクトリ エントリ(ユーザ)インスタンス ハンドルを設定します。
オブジェクトを解放するには、以下の表の関数を使用します。
関数名
CA Single Sign-on
ポリシー サーバによって解放されるオブジェクト
ディレクトリ プロバイダ。プロバイダ ハンドルの削除
ディレクトリまたはエントリ インスタンス。どのハンドルが渡されるかを決定します。
ユーザ インスタンスの解放
ポリシー サーバは、必要に応じてユーザ インスタンス ハンドルを解放できるように、SmDirReleaseInstance() を呼び出します。渡されるハンドルがディレクトリ インスタンス ハンドルではなくユーザ インスタンス ハンドルであることを確認します。
ディレクトリ インスタンスのリリース
ポリシー サーバは、必要に応じてディレクトリ インスタンス ハンドルを解放できるように、SmDirReleaseInstance() を呼び出します。渡されるハンドルがユーザ インスタンス ハンドルではなくディレクトリ インスタンス ハンドルであることを確認します。
CA Single Sign-on
 は、ディレクトリ コンテキストが必要なくなった後、SmDirInitDirInstance() の呼び出しごとに 1 回 SmDirReleaseInstance() を呼び出します。これは通常要求の最後に呼び出されます。
ディレクトリ プロバイダの解放
管理者がポリシー サーバのシャットダウンを開始するとき、SmDirRelease() を呼び出してディレクトリ プロバイダを解放します。
ユーティリティ関数
これらの関数は、ディレクトリ操作のシーケンス、またはディレクトリ エントリ(ユーザ)操作のシーケンス内で呼び出すことができます。関数がパラメータを通してインスタンス ハンドルを受信する場合、それがディレクトリ インスタンス ハンドルかディレクトリ エントリ(ユーザ)インスタンス ハンドルかを判断します。
関数名
説明
文字列に割り当てられた空きメモリ。
文字列配列に割り当てられた空きメモリ。
ディレクトリ API バージョン、およびサポートするディレクトリ機能を確認します。
文字列および文字列配列の解放
ポリシー サーバが文字列パラメータをとる操作関数を呼び出した後、ポリシー サーバは、SmDirFreeString() または SmDirFreeStringArray() を呼び出して割り当てられたメモリを解放します。呼び出しを繰り返して複数の文字列を解放できます。
たとえば、管理者は、ユーザ Mikel の検索を実行するために管理 UI を使用できます。管理者は、まず[検索]ドロップダウン リスト ボックスから文字列 User を選択し、次に、[検索式]フィールドに文字列 Mikel を入力します。  
CA Single Sign-on
は SmDirLookup() を呼び出し、文字列("User = Mikel" の形式)を
lpszPattern
パラメータに渡します。  
CA Single Sign-on
は、その後 SmDirFreeStringArray() を 2 回呼び出します。最初の呼び出しで、
CA Single Sign-on
は文字列配列 Mikel を渡します。2 番目の呼び出しで、
CA Single Sign-on
は文字列配列 User を渡します。
クエリおよび検証
ポリシー サーバは、SmDirQueryVersion()、次に SmDirValidateInstance() を頻繁に呼び出します。このシーケンスは複数回繰り返される場合があります。