20 APIの使用

Oracle Identity Managerには、アプリケーション開発用のAPIが用意されています。

この章のトピックは、次のとおりです:

• Oracle Identity Governance APIについて

• Oracle Identity Governanceサービスへのアクセス

• Oracle Identity Governanceサービス

• よく使用されるサービス

• 従来のサービスと新規サービス間のマッピング

• 従来のOracle Identity Manager APIの使用

• コード・サンプル

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

20.1 Oracle Identity Governance APIについて

オラクル社では、Oracle Identity Governanceで使用可能なサービスを公開するネットワーク対応型のJavaベースのApplication Program Interface (API)を提供しています。

このAPIはPlain Old Java Objects (POJO)に基づき、Oracle Identity Governanceと対話するために必要なすべての処理を行います。このAPIは、Oracle Identity Governanceのクライアントを構築する場合や、サード・パーティ製品をOracle Identity Governanceプラットフォームと統合する場合に使用できます。

ノート:

このリリースでは、Oracle Identity Governanceは次のものをサポートしていません。

• 従来のAPI

• シグネチャベースのログイン

20.2 Oracle Identity Governanceサービスへのアクセス

OIMClientクラスを使用して、Oracle Identity Managerと統合するためのクライアントを開発できます。

この項では、Oracle Identity Managerサービスに加えて、それらのサービスを使用してOracle Identity Managerと統合するためのクライアントを開発する方法について説明します。

次の項目が含まれます。

• Oracle Identity Governanceサービスについて

• OIMClientの使用

• 統合デプロイメントにおけるOIMClientおよびtcUtilityFactoryの使用

20.2.1 Oracle Identity Governanceサービスについて

Oracle Identity Managerサービスへのエントリ・ポイントは、oracle.iam.platform.OIMClientクラスです。

以前のリリースで使用されていたThor.API.tcUtilityFactoryもサポートされます。Oracle Identity Managerと統合するためのクライアントの開発には、oracle.iam.platform.OIMClientを使用することをお薦めします。

20.2.2 OIMClientの使用

OIMClientを使用するには、OIMClientのインスタンスを作成し、サービスを検索し、サービスに対してメソッドを呼び出します。

OIMClientは、Oracle Identity Managerで使用可能なサービスにアクセスするためのエントリ・ポイントです。OIMClientを使用するには、次のステップを実行します。

1. 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, t3://OIM_HOSTNAME:OIM_PORT);
   OIMClient oimClient = new OIMClient(env);
   

   ここで、OIM_HOSTNAMEをOracle Identity Managerがデプロイされているホスト名に、OIM_PORTをポート番号に置き換えます。

2. 適切な資格証明を使用してOracle Identity Managerにログインします。

   oimClient.login(OIM_USERNAME, OIM_PASSWORD);
   

3. サービスを参照します。

   UserManager usermgr = oimClient.getService(UserManager.class);
   OR
   tcLookupOperationsIntf lookupIntf = oimClient.getService(tcLookupOperationsIntf.class);
   

4. サービスでメソッドをコールします。

   HashMap userAttributes = new HashMap();
   ……………..
   UserManagerResult result = userMgr.create(new User(null, userAttributes));
   

20.2.3 統合デプロイメントにおけるOIMClientおよびtcUtilityFactoryの使用

統合デプロイメントでOIMClientおよびtcUtilityFactoryを使用するには、OPSSフレームワークを使用するか、OIMClient APIを呼び出します。

Access Manager (OAM)と統合されるOracle Identity Managerデプロイメントでは、Oracle Identity Managerドメインのセキュリティ・レルムにおいて、OIMSignatureAuthenticatorは構成されません。したがって、Oracle Identity Managerと統合するすべてのカスタム・アプリケーションまたはパートナ・アプリケーションでは、Oracle Identity Managerへの署名ベースのログインを使用しないでください。かわりに、次のいずれかの方法を使用する必要があります。

