ヘッダーをスキップ
Oracle Identity Manager API使用法ガイド
リリース9.0.3
E05092-01
  目次
目次

戻る
戻る
 
次へ
次へ
 

1 Oracle Identity Manager APIの使用方法

オラクル社では、Oracle Identity Manager内のよく使用される機能を公開する目的で、ネットワーク対応型のJavaベースのApplication Program Interface(API)を提供しています。このAPIは、Oracle Identity Managerのクライアントを構築する場合や、サード・パーティ製品をOracle Identity Managerプラットフォームに統合する場合に便利です。

この章には、次の各項が含まれます。

Oracle Identity Manager APIの要件

次の表に、主なAPI機能をリストします。

要件 ソリューション
理解しやすい共通の言語 Java。
ネットワーク対応 Java 2 Platform, Enterprise Edition(J2EE)分散コンピューティングに基づいた開発環境。
使いやすさ セッション初期化およびメンテナンスのタスクは、APIユーザーから隠蔽されます。ユーティリティ・クラスの作成に必要な基礎的作業は、Oracle Identity Manager APIの使用により隠蔽されます。ユーティリティ・クラスの作成および使用については、統一化された方法が提供されます。

ファクトリ・クラス

Thor.API.tcUtilityFactoryクラスにより、ユーティリティ・クラスを作成および使用するための統一化された方法がサポートされます。このクラスにより、APIを通じて公開されるOracle Identity Manager機能を使用する際の複雑さが最小化され、感じられなくなります。これらは、次の方法により実現されます。

このクラスの使用例は、次のとおりです。

このクラスで使用可能なメソッドのリストは、APIに付属のJava APIリファレンスを参照してください。このクラスの使用方法の詳細は、「APIの使用方法」を参照してください。

ユーティリティ・クラス

Oracle Identity Manager APIでは、Thor.API.Operationsパッケージに定義されたユーティリティ・クラスおよびインタフェースを通じて、よく使用されるOracle Identity Manager機能を公開しています。これらのクラスとインタフェースにより、メソッドが機能領域ごとにグループ化されます。

表1-1に、APIで使用できるインタフェースの一部をリストします。

表1-1 APIで使用できるユーティリティ・インタフェースの一部

インタフェース 説明

tcUserOperationsIntf

共通のユーザー操作を公開します。たとえば、ユーザーの検索、ユーザーの作成、およびユーザーの有効化と無効化です。

tcGroupOperationsIntf

共通のグループ操作を公開します。たとえば、グループの検索、グループの作成、およびグループでのユーザーの追加と削除です。

tcRequestOperationsIntf

共通のリクエスト操作を公開します。たとえば、リクエストの作成とリクエストへのコメントの追加です。



関連資料:

クラスおよびインタフェースの完全なリストと、使用可能なすべてのメソッドの説明は、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の使用方法

この項には、次の各項目が含まれます。

設定と構成

APIをインストールするには、次の手順を実行します。

  1. 次のディレクトリ構造を作成します。

    <Custom Client>\config\lib\ext

  2. 標準のOracle Identity Managerデスクトップ・クライアント・インストール環境のconfig、libおよびextフォルダから、カスタム・クライアント・インストール環境のconfig、libおよびextフォルダに各ファイルをそれぞれコピーします。

  3. <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の場合、次の手順を実行します。

  1. WebSphereアプリケーション・クライアントをインストールします。

  2. 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>
    
    
  3. 次のコマンドを含むバッチ・ファイルを作成します。

    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-2init()メソッドを参照してください。

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』を参照してください。

それ以降のバージョンでは、次のマニュアルを参照してください。

  • 『Oracle Identity Manager JBoss用インストレーション・ガイド』

  • 『Oracle Identity Manager Oracle Containers for J2EE用インストレーション・ガイド』

  • 『Oracle Identity Manager WebLogic用インストレーション・ガイド』

  • 『Oracle Identity Manager WebSphere用インストレーション・ガイド』


結果セット・オブジェクトの使用方法

次に、結果セットの使用方法の例を示します。この例では、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");

Oracle Identity Manager例外の処理

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();
  }
}

カスタムAPI ZIPファイルの使用方法

Oracle Identity Manager 8.0.2以上では、Oracle Identity Managerデスクトップ・クライアントとともにカスタムAPI ZIPファイルがインストールされます。このZIPファイルの目的は、API開発サイクルの簡略化です。このZIPファイルは、次の場所にあります。

XL_installation_directory/xlclient/CustomClient.zip

カスタムAPI ZIPファイルを構成するには、次の手順を実行します。

  1. カスタムAPI ZIPファイルを抽出します。

  2. JBossおよびWebLogicの場合、xlCustomClientを変更して実行します。

    WebSphereの場合、wsCustomClientを変更して実行します。

    各スクリプトの構成方法の詳細は、次の各項目を参照してください。

JBoss構成

xlCustomClient.batを次のように変更します。

  1. CLASSPATHを変更して、カスタム・クライアントに関連付けられたJARを追加します。

  2. CLIENT_CLASS変数にカスタム・クライアントのメイン・クラス名を設定します。

  3. 次のプロパティを変更します。

    -Djava.security.auth.login.config=config\auth.conf
    -Djava.naming.provider.url=jnp://<machinename>:<portno>/
    

WebLogic構成

xlCustomClient.batを次のように変更します。

  1. CLASSPATHを変更して、カスタム・クライアント・インストールに関連付けられたJARを追加します。

  2. CLIENT_CLASSにカスタム・クライアントのメイン・クラス名を設定します。

  3. 次のプロパティを変更します。

    -Djava.security.auth.login.config=config\authwl.conf
    -Djava.naming.provider.url=t3://<machinename>:<portno>/
    
    

<Custom Client>/config/xlconfig.xmlを次のように変更します。

  1. アプリケーション・サーバー名を変更します。

    <appServerName>weblogic</appServerName>
    
    
  2. 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を次のように変更します。

  1. CLASSPATHを変更して、カスタム・クライアント・インストールに関連付けられたJARを追加します。

  2. CLIENT_CLASSにカスタム・クライアントのメイン・クラス名を設定します。

  3. WS_HOMEにWebSphereホームを設定します。

<Custom Client>/config/xlconfig.xmlを次のように変更します。

  1. アプリケーション・サーバー名を変更します。

    <appServerName>websphere</appServerName>
    
    
  2. 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>