オラクル社では、Oracle Identity Manager内のよく使用される機能を公開する目的で、ネットワーク対応型のJavaベースのApplication Program Interface(API)を提供しています。このAPIは、Oracle Identity Managerのクライアントを構築する場合や、サード・パーティ製品をOracle Identity Managerプラットフォームに統合する場合に便利です。
この章には、次の各項が含まれます。
次の表に、主なAPI機能をリストします。
要件 | ソリューション |
---|---|
理解しやすい共通の言語 | Java。 |
ネットワーク対応 | Java 2 Platform, Enterprise Edition(J2EE)分散コンピューティングに基づいた開発環境。 |
使いやすさ | セッション初期化およびメンテナンスのタスクは、APIユーザーから隠蔽されます。ユーティリティ・クラスの作成に必要な基礎的作業は、Oracle Identity Manager APIの使用により隠蔽されます。ユーティリティ・クラスの作成および使用については、統一化された方法が提供されます。 |
Thor.API.tcUtilityFactory
クラスにより、ユーティリティ・クラスを作成および使用するための統一化された方法がサポートされます。このクラスにより、APIを通じて公開されるOracle Identity Manager機能を使用する際の複雑さが最小化され、感じられなくなります。これらは、次の方法により実現されます。
任意のソース(Webクライアント、アダプタ、カスタム・コードなど)からコールされるAPIに対する統一化された機能の提供
インスタンス化の際のセッション情報の作成および管理
この情報は、ユーティリティ・ファクトリを通じて取得されたリソースの管理に使用されます。
既存のセッションのコンテキストにおいてAPIが機能する時期の識別
これにより、ユーティリティ・クラスを取得するためにユーティリティ・メソッドを使用できます(たとえば、データベース接続が存在する場合に静的メソッドを使用するなど)。
このクラスの使用例は、次のとおりです。
セッションとデータベース接続がすでに存在する場合
この場合、静的メソッドの使用により、ユーティリティ・クラスとしてクラスを使用できます(アダプタ・ファクトリを通じて作成されるアダプタなど)。
セッションとデータベース接続がまだ作成されていない場合
この場合、クラスをインスタンス化し、データベース接続に必要な情報を提供できます。データベースに接続すると、クラスによってセッションおよびデータベース・オブジェクトの作成と管理が行われます。この使用例は、通常、Oracle Identity Managerとの統合にAPIを使用するサード・パーティにより、クライアント・サイドでAPIがインスタンス化される場合にのみ発生します。
このクラスで使用可能なメソッドのリストは、APIに付属のJava APIリファレンスを参照してください。このクラスの使用方法の詳細は、「APIの使用方法」を参照してください。
Oracle Identity Manager APIでは、Thor.API.Operations
パッケージに定義されたユーティリティ・クラスおよびインタフェースを通じて、よく使用されるOracle Identity Manager機能を公開しています。これらのクラスとインタフェースにより、メソッドが機能領域ごとにグループ化されます。
表1-1に、APIで使用できるインタフェースの一部をリストします。
表1-1 APIで使用できるユーティリティ・インタフェースの一部
インタフェース | 説明 |
---|---|
|
共通のユーザー操作を公開します。たとえば、ユーザーの検索、ユーザーの作成、およびユーザーの有効化と無効化です。 |
|
共通のグループ操作を公開します。たとえば、グループの検索、グループの作成、およびグループでのユーザーの追加と削除です。 |
|
共通のリクエスト操作を公開します。たとえば、リクエストの作成とリクエストへのコメントの追加です。 |
関連資料: クラスおよびインタフェースの完全なリストと、使用可能なすべてのメソッドの説明は、APIのJavadocドキュメントを参照してください。 |
Thor.API.Operations
パッケージのすべてのクラスは、ベース・ユーティリティ・クラスのThor.API.Base.tcBaseUtility
を拡張しており、Thor.API.Base.tcUtilityOperationsIntf
インタフェースを実装しています。
ベース・ユーティリティ・クラスでは、すべてのユーティリティ・クラスに共通の基本機能が提供されます。ベース・ユーティリティ・クラスは、他のすべてのユーティリティ・クラスによって継承される共通機能を提供する抽象クラスです。継承される機能は、主にファクトリ・クラスとユーティリティ・クラス間の対話に関係しています。すべてのユーティリティ・クラスは、そのクラスがユーティリティ・クラスであることを示すtcUtilityOperationsIntf
インタフェースを実装しています。
Thor.API.tcResultSet
インタフェースは、データベースから取得したレコードを格納するデータ構造です。データセットを戻す必要のあるOracle Identity Manager APIのメソッドでは、結果セットが使用されます。この結果セットは、列が属性に対応し、行がエンティティに対応する2次元データ構造です。たとえば、ユーザーを検索するメソッドにより戻される結果セットの場合、各行が1人のユーザーに関するデータを表し、行内の各列がそのユーザーの属性を表します。
付属する様々なメソッドを使用して、結果セット内をスクロールし、特定の属性に対応する個々のエントリを取得できます。結果セット内の特定の行を検索するには、行番号をパラメータとしてgoToRow()
メソッドを使用します。行から列の値を取得するには、getStringValue()
などの適切なアクセッサ・メソッドを使用します。特定の列から値を取得するには、列名をパラメータとしてアクセッサ・メソッドに渡します。列名は、Oracle Identity Managerメタデータ・システムで定義されている説明的なコードです。
次の表に、サンプル・メタデータ値の一部を示します。このマッピングは参照コードに基づいており、管理およびユーザー・コンソールで参照定義フォームを使用して参照できます。
列コード | 説明 |
---|---|
Users.First Name |
ユーザーの名前 |
Groups.Group Name |
グループの名前 |
注意: 既存のレコードを更新する際に必要となるため、取得した結果セット・オブジェクトの状況を常に把握してください。 |
この項には、次の各項目が含まれます。
APIをインストールするには、次の手順を実行します。
次のディレクトリ構造を作成します。
<Custom Client>\config\lib\ext
標準のOracle Identity Managerデスクトップ・クライアント・インストール環境のconfig、libおよびextフォルダから、カスタム・クライアント・インストール環境のconfig、libおよびextフォルダに各ファイルをそれぞれコピーします。
<Custom Client>ディレクトリにbasecp.batファイルとclasspath.batファイルをコピーします。
JBoss Application Serverの場合
次のコマンドを含むバッチ・ファイルを作成します。
call classpath set CLIENT_CLASS=<fully qualified name of your custom API client class
> java -Djava.security.manager -DXL.HomeDir=. -Djava.security.policy=config\xl.policy -Djava.security.auth.login.config=config\auth.conf -Djava.naming.provider.url=jnp://<host_name
>:<port
>/<CLIENT_CLASS
>
WebLogic Application Serverの場合
次のコマンドを含むバッチ・ファイルを作成します。
call classpath set CLIENT_CLASS=<fully qualified name of your custom API client class
> java -Djava.security.manager -DXL.HomeDir=. -Djava.security.policy=config\xl.policy -Djava.security.auth.login.config=config\authwl.conf -Djava.naming.provider.url=t3://<host_name
>:<port
>/<CLIENT_CLASS
>
WebSphere Application Serverの場合
WebSphere Application Serverの場合、次の手順を実行します。
WebSphereアプリケーション・クライアントをインストールします。
Enterprise Archive(EAR)ファイルのXLCustomClient.earを作成します。
EARファイルには、カスタム・クライアントのメイン・クラスを含むJava Archive(JAR)ファイルを格納する必要があります。マニフェスト・ファイルには、メイン・クラス名のエントリを含める必要があります。次に、EARファイルを構築するためのサンプルAntターゲットを示します。
<target name="makeXLAPICustomClient" depends="init" description="create a jar for the client side code"> <jar jarfile="<dir>/xlWSCustomClient.jar"> <fileset dir="<dir>"> <include name="<fully qualified classes directory>"/> </fileset> <fileset dir="<dir>"> <include name="application-client.xml"/> </fileset> <manifest> <attribute name="Main-Class" value="<fully qualified main class name>"/> </manifest> </jar> <ear appxml="<dir>/application.xml" earfile="<dir>/XLCustomClient.ear"> <fileset file="<dir>/xlWSCustomClient.jar"/> </ear> </target>
次のコマンドを含むバッチ・ファイルを作成します。
call basecp.bat set WS_HOME=c:\Websphere "%WS_HOME%\bin\launchclient" XLCustomClient.ear -CCclasspath=%CLASSPATH% -CCsecurityMgrPolicy=./config/xl.policy -CCDXL.HomeDir=. -CCDjava.security.auth.login.config=./config/authws.conf -CCDwas.home="%WS_HOME%"
Webアプリケーションなどの独自のアプリケーションでAPIを使用する場合、クライアントがユーザーからOracle Identity Managerのパスワードを取得できないことがあります。たとえば、シングル・サインオン環境では、ユーザーIDをチェックする際にOracle Identity Managerで認証アプリケーションを使用できない場合があります。このような場合、Oracle Identity Managerと、Oracle Identity ManagerにユーザーIDのみを提供するエンティティの間で信頼を確立する必要があります。
信頼は、デジタル署名を使用して確立します。例1-2のinit()
メソッドを参照してください。
tcUtilityFactory moFactory = new tcUtilityFactory("development",signedMessage);
tcSignatureMessage
オブジェクトには、ユーザーIDの署名バージョンであるOracle Identity ManagerユーザーIDと、Oracle Identity Managerに接続するエンティティのIDを保証するX.509証明書が含まれます。
このオブジェクトを作成するには、次のようにtcCryptoUtil
ユーティリティ・クラスの静的ユーティリティ・メソッドのsign
を使用します。
tcSignatureMessage moSignature = tcCryptoUtil.sign("xelsysadm","PrivateKey");
APIを使用するエンティティでは、署名の秘密鍵のセキュリティを維持する必要があります。秘密鍵は、2つのシステム間で信頼を確立するための基盤となります。
Oracle Identity Managerに、信頼する証明書を示しておく必要もあります。証明書を信頼するには、.xlkeystore内か、またはサーバーのxlconfig.xmlファイルのsecurity
セクションに構成されたキーストア内に、信頼できるCAとして証明書の署名者を追加する必要があります。
ファクトリ・クラスのインスタンスを作成すると、そのクラスのgetUtility()
メソッドをコールすることで、ユーティリティ・クラスのインスタンスを取得できます。getUtility()
メソッドにより、tcUtilityOperationsIntf
のインスタンスが戻されます。戻りオブジェクトは、リクエストした特定のユーティリティ・クラスにキャストする必要があります。
tcUserOperationsIntf moUserUtility = (tcUserOperationsIntf) moFactory.getUtility("Thor.API.Operations.tcUserOperationsIntf");
注意: スケジュール済タスクでは、これらの手順は異なります。リリース9.0.2より前のインストール環境の場合、使用しているアプリケーション・サーバーに対応する『Oracle Identity Manager Installation and Upgrade Guide』を参照してください。それ以降のバージョンでは、次のマニュアルを参照してください。
|
次に、結果セットの使用方法の例を示します。この例では、findAllUsers()
メソッドをコールすることで結果セットを取得しています。このメソッドにより、特定の基準に一致するすべてのユーザーが検索されます。
tcResultSet moResultSet = moUserUtility.findAllUsers(mhAttribs);
findAllUsers()
メソッドでレコードが戻されたかどうかをチェックするには、次のようにisEmpty()
メソッドを使用します。
boolean mbEmpty = moResultSet.isEmpty();
検出されたレコードの数を取得するには、getRowCount()
メソッドを使用します。レコードが検出されなかった場合、メソッドにより0
が戻されます。このメソッドの例は、次のとおりです。
int mnNumRec = moResultSet.getRowCount();
システム内の特定のレコードを選択するには、次のようにgoToRow()
メソッドを使用します。
moResultSet.goToRow(5);
現在の行から属性値を取得するには、次のように適切なアクセッサ・メソッドを使用します。
String msUserLastName = moResultSet.getStringValue("Users.Last Name");
APIのメソッドでは、Oracle定義のJava例外がスローされます。捕捉した例外オブジェクトでgetMessage()
メソッドを使用するかわりに、isMessage
内部変数にアクセスして例外メッセージを取得できます。
tcUtilityFactory
クラスによって、ユーティリティまたはファクトリ・インスタンスで使用されるすべてのリソースが管理され、使用後のリソースを解放する手段が提供されます。
tcUtilityFactory
をインスタンス化してユーティリティ・クラスのインスタンスを取得するために使用した場合、ユーティリティ・クラスに関連付けられたリソースを解放するには、ファクトリ・クラスのclose(utility Object)
メソッドをコールします。セッションが終了したら、ファクトリ・インスタンスのclose()
メソッドをコールして、すべてのユーティリティ・クラス、セッション・オブジェクトおよびデータベース・オブジェクトを解放します。
静的コールを使用してユーティリティ・クラスを直接取得した場合は、ユーティリティ・オブジェクトが不要になった後に、そのユーティリティ・オブジェクトのclose(object)
メソッドをコールします。
例1-1は、Oracle Identity Manager情報を取得する方法を示しています。この例では、ユーティリティ・ファクトリのインスタンスが作成されます。このインスタンスを何度か使用して個々のユーティリティ・クラスを取得し、次にそれらのユーティリティ・クラスを使用してOracle Identity Manager情報を取得します。
例1-1 Oracle Identity Manager情報の取得
/** The utility factory instance. */ tcUtilityFactory ioUtilityFactory public void init(){ ConfigurationClient.ComplexSetting config = ConfigurationClient.getComplexSettingByPath("Discovery.CoreServer"); final Hashtable env = config.getAllSettings(); tcUtilityFactory ioUtilityFactory = new tcUtilityFactory(env, "xelsysadm", "xelsysadm"); } /** Retrieves user login based on the first name. */ public List getUserLogin(String psFirstName){ Vector mvUsers=new Vector(); tcUserOperationsIntf moUserUtility = (tcUserOperationsIntf)ioUtilityFactory.getUtility("Thor.API.Operations.tcUserOperationsIntf"); Hashtable mhSearchCriteria = new Hashtable(); mhSearchCriteria.put("Users.First Name", psFirstName); tcResultSet moResultSet = moUserUtility.findUsers(mhSearchCriteria); for (int i=0; i<moResultSet.getRowCount(); i++){ moResultSet.goToRow(i); mvUsers.add(moResultSet.getStringValue("Users.User ID")); } } /** Retrieves the administrators of an organization based on the organization name. */ public List getAdministratorsOfOrganization(String psOrganizationName){ Vector mvOrganizations=new Vector(); tcOrganizationOperationsIntf moOrganizationUtility = (tcOrganizationOperationsIntf)ioUtilityFactory.getUtility("Thor.API.Operations.tcOrganizationOperationsIntf"); Hashtable mhSearchCriteria = new Hashtable(); mhSearchCriteria.put("Organizations.Organization Name", psOrganizationName); tcResultSet moResultSet = moOrganizationUtility.findOrganizations(mhSearchCriteria); tcResultSet moAdmins; for (int i=0; i<moResultSet.getRowCount(); i++){ moResultSet.goToRow(i); moAdmins=moOrganizationUtility.getAdministrators(moResultSet.getLongValue("Organizations.Key")); mvOrganizations.add(moAdmins.getStringValue("Groups.Group Name")); } } public void example(){ List moList; // initialize resources init(); // retrieve user logins with first name 'Joe' moList=getUserLogin("Joe"); // retrieve user logins with first names starting with 'D' moList=getUserLogin("D*"); // retrieve the administrators of an organization with name 'Example Organization' moList=getAdministratorsOfOrganization("Example Organization"); // release resources ioUtilityFactory.close(); }
例1-2は、デジタル署名ベースのメソッドを使用して、ユーティリティ・ファクトリのインスタンスを作成する方法を示しています。
例1-2 デジタル署名ベースのメソッドの使用
/** The utility factory instance. */ public void init() { try { ConfigurationClient.ComplexSetting config = ConfigurationClient.getComplexSettingByPath("Discovery.CoreServer"); final Hashtable env = config.getAllSettings(); tcSignatureMessage moSignature = tcCryptoUtil.sign("xelsysadm", "PrivateKey"); tcUtilityFactory m_utilFactory = new tcUtilityFactory(env, moSignature); } catch(Exception ex) { ex.printStackTrace(); } }
Oracle Identity Manager 8.0.2以上では、Oracle Identity Managerデスクトップ・クライアントとともにカスタムAPI ZIPファイルがインストールされます。このZIPファイルの目的は、API開発サイクルの簡略化です。このZIPファイルは、次の場所にあります。
XL_installation_directory/xlclient/CustomClient.zip
カスタムAPI ZIPファイルを構成するには、次の手順を実行します。
カスタムAPI ZIPファイルを抽出します。
JBossおよびWebLogicの場合、xlCustomClient
を変更して実行します。
WebSphereの場合、wsCustomClient
を変更して実行します。
各スクリプトの構成方法の詳細は、次の各項目を参照してください。
JBoss構成
xlCustomClient.batを次のように変更します。
CLASSPATH
を変更して、カスタム・クライアントに関連付けられたJARを追加します。
CLIENT_CLASS
変数にカスタム・クライアントのメイン・クラス名を設定します。
次のプロパティを変更します。
-Djava.security.auth.login.config=config\auth.conf -Djava.naming.provider.url=jnp://<machinename>:<portno>/
WebLogic構成
xlCustomClient.batを次のように変更します。
CLASSPATH
を変更して、カスタム・クライアント・インストールに関連付けられたJARを追加します。
CLIENT_CLASS
にカスタム・クライアントのメイン・クラス名を設定します。
次のプロパティを変更します。
-Djava.security.auth.login.config=config\authwl.conf -Djava.naming.provider.url=t3://<machinename
>:<portno
>/
<Custom Client>/config/xlconfig.xmlを次のように変更します。
アプリケーション・サーバー名を変更します。
<appServerName>weblogic</appServerName>
Discovery
設定をWebLogic固有の値に変更します。
<Discovery> <CoreServer> <java.naming.provider.url> t3://10.1.1.54:7001 </java.naming.provider.url> <java.naming.factory.initial> weblogic.jndi.WLInitialContextFactory </java.naming.factory.initial> </CoreServer> </Discovery>
WebSphere構成
wsCustomClient.batを次のように変更します。
CLASSPATH
を変更して、カスタム・クライアント・インストールに関連付けられたJARを追加します。
CLIENT_CLASS
にカスタム・クライアントのメイン・クラス名を設定します。
WS_HOME
にWebSphereホームを設定します。
<Custom Client>/config/xlconfig.xml
を次のように変更します。
アプリケーション・サーバー名を変更します。
<appServerName>websphere</appServerName>
Discovery
設定をWebSphere固有の値に変更します。
<Discovery> <CoreServer> <java.naming.provider.url> corbaloc:iiop:host:2809 </java.naming.provider.url> <java.naming.factory.initial> com.ibm.websphere.naming.WsnInitialContextFactory </java.naming.factory.initial> </CoreServer> </Discovery>