• Oracle Platform Security Services (OPSS)フレームワーク: パートナ・アプリケーションまたはクライアント・アプリケーションが、Fusion Middlewareスタックに基づくJ2EEアプリケーションである場合は、OPSSフレームワークで次の方法を使用できます。

  ノート:

  OPSSおよびその主な機能の詳細は、アプリケーション・セキュリティ・ガイドのOracle Platform Security Servicesの概要を参照してください

  • OPSS資格証明ストア: これにより、資格証明のセキュアな管理(格納、取得、変更)が可能です。パスワードをOPSS資格証明ストアに格納し、Oracle Identity ManagerクライアントにユーザーIDおよびパスワードを使用してログインする際に、それを取得できます。OPSS資格証明ストアの詳細は、アプリケーション・セキュリティ・ガイドの資格証明ストアの管理を参照してください。

  • OPSS SubjectSecurity API: パートナ・アプリケーションにおいて、システム管理者ユーザーなどのより高い権限を使用してOracle Identity Manager EJB/サービスAPIを呼び出す場合は、OPSS SubjectSecurity APIを使用できます。次のパートナ・アプリケーションのサンプル・コードでは、より高い権限を使用してOracle Identity Manager APIを呼び出しています。

    関連項目:

    SubjectSecurity APIの詳細は、『Oracle Fusion Middleware Oracle Platform Security Services Java APIリファレンス』を参照してください。

    //Get ActionExecutor for OIM System administrator, xelsysadm
    ActionExecutor actionExecutor = SubjectSecurity.getInstance().getActionExecutor("xelsysadm");
    actionExecutor.execute(new PrivilegedAction<Object>() {
      public Object run() {
           //OIM EJB method invocation goes here….
                       Hashtable env = new Hashtable();
          //serverURL – OIM server's RMI URL
                       // ctxFactory – WLS/WAS context factory class
             env.put(OIMClient.JAVA_NAMING_PROVIDER_URL, serverURL);
             env.put(OIMClient.JAVA_NAMING_FACTORY_INITIAL,ctxFactory);
             OIMClient client = new OIMClient(env);
      //Invoking EJB service method as "xelsysadm"
             RequestService reqSrvc = client.getService(RequestService.class);
             reqSrvc.getBasicRequestData("1");//1 is the request ID.
                  }
    });
    

• なんらかの理由でOPSSフレームワークを使用できない場合は、ユーザーIDおよびパスワードを使用してOIMClient APIを呼び出すことをお薦めします。ただし、Oracle Identity Managerユーザーのパスワードは、クライアントまたはパートナによってセキュアに格納および管理する必要があります。

20.3 Oracle Identity Governanceサービス

Oracle Identity Manager APIを使用して、Oracle Identity Managerで使用可能なサービスにアクセスできます。

Oracle Identity Manager 11gリリース1 (11.1.1)のAPIと従来のAPIとでは使用されている表記規則が異なるため、この項ではこれらについて次の各トピックで個別に説明します。

• Oracle Identity Governanceのサービス

• 従来のサービスまたはユーティリティ

20.3.1 Oracle Identity Governanceのサービス

サービスは、パッケージ名とサービス・インタフェース名に関連する規則に基づきます。

Oracle Identity Manager 11g以降のサービスでは、次の表記規則に従います。

• パッケージ名: サービスは、名前が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
  

Oracle Identity Managerで導入された新しいサービスには次のようなものがあります。

oracle.iam.api.OIMService
oracle.iam.platform.authopss.api.AuthorizationService
oracle.iam.provisioning.api.ProvisioningService
oracle.iam.provisioning.api.ApplicationInstanceService

20.3.2 従来のサービスまたはユーティリティ

ユーティリティは、パッケージ名とサービス・インタフェース名に関連する命名規則に従います。

ユーティリティとも呼ばれる従来のサービスでは、次の命名規則に従います。

• パッケージ名: 従来のAPIはすべてThor.API.Operationsパッケージに含まれます。

• サービス・インタフェース名: サービス名の形式は、*Intfです。たとえば、Thor.API.Operations.tcImportOperationsIntfとなります。

関連項目:

Oracle Identity Managerで使用可能な全サービスのリストは、Oracle Fusion Middleware Oracle Identity Governance Java APIリファレンスを参照してください。前述の命名規則を使用して、APIを検索できます。

20.4 よく使用されるサービス

よく使用されるサービスには、UserManager、RequestService、RoleManager、OrganizationManager、oracle.iam.api.OIMServiceなどがあります。

