| Oracle® Fusion Middleware Oracle Identity Manager開発者ガイド 11g リリース1(11.1.1) B66705-01 |
|
 前 |
 次 |
オラクル社では、Oracle Identity Managerで使用可能なサービス(以前のリリースではユーティリティと呼ばれていました)を公開する目的で、ネットワーク対応型のJavaベースのApplication Program Interface(API)を提供しています。このAPIはPlain Old Java Objects(POJO)に基づき、Oracle Identity Managerと対話するために必要なすべての処理を行います。このAPIは、Oracle Identity Managerのクライアントを構築する場合や、サード・パーティ製品をOracle Identity Managerプラットフォームに統合する場合に使用できます。
この章では、次の内容を説明します。
Oracle Identity Managerサービスへのエントリ・ポイントは、oracle.iam.platform.OIMClientクラスです。以前のリリースで使用されていたThor.API.tcUtilityFactoryもサポートされます。Oracle Identity Managerと統合するためのクライアントの開発には、oracle.iam.platform.OIMClientを使用することをお薦めします。
この項の内容は次のとおりです。
OIMClientは、Oracle Identity Managerで使用可能なサービスにアクセスするためのエントリ・ポイントです。OIMClientを使用するには、次の手順を実行します。
Oracle Identity Managerアプリケーションへの接続に必要な環境情報を持つOIMClientのインスタンスを作成します。
Hashtable env = new Hashtable(); env.put(OIMClient.JAVA_NAMING_FACTORY_INITIAL, "weblogic.jndi.WLInitialContextFactory"); env.put(OIMClient.JAVA_NAMING_PROVIDER_URL, http://OIM_HOSTNAME:OIM_PORT); OIMClient oimClient = new OIMClient(env);
ここで、OIM_HOSTNAMEをOracle Identity Managerがデプロイされているホスト名に、OIM_PORTをポート番号に置き換えます。
適切な資格証明を使用してOracle Identity Managerにログインします。
oimClient.login(OIM_USERNAME, OIM_PASSWORD);
サービスを参照します。
UserManager usermgr = oimClient.getService(UserManager.class);
サービスでメソッドをコールします。
HashMap userAttributes = new HashMap(); …………….. UserManagerResult result = userMgr.create(new User(null, userAttributes));
Oracle Identity Managerの以前のリリースでは、Oracle Identity Managerサービス(従来のリリースではユーティリティと呼ばれていたもの)へのアクセスでtcUtilityFactoryがサポートされていました。tcUtilityFactoryは引き続きサポートされます。ただし、前述のとおり、Oracle Identity Manager用のあらゆるクライアント・アプリケーションの作成でOIMClientを使用することをお薦めします。
tcUtilityFactoryを使用するには、次の手順を実行します。
ユーザー名やパスワードなどの環境情報を持つtcUtilityFactoryのインスタンスを作成します。
tcUtilityFactory ioUtilityFactory = new tcUtilityFactory(env, "OIM_USERNAME", "OIM_PASSWORD");
ユーティリティの完全修飾名を指定して、ユーティリティまたはサービスを参照します。
tcUserOperationsIntf moUserUtility = (tcUserOperationsIntf)ioUtilityFactory.getUtility("Thor.API.Operations.tcUserOperationsIntf");
ユーティリティで次の操作を実行します。
Hashtable mhSearchCriteria = new Hashtable();
mhSearchCriteria.put("Users.First Name", psFirstName);
tcResultSet moResultSet = moUserUtility.findUsers(mhSearchCriteria);
Oracle Identity Manager APIを使用して、Oracle Identity Managerで使用可能なサービスにアクセスできます。11g リリース1(11.1.1)で導入されたAPIと従来のAPIとでは使用されている表記規則が異なるため、この項ではこれらについて次の各トピックで個別に説明します。
Oracle Identity Manager 11g リリース1(11.1.1)で導入されたサービスでは、次の表記規則に従います。
パッケージ名: サービスは、名前がapiで終わるパッケージに含まれます。次に例を示します。
oracle.iam.request.api oracle.iam.identity.usermgmt.api
サービス・インタフェース名: 11gで導入されたサービスは通常、*Serviceというネーミング規則を使用します。次に例を示します。
oracle.iam.request.api.RequestService oracle.iam.selfservice.self.selfmgmt.api.AuthenticatedSelfService
一部のアイデンティティ管理APIでは、APIに*Managerというネーミング規則を使用します。次に例を示します。
oracle.iam.identity.usermgmt.api.UserManager
ユーティリティとも呼ばれる従来のサービスでは、次のネーミング規則に従います。
パッケージ名: 従来のAPIはすべてThor.API.Operationsパッケージに含まれます。
サービス・インタフェース名: サービス名の形式は、*Intfです。たとえば、Thor.API.Operations.tcImportOperationsIntfとなります。
|
関連項目: Oracle Identity Managerで使用可能な全サービスのリストは、Oracle Fusion Middleware Oracle Identity Manager Java APIリファレンスを参照してください。前述のネーミング規則を使用して、APIを検索できます。 |
表31-1に、Oracle Identity Managerでよく使用されるサービスの一部を示します。
表31-1 よく使用されるサービス
| サービス名 | 説明 |
|---|---|
|
UserManager |
ユーザーの作成、検索、変更、削除などのユーザー管理操作を提供します。 |
|
RequestService |
リクエストの発行、取消し、クローズおよび検索操作を提供します。 注意: 存在しないリクエスト・テンプレートの検索時にリクエスト・テンプレート・サービスを使用すると、null値が返されます。 |
|
RoleManager |
ロールの作成、検索、変更、削除などのロール管理操作を提供します。このサービスでは、ロール・メンバーおよびロール間の関係の管理操作も提供されます。 |
|
OrganizationManager |
組織の作成、検索、変更、削除、有効化、無効化などの組織管理操作を提供します。 |
Oracle Identity Manager 11g リリース1(11.1.1)では、従来のAPIの一部が新規アーキテクチャを使用して再作成されており、対応するユーティリティ・サービスまたはインタフェース・クラスが変更されています。表31-2に、従来のインタフェースと新規インタフェース間の対応の概要を示します。
表31-2 従来のサービスと新規サービス間のマッピング
| 従来のサービス | 新規サービス |
|---|---|
|
Thor.API.Operations.tcUserOperationsIntf |
oracle.iam.identity.usermgmt.api.UserManager |
|
Thor.API.Operations.tcGroupOperationsIntf |
oracle.iam.identity.rolemgmt.api.RoleManager |
|
Thor.API.Operations.tcOrganizationOperationsIntf |
oracle.iam.identity.orgmgmt.api.OrganizationManager |
|
Thor.API.Operations.tcRequestOperationsIntf |
oracle.iam.request.api.RequestService |
|
Thor.API.Operations.tcSchedulerOperationsIntf |
oracle.iam.scheduler.api.SchedulerService |
|
Thor.API.Operations.tcEmailOperationsIntf |
oracle.iam.notification.api.NotificationService |
この項には次のトピックが含まれます:
Oracle Identity Manager用クライアントを開発するには、次の前提条件を満たしている必要があります。
Java Development Kit(JDK)1.6がインストールされており、パス内に設定されていること
ANT 1.7がインストールされており、パス内に設定されていること
Oracle Identity Managerパッケージには、クライアントの開発に必要なライブラリと構成ファイルを含むZIPファイルが含まれています。また、独自のアプリケーション開発の出発点として使用できるサンプル・クライアントも含まれています。
Oracle Identity Manager用のアプリケーション・クライアントを実行するには、次の手順を実行します。
OIM_ORACLE_HOME/server/client/oimclient.zipを、クライアントを開発するコンピュータ(oimclient/ディレクトリなど)にコピーします。このドキュメントでは、このディレクトリをOIM_CLIENT_HOMEと呼びます。ZIPファイルを解凍します。oimclient.zipファイルは、conf、lib、sample、directories、oimclient.jarおよびREADMEで構成されています。
アプリケーション・サーバー固有のクライアント・ライブラリをOIM_CLIENT_HOME/lib/ディレクトリにコピーします。Oracle WebLogic Serverでは、wlfullclient.jarがクライアント・ライブラリです。これは、MIDDLEWARE_HOME/WL_HOME/server/lib/ディレクトリ(たとえば、/scratch/beahome/wlserver_10.3/server/lib/)に作成されます。wlfullclient.jarが存在するかどうかを確認します。存在しない場合は、jarbuilderツールを使用して生成する必要があります。wlfullclient.jarの生成方法は、Oracle WebLogic Serverのドキュメントを参照してください。
サンプル・クライアントを編集して実行します。これを行うには、次の手順を実行します。
OIM_CLIENT_HOME/sample/src/oracle/iam/samples/SampleOIMClient.javaサンプル・クライアント・ファイルを開きます。
Oracle Identity Managerが表示されるホストを指すように、次の定数を編集します。
OIMURL: Oracle Identity Managerホスト・コンピュータのURL
OIMUserName: Oracle Identity Managerの管理者のユーザー名
OIMPassword: Oracle Identity Managerの管理者のパスワード
antコマンドを実行します。これにより、サンプル・クライアントがコンパイルされ、実行されます。サンプルが正常に実行されると、次の出力が生成されます。
[java] LOGGER >> Creating client.... [java] LOGGER >> Logging in [java] LOGGER >> Log in successful [java] LOGGER >> User Created
この項の内容は次のとおりです。
従来のOracle Identity Manager APIでは、多くの場合tcResultSetインタフェースを使用します。Thor.API.tcResultSetインタフェースは、データベースから取得したレコードを格納するデータ構造です。データセットを戻す必要のあるOracle Identity Manager APIのメソッドでは、結果セットが使用されます。この結果セットは、列が属性に対応し、行がエンティティに対応する2次元データ構造です。たとえば、ユーザーを検索するメソッドにより戻される結果セットの場合、各行が1人のユーザーに関するデータを表し、行内の各列がそのユーザーの属性を表します。
付属する様々なメソッドを使用して、結果セット内をスクロールし、特定の属性に対応する個々のエントリを取得できます。結果セット内の特定の行を検索するには、行番号をパラメータとしてgoToRow()メソッドを使用します。行から列の値を取得するには、getStringValue()などの適切なアクセッサ・メソッドを使用します。特定の列から値を取得するには、列名をパラメータとしてアクセッサ・メソッドに渡します。列名は、Oracle Identity Managerメタデータ・システムで定義されている説明的なコードです。
次の表に、サンプル・メタデータ値の一部を示します。このマッピングは参照コードに基づいており、Design Consoleで「参照定義」フォームを使用して参照できます。
| 列コード | 説明 |
|---|---|
|
IT Resources.Name |
ITリソースの名前 |
|
Process Definition.Name |
プロビジョニング・プロセスの名前 |
|
注意: 既存のレコードを更新する際に必要となるため、取得した結果セット・オブジェクトの状況を常に把握してください。 |
結果セットの使用方法の例を次に示します。この例では、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)メソッドをコールします。
例31-1に、Oracle Identity Manager情報の取得方法を示します。この例では、ファクトリ・クラスのインスタンスが作成されます。次に、個々のユーティリティ・クラスを取得し、それらを使用してOracle Identity Managerの情報を取得するために、インスタンスが複数回コールされます。
例31-1 Oracle Identity Manager情報の取得
/*
This class is intented to showcase some of OIM API's. These API's are
specific to OIM 11g release. As an example, Legacy API's usage for
Organization is also shown.
*/
package oracle.iam.samples;
// Role related API's
import oracle.iam.identity.rolemgmt.api.RoleManager;
import oracle.iam.identity.rolemgmt.vo.Role;
import oracle.iam.identity.exception.RoleSearchException;
import oracle.iam.identity.rolemgmt.api.RoleManagerConstants.RoleAttributeName;
import oracle.iam.identity.rolemgmt.api.RoleManagerConstants.RoleCategoryAttributeName;
// User related API's
import oracle.iam.identity.usermgmt.api.UserManager;
import oracle.iam.identity.usermgmt.vo.User;
import oracle.iam.identity.exception.UserSearchException;
import oracle.iam.identity.usermgmt.api.UserManagerConstants.AttributeName;
// Organization Legacy API's
import Thor.API.Operations.tcOrganizationOperationsIntf;
import Thor.API.tcResultSet;
import Thor.API.Exceptions.tcAPIException;
import Thor.API.Exceptions.tcColumnNotFoundException;
import Thor.API.Exceptions.tcOrganizationNotFoundException;
import oracle.iam.platform.OIMClient;
import oracle.iam.platform.authz.exception.AccessDeniedException;
import oracle.iam.platform.entitymgr.vo.SearchCriteria;
import java.util.*;
import javax.naming.NamingException;
import javax.security.auth.login.LoginException;
public class Sample {
private static OIMClient oimClient;
/*
* Initialize the context and login with client supplied environment
*/
public void init() throws LoginException {
System.out.println("Creating client....");
String ctxFactory = "weblogic.jndi.WLInitialContextFactory";
String serverURL = "t3://OIM_HOSTNAME:OIM_PORT";
String username = "xelsysadm";
String password = "xelsysadm";
Hashtable env = new Hashtable();
env.put(OIMClient.JAVA_NAMING_FACTORY_INITIAL,ctxFactory);
env.put(OIMClient.JAVA_NAMING_PROVIDER_URL, serverURL);
oimClient = new OIMClient(env);
System.out.println("Logging in");
oimClient.login(username, password);
System.out.println("Log in successful");
}
/**
* Retrieves User login based on the first name using OIM 11g
* UserManager service API.
*/
public List getUserLogin(String psFirstName) {
Vector mvUsers = new Vector();
UserManager userService = oimClient.getService(UserManager.class);
Set<String> retAttrs = new HashSet<String>();
// Attributes that should be returned as part of the search.
// Retrieve "User Login" attribute of the User.
// Note: Additional attributes can be specified in a
// similar fashion.
retAttrs.add(AttributeName.USER_LOGIN.getId());
// Construct a search criteria. This search criteria states
// "Find User(s) whose 'First Name' equals 'psFirstName'".
SearchCriteria criteria;
criteria = new SearchCriteria(AttributeName.FIRSTNAME.getId(), psFirstName, SearchCriteria.Operator.EQUAL);
try {
// Use 'search' method of UserManager API to retrieve
// records that match the search criteria. The return
// object is of type User.
List<User> users = userService.search(criteria, retAttrs, null);
for (int i = 0; i < users.size(); i++) {
//Print User First Name and Login ID
System.out.println("First Name : " + psFirstName + " -- Login ID : " + users.get(i).getLogin());
mvUsers.add(users.get(i).getLogin());
}
} catch (AccessDeniedException ade) {
// handle exception
} catch (UserSearchException use) {
// handle exception
}
return mvUsers;
}
/**
* Retrieves the administrators of an Organization based on the
* Organization name. This is Legacy service API usage.
*/
public List getAdministratorsOfOrganization(String psOrganizationName) {
Vector mvOrganizations = new Vector();
tcOrganizationOperationsIntf moOrganizationUtility = oimClient.getService(tcOrganizationOperationsIntf.class);
Hashtable mhSearchCriteria = new Hashtable();
mhSearchCriteria.put("Organizations.Organization Name", psOrganizationName);
try {
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"));
System.out.println("Organization Admin Name : " + moAdmins.getStringValue("Groups.Group Name"));
}
} catch (tcAPIException tce) {
// handle exception
} catch (tcColumnNotFoundException cnfe) {
// handle exception
} catch (tcOrganizationNotFoundException onfe) {
// handle exception
}
return mvOrganizations;
}
/**
* Retrieves Role Display Name based on Role name and Role Category
* using OIM 11g RoleManager service API. This example shows how
* to construct compound search criteria.
*/
public List getRoleDisplayName(String roleName, String roleCategory ) {
Vector mvRoles = new Vector();
RoleManager roleService = oimClient.getService(RoleManager.class);
Set<String> retAttrs = new HashSet<String>();
// Attributes that should be returned as part of the search.
// Retrieve the "Role Display Name" attribute of a Role.
// Note: Additional attributes can be specified in a
// similar fashion.
retAttrs.add(RoleAttributeName.DISPLAY_NAME.getId());
// Construct the first search criteria. This search criteria
// states "Find Role(s) whose 'Name' equals 'roleName'".
SearchCriteria criteria1;
criteria1 = new SearchCriteria(RoleAttributeName.NAME.getId(), roleName, SearchCriteria.Operator.EQUAL);
// Construct the second search criteria. This search criteria
// states "Find Role(s) whose 'category' equals 'roleCategory'".
SearchCriteria criteria2;
criteria2 = new SearchCriteria(RoleCategoryAttributeName.NAME.getId(), roleCategory, SearchCriteria.Operator.EQUAL);
// Construct the compound search criteria using 'criteria1' and
// 'criteria2' as arguments. This showcases how to construct
// compound search criterias.
SearchCriteria criteria = new SearchCriteria(criteria1, criteria2, SearchCriteria.Operator.AND);
try {
// Use 'search' method of RoleManager API to retrieve
// records that match the search criteria. The return
// object is of type Role.
List<Role> roles = roleService.search(criteria, retAttrs, null);
for (int i = 0; i < roles.size(); i++) {
//Print Role Display Name
System.out.println("Role Display Name : " +
roles.get(i).getDisplayName());
mvRoles.add(roles.get(i).getDisplayName());
}
} catch (AccessDeniedException ade) {
// handle exception
} catch (RoleSearchException use) {
// handle exception
}
return mvRoles;
}
// Main method invocation
// Following assumptions are made
//1. A User "Joe Doe" already exists in OIM
//2. An Organization "Example Organization" already exists in OIM
//3. A Role "Foobar" already exists in OIM
public static void main(String args[]) {
List moList = null;
try {
Sample oimSample = new Sample();
// initialize resources
oimSample.init();
// retrieve User logins with first name 'Joe'
moList=oimSample.getUserLogin("Joe");
// retrieve User logins with first names starting with 'J'
moList=oimSample.getUserLogin("J*");
// retrieve the administrators of an Organization with name
// 'Example Organization'
moList=oimSample.getAdministratorsOfOrganization(
"Example Organization");
// retrieve Role display name with role name 'FooBar'
// and role category as 'Defaut'
moList=oimSample.getRoleDisplayName("foobar", "Default");
// release resources
oimClient.logout();
} catch (Exception e) {
e.printStackTrace();
}
}
}
次に、サンプルの出力を示します。
[java] Creating client.... [java] Logging in [java] Log in successful [java] First Name : Joe -- Login ID : JDOE [java] First Name : J* -- Login ID : JHOND [java] First Name : J* -- Login ID : JDOE [java] Organization Admin Name : SYSTEM ADMINISTRATORS [java] Role Display Name : foobar
