オラクル社では、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