表20-1に、Oracle Identity Managerでよく使用されるサービスの一部を示します。

表20-1 よく使用されるサービス

サービス名	説明
UserManager	ユーザーの作成、検索、変更、削除などのユーザー管理操作を提供します。
RequestService	リクエストの発行、取消し、クローズおよび検索操作を提供します。
RoleManager	ロールの作成、検索、変更、削除などのロール管理操作を提供します。このサービスでは、ロール・メンバーおよびロール間の関係の管理操作も提供されます。
OrganizationManager	組織の作成、検索、変更、削除、有効化、無効化などの組織管理操作を提供します。
oracle.iam.api.OIMService	Oracle Identity Managerで操作を実行するメソッドを提供します。このサービスのAPIのコール中に、目的を渡すことができます。ここでの目的とは、リクエストまたは指示です。

20.5 従来のサービスと新規サービス間のマッピング

Oracle Identity Managerでは、従来のAPIの一部が新規アーキテクチャを使用して再作成されており、対応するユーティリティ・サービスまたはインタフェース・クラスが変更されています。

表20-2に、従来のインタフェースと新規インタフェース間の対応の概要を示します。

表20-2 従来のサービスと新規サービス間のマッピング

従来のサービス	新しいサービス
Thor.API.Operations.tcUserOperationsIntf	oracle.iam.identity.usermgmt.api.UserManager
Thor.API.Operations.tcGroupOperationsIntf ノート: 管理を追加および削除するためのグループ・マネージャAPI関連のすべての委任管理APIは非推奨になりました。	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

20.6 従来のOracle Identity Manager APIの使用

従来のOracle Identity Manager APIでは、多くの場合tcResultSetインタフェースを使用します。

この項では、結果セットの使用方法について説明します。次の項目が含まれます。

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

• 結果セットの使用例

• Oracle Identity Manager例外の処理

• クリーンアップ

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

Thor.API.tcResultSetインタフェースは、データベースから取得したレコードを格納するデータ構造です。

データセットを戻す必要のあるOracle Identity Manager APIのメソッドでは、結果セットが使用されます。この結果セットは、列が属性に対応し、行がエンティティに対応する2次元データ構造です。たとえば、ユーザーを検索するメソッドにより戻される結果セットの場合、各行が1人のユーザーに関するデータを表し、行内の各列がそのユーザーの属性を表します。

付属する様々なメソッドを使用して、結果セット内をスクロールし、特定の属性に対応する個々のエントリを取得できます。結果セット内の特定の行を検索するには、行番号をパラメータとしてgoToRow()メソッドを使用します。行から列の値を取得するには、getStringValue()などの適切なアクセッサ・メソッドを使用します。特定の列から値を取得するには、列名をパラメータとしてアクセッサ・メソッドに渡します。列名は、Oracle Identity Managerメタデータ・システムで定義されている説明的なコードです。

次の表に、サンプル・メタデータ値の一部を示します。このマッピングは参照コードに基づいており、Design Consoleで「参照定義」フォームを使用して参照できます。

列コード	説明
IT Resources.Name	ITリソースの名前
Process Definition.Name	プロビジョニング・プロセスの名前

ノート:

既存のレコードを更新する際に必要となるため、取得した結果セット・オブジェクトの状況を常に把握してください。

20.6.2 結果セットの使用例

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");

20.6.3 Oracle Identity Manager例外の処理

APIのメソッドでは、Oracle定義のJava例外がスローされます。

捕捉した例外オブジェクトでgetMessage()メソッドを使用するかわりに、isMessage内部変数にアクセスして例外メッセージを取得できます。

20.6.4 クリーンアップ

tcUtilityFactoryクラスによって、ユーティリティまたはファクトリ・インスタンスで使用されるすべてのリソースが管理され、使用後のリソースを解放する手段が提供されます。

ユーティリティ・クラス・インスタンスを取得し、このユーティリティ・クラスに関連付けられているリソースを解放するために、tcUtilityFactoryをインスタンス化して使用する場合は、ファクトリ・クラスでclose(utility Object)メソッドをコールします。セッションが終了している場合は、ファクトリ・インスタンスでclose()メソッドをコールして、すべてのユーティリティ・クラス、セッション・オブジェクトおよびデータベース・オブジェクトを解放します。

静的コールを使用してユーティリティ・クラスを直接取得した場合は、ユーティリティ・オブジェクトが不要になった後に、そのユーティリティ・オブジェクトのclose(object)メソッドをコールします。

20.7 コード・サンプル

情報の取得や証明書およびOIMService APIの使用に関するコード・サンプルを理解します。

この項には次のコード例が含まれます。

• Oracle Identity Governance情報の取得

• 証明書APIの使用

• OIMService APIの使用

20.7.1 Oracle Identity Governance情報の取得

ファクトリ・クラスのインスタンスを作成する例を理解します。次に、個々のユーティリティ・クラスを取得し、それらを使用してOracle Identity Governanceの情報を取得するために、インスタンスが複数回コールされます。

Oracle Identity Governanceの情報を取得するには:

1. 前提条件として、次のJARファイルがAPI実行のクラスパスにあることを確認します:

   $MW_HOME/oracle_common/modules/oracle.jrf/jrf-api.jar
   $MW_HOME/idm/designconsole/lib/oimclient.jar
   $MW_HOME/oracle_common/modules/thirdparty/spring-context-4.3.20.RELEASE.jar
   $MW_HOME/oracle_common/modules/org.apache.commons.logging_1.2.jar
   $MW_HOME/idm/server/idmdf/idmdf-common.jar
   $MW_HOME/wlserver/server/lib/wlthint3client.jar
   $MW_HOME/oracle_common/modules/thirdparty/spring-core-4.3.20.RELEASE.jar
   

2. 次のコマンドを実行して、コードを実行します:

   $JAVA_HOME/bin/java -Djava.security.policy=$DC_HOME/config/xl.policy -Djava.security.auth.login.config=$DC_HOME/config/authwl.conf  -DAPPSERVER_TYPE=wls -cp $CLASSPATH Sample

   次に、Oracle Identity Governance情報を取得する方法のサンプル・コードを示します。

   /*
    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. 
   */
    
   // 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";
           char[] password = "xelsysadm".toCharArray();
           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
   

20.7.2 証明書APIの使用

ユーザーに属する証明書の取得、アプリケーション・インスタンス証明書の取得、証明書の認定または拒否、および証明書の完了に関するコード例を理解します。

この項では、CertificationServiceなどの証明書に関連するAPIの使用方法のコード例を示します。次の項目が含まれます。

• ユーザーに属する証明書の取得

• アプリケーション・インスタンス証明書の取得

• 証明書の認定または拒否

• 証明書の完了

20.7.2.1 ユーザーに属する証明書の取得

次の例は、ユーザーに属する証明書を取得するためのコード・サンプルです。

public List<CertificationInstance> findCertifications(SearchCriteria
searchCriteria, Set<String> retAttrs, Map<String,Object> configParams) throws
CertificationServiceException;
Example of searchCriteria to use:
  SearchCriteria searchCriteria1 = new
SearchCriteria(CertificationConstants.CERTIFICATION_SEARCH_FIELDPRIMARY_REVIEW
ER_ID, userKey, SearchCriteria.Operator.EQUAL);
  SearchCriteria searchCriteria2 = new
SearchCriteria("certificationStatusForQuery",
CertificationConstants.STATE_IN_PROGRESS.toString(),
SearchCriteria.Operator.EQUAL);
  SearchCriteria searchCriteria = new SearchCriteria(searchCriteria1,
searchCriteria2, SearchCriteria.Operator.AND);

20.7.2.2 アプリケーション・インスタンス証明書の取得

次の例は、アプリケーション・インスタンス証明書を取得するためのコード・サンプルです。

public List<IDCAccountAttributeAndRoleWrapper> loadBatchUserEntitlements(LongcertificationId, String taskUid, Long userId, PaginationContext context,SearchCriteria searchCriteria) throws CertificationServiceException;

20.7.2.3 証明書の認定または拒否

次の例は、権限を認定または拒否するためのコード・サンプルです。

public void certifyUserEntitlements(Long certId, String taskUid, Long
userEntityId, Set<Long> roleEntityIds, Set<Long> accountEntityIds, Set<Long>
accountAttributeEntityIds, Integer certified, Date statusEndDate, String
comments) throws CertificationServiceException;

20.7.2.4 証明書の完了

次の例は、証明書を完了するためのコード・サンプルです。

public CertificationInstance completeCertification(final Long certificationId, String taskUid, char[] cleartextPassword)

20.7.3 OIMService APIの使用

RequestDataオブジェクトを構築し、OIMService APIを通じて操作を呼び出すためのOIMService APIの使用例を理解します。

この項では、OIMService APIを使用した操作の使用例を示します。次の項目が含まれます。

• RequestDataオブジェクトの構築

• OIMService APIの使用例

20.7.3.1 RequestDataオブジェクトの構築

OIMService APIを介してサポートされる操作を呼び出すには、まずRequestDataオブジェクトを構築する必要があります。

この項では、RequestDataオブジェクトの構築について説明します。次の項目が含まれます。

• ターゲット・ユーザーおよびカート項目に関連する操作のRequestDataオブジェクトの構築

• ユーザー・エンティティに関連する操作のRequestDataオブジェクトの構築

• 操作およびエンティティ・キー

20.7.3.1.1 ターゲット・ユーザーおよびカート項目に関連する操作のRequestDataオブジェクトの構築

ロール、アプリケーション・インスタンス、権限などのターゲット・ユーザーおよびカート項目に関連するすべての操作について、次のようにしてRequestDataオブジェクトを構築します。

1. RequestDataオブジェクトのインスタンスを作成します。
2. 次のような呼出しで受益者オブジェクトのリストの作成、フィールドの設定およびオブジェクトのRequestDataオブジェクトとの関連付けを行います。

   requestData.setBeneficiaries();
   

3. RequestBeneficiaryEntityオブジェクトのリストを作成し、エンティティ・タイプ、エンティティ・キー、操作などのカート項目データを設定します。次のような呼出しでオブジェクトを受益者オブジェクトと関連付けます。

   beneficiary.setTargetEntities();
   

   entityKeyは特定の操作に対するentity.setEntityKey()メソッドを使用して設定され、表20-3に基づく必要があります。

4. RequestBeneficiaryEntityAttributeオブジェクトのリストを作成し、各オブジェクトの属性名と値を設定します。entity.setEntityData()を呼び出してオブジェクトをエンティティ・オブジェクトと関連付けます。これは、カート項目がフォームに関連付けられる場合にのみ必要です。

   ノート:

   • RequestData.setTargetEntities()は、この例では使用しません。

   • OIMService APIの使用の詳細は、OIMService APIの使用例を参照してください。

20.7.3.1.2 ユーザー・エンティティに関連する操作のRequestDataオブジェクトの構築

ユーザーの作成、ユーザーの変更、ユーザーの有効化、ユーザーの無効化、ユーザーの削除などのユーザー・エンティティのみが関係する操作のすべてで、次のようにしてRequestDataオブジェクトに移入する必要があります。

1. RequestDataオブジェクトのインスタンスを作成します。
2. エンティティ・タイプ、エンティティ・キーおよび操作を設定し、RequestEntityオブジェクトのリストを作成します。ユーザーの作成以外のすべての操作で、ユーザー・キーとしてエンティティ・キーを設定する必要があります。
3. RequestEntityAttributeオブジェクトのリストを作成し、各オブジェクトの属性名と値を設定します。これは、ユーザーの作成およびユーザーの変更の操作にのみ必要です。

20.7.3.1.3 操作およびエンティティ・キー

表20-3は、操作とそれに対応する、entity.setEntityKey()メソッドを使用して設定されるエンティティ・キーのリストです。

表20-3 操作とentityKey

操作	entityKey
アプリケーション・インスタンスのプロビジョニング	アプリケーション・インスタンス・キー
アカウントの変更	アカウント・キー
アカウントの失効	アカウント・キー
アカウントの有効化	アカウント・キー
アカウントの無効化	アカウント・キー
権限のプロビジョニング	権限キー
権限の変更	権限インスタンス・キー
権限の失効	権限インスタンス・キー

20.7.3.2 OIMService APIの使用例

OIMService APIを使用したアカウントの失効とユーザーの作成に関するコード・サンプルを理解します。

この項では、OIMService APIの使用方法のコード例を示します。次の項目が含まれます。

• アカウントの失効

• ユーザーの作成

20.7.3.2.1 アカウントの失効

次に、アカウントの失効に関するコード・サンプルを示します。

RequestData requestData = new RequestData();
Beneficiary beneficiary = new Beneficiary();
beneficiary.setBeneficiaryKey("12"); //User with key 12
beneficiary.setBeneficiaryType(Beneficiary.USER_BENEFICIARY);
 
RequestBeneficiaryEntity entity = new RequestBeneficiaryEntity();
entity.setEntityType("ApplicationInstance");
entity.setEntityKey(String.valueOf(accountKey));
entity.setOperation("REVOKE");
 
List<RequestBeneficiaryEntity> entities = new ArrayList<RequestBeneficiaryEntity>();
 
entities.add(entity);
beneficiary.setTargetEntities(entities);
 
List<Beneficiary> beneficiaries = new ArrayList<Beneficiary>();
beneficiaries.add(beneficiary);
requestData.setBeneficiaries(beneficiaries);
OperationResult result = oimService.doOperation(requestData, OIMService.Intent.ANY);
if( result.getRequestID() != null ) {
//Operation resulted in to request creation.
System.out.println("Request submitted with ID: " + result.getRequestID());
} else {
System.out.println("Account is revoked successfully");
}

20.7.3.2.2 ユーザーの作成

次に、ユーザーの作成に関するコード・サンプルを示します。

RequestData requestData = new RequestData("Create User");
RequestEntity ent = new RequestEntity();
ent.setRequestEntityType(OIMType.User);
ent.setOperation("CREATE");
HashMap<String, String> userData = new HashMap<String, String>();
 
List<RequestEntityAttribute> attrs = new ArrayList<RequestEntityAttribute>();
 
RequestEntityAttribute attr = new RequestEntityAttribute("Last Name", "Doe", RequestEntityAttribute.TYPE.String);
attrs.add(attr);        
attr = new RequestEntityAttribute("First Name", "John", RequestEntityAttribute.TYPE.String);
attrs.add(attr);
attr = new RequestEntityAttribute("User Login", "jdoe", RequestEntityAttribute.TYPE.String);
attrs.add(attr);
Long organizationKey = new Long(1);
attr = new RequestEntityAttribute("Organization", organizationKey , RequestEntityAttribute.TYPE.Long);
attrs.add(attr);
attr = new RequestEntityAttribute("Role", "Full-Time", RequestEntityAttribute.TYPE.String);
attrs.add(attr);
 
ent.setEntityData(attrs);
 
List<RequestEntity> entities = new ArrayList<RequestEntity>();
entities.add(ent);
requestData.setTargetEntities(entities);
OperationResult result = oimService.doOperation(requestData, OIMService.Intent.ANY);
if( result.getRequestID() != null ) {
//Operation resulted in to request creation.
System.out.println("Request submitted with ID: " + result.getRequestID());
} else {
System.out.println("User is created successfully");
}

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

API開発サイクルが容易になるように、Oracle Identity ManagerにはカスタムAPI ZIPファイルが用意されています。

カスタムAPI ZIPファイルを構成するには:

1. $MW_HOME/idm/designconsole/CustomClient.zipファイルを解凍します。
2. xlCustomClient.batを次のように変更します。
   1. CLASSPATHを、カスタム・クライアントに関連付けられたJARに変更します。
   2. CLIENT_CLASSにカスタム・クライアントのメイン・クラス名を設定します。
   3. 次のプロパティを変更します。

      -Djava.security.auth.login.config=config\authwl.conf 
      -Djava.naming.provider.url=t3://HOST_NAME:PORT_NUMBER/

3. <Custom Client>/config/xlconfig.xmlを次のように変更します。
   1. アプリケーション・サーバー名を変更します。

      <appServerName>weblogic</appServerName>

   2. Discovery設定をWebLogic固有の値に変更します。

      <Discovery>
        <CoreServer>
          <java.naming.provider.url>
            t3://HOST_IP_ADDRESS:PORT_NUMBER
          </java.naming.provider.url>
          <java.naming.factory.initial>
            weblogic.jndi.WLInitialContextFactory
          </java.naming.factory.initial>
        </CoreServer>
      </Discovery>