3 ArisID APIの使用
注意:
この章およびすべての項は、12c (12.2.1.3.0)リリースで非推奨になりました。非推奨になると、機能は強化されなくなりますが、12c (12.2.1.3.0)リリースの有効期間中は引き続きサポートされます。記載がある場合、非推奨となった機能は今後のメジャー・リリースではサポートされなくなる可能性があります。次の各トピックで、Identity Governance Framework ArisID APIのアーキテクチャと主要な機能について説明します。
3.1 ArisID APIについて
Identity Governance Framework ArisID APIは、すべてのアイデンティティ情報交換の受渡しに使用される共通のコア・サービスを表します。正式な名称ではありませんが、ArisID APIは、開発者からアイデンティティBeanと呼ばれることが多くあります。
Oracle WebLogic ServerとOracle Identity Managementをインストールしてある場合、このAPIを使用したアプリケーションの開発に必要なjarファイルはすべて、コンピュータにすでにインストールされています。
Identity Governance Frameworkオープン・ソースAPI jarファイルは次のとおりです。
-
openliberty.arisId_1.1.jar: 属性のセットを含むアイデンティティ・サブジェクトの取得に使用されるライブラリ関数とプロバイダを含んだコアArisID APIを提供します。
http://arisid.sourceforge.net/javadocs/arisId_1.1_javadoc/
を参照してください。 -
org.openliberty.arisIdBeans_1.1.jar: ArisID APIに加えてJavaオブジェクトの抽象化を提供するArisID Beanを提供します。これらによって、ArisID APIのトランザクション型アプローチをオブジェクトまたはBean型のアプローチに変換します。
http://arisid.sourceforge.net/javadocs/arisId_1.1_javadoc/
を参照してください。
ArisID API jarファイルは次のとおりです。
-
idxuserrole.jar: 標準的なユーザーとロールのアイデンティティの読取り専用操作を提供します。このjarは、標準のidxuserrole.xml CARMLファイルから生成されます。Identity Governance Framework IDXUserRole Java APIリファレンスを参照してください。
-
userrole.jar: アイデンティティ情報を更新するためのユーザーとロールのアイデンティティ読取り/書込み操作を提供します。Identity Governance Framework UserRole Java APIリファレンスを参照してください。
-
arisId-stack-ovd.jar: このjarファイルはOracle Virtualizationライブラリを使用した
IAttrSvcStack
インタフェースの実装で、異なるバックエンドに接続し、アイデンティティ・ストア・エンティティの抽象ビューを提供します。
ArisID Beanによって、CARML対話の初期化とアクセスに必要なJava APIが提供されます。Beanジェネレータでは、Apache Velociyを使用してCARMLファイル内の各エンティティに対するjavaファイルのセットを生成します。CARMLファイルは、アプリケーションの属性使用要件を記述する宣言型のドキュメントです。ArisID Beanは、jarファイルidxuserrole.jarおよびuserrole.jar内にあります。
次の図に、ArisID APIアーキテクチャの概要を示します。
3.2 ArisID APIの構成
ArisID APIは、Webサーバー環境で簡単で柔軟なデプロイを可能にする複数の構成オプションをサポートしています。
Identity Governance Framework ArisIDでは、作成 > 変更 > テスト > デプロイといった基本的な開発プロセスがサポートされます。作成では、CARML XMLファイルをご使用の環境に応じて変更する必要があります。アプリケーションのテストは、LDAPディレクトリ・サーバーが組み込まれたOracle WebLogic Serverで行えます。
この項では、次の項目について説明します。
3.2.1 CARMLファイルの確認
CARMLは、アプリケーションについて属性使用の要件を定義するXMLベースの宣言形式です。管理者は、CARMLファイルを調べて、適切なバックエンド・リソースに接続します。
既存のArisID Beanがアプリケーションのニーズを満たすかどうかを判断するには、CARMLファイルidxuserrole.xml(読取り専用操作)およびuserrole.xml(読取り専用および読取り/書込み操作)のCARMLファイルを確認する必要があります。これらのCARMLファイルは、DOMAIN_HOME/config/fmwconfig/carmlにあります。
3.2.2 アイデンティティ・リポジトリの構成
アイデンティティ・リポジトリは、企業のユーザーとグループに関する情報が格納されるデータ・ストアです。ArisID Beanによって使用されるアイデンティティ・リポジトリを構成できます。
ArisID Beanによって使用されるアイデンティティ・リポジトリを使用可能にする必要があります。LDAPベースのディレクトリ・サーバーが組み込まれたOracle WebLogic Serverまたは11gのOracle Virtual Directoryでサポートされている任意のLDAPディレクトリを使用できます。ArisID APIは、Oracle Platform Security Servicesと統合されています。Oracle Platform Security Servicesに構成されているLDAPベースのアイデンティティ・ストアに自動的に接続します。Oracle Platform Security Servicesでサポートされているアイデンティティ・ストアの詳細は、Identity Governance Frameworkのシステム要件と動作保証情報を参照してください。
Oracle Platform Security Servicesアイデンティティ・ストアとは異なるアイデンティティ・ストアを使用する必要がある場合、次のシステム・プロパティを設定します。
igf.ovd.config.dir=DOMAIN_HOME/config/fmwconfig/arisidprovider/conf
次に、adapters.os_xmlファイルを編集して、接続先のディレクトリのhost
、port
および資格証明を含めます。igf.ovd.config.dir
プロパティは、adapaters.os_xmlおよび適切に設定された他の構成ファイルを含む任意のディレクトリに設定できます。
ディレクトリ制限
次のLDAPディレクトリ制限が適用されます。
-
OpenLDAP 2.2またはNovell eDirectoryを使用する場合、ページングはサポートされていません。たとえば、
searchUsersbyPage()
、searchRolesbyPage()
などのページングAPIは機能しません。複数言語サポート(MLS)は提供されません。 -
Oracle WebLogic Serverの組込みLDAPベースのディレクトリ・サーバーを使用する場合、複数言語サポート(MLS)は提供されません。
3.2.3 マッピング・ファイルの構成
マッピング・ファイルで、CARML属性をLDAP属性、オブジェクトクラスおよび検索パラメータにマップできます。サイトのLDAPベースのディレクトリ・サーバー用にマッピング・ファイルをカスタマイズできます。
CARMLファイルが作成されている場合、対応するマッピング・ファイルは同じ場所に作成されます。デフォルトのマッピング・ファイルには、Oracle WebLogic Serverに組み込まれているディレクトリ・サーバー(Oracle Platform Security Servicesのデフォルト・アイデンティティ・ストア)に固有の属性詳細が含まれています。デフォルトのCARMLファイルとOracle Platform Security Servicesアイデンティティ・ストアを使用する場合、マッピングを構成する必要ばありません。Oracle Platform Security Servicesの構成パラメータは、マッピング・ファイルのパラメータをオーバーライドします。
3.3 ArisID APIの設計に関する推奨事項
デフォルトのCARMLファイルとマッピング・ファイルには、デプロイ・シナリオについて特定の想定がなされています。デプロイ要件によっては、これらの詳細を変更する必要がある場合があります。
次の各トピックで、変更可能な構成パラメータについて説明します。
3.3.1 一意識別子の構成について
すべてのユーザーが一意に識別可能である必要があります。ユーザー・エントリを識別するための一意の識別子として、デフォルトの構成、emailが使用されます。
ユーザーの検索時、検索に想定されているデフォルトの属性はemail
です。次に例を示します。
SearchUser( String uniqueid, Map<String, Object>)
パフォーマンス上の理由から、一意の識別子として使用される属性は、バックエンドで検索可能な属性である必要があります。アプリケーションが選択したuniquekey
とバックエンドの属性との間のマッピングは、構成時に処理されます。これは、Oracle Virtual Directoryマッピングでの構成です。HashMap
を使用して、操作の実行時に使用するオプションのコンテキスト情報を指定します。現在のリリースでは、次のオプションがサポートされます。
-
検索を実行するプリンシパル・ユーザー: (
ArisIdConstants.APP_CTX_AUTHUSER, (Principal)user
) -
言語の制約(ある場合): (
ArisIdConstants.APP_CTX_LOCALE, "fr"
) -
ページネーション・サポート(ある場合): (
ArisIdConstants.APP_CTX_PAGESIZE, 10
)
3.3.2 キー属性の仕様について
属性の一意性は、制約または属性を定義することによって適用されます。
アプリケーションで、アイデンティティ・リポジトリのバックエンドからアクセスされるエントリをアプリケーション固有のリポジトリに格納することがあります。このような場合、永続化する属性を慎重に検討する必要があります。たとえば、バックエンドがLDAPベースのリポジトリの場合、GUID
属性がLDAPベースのバックエンドで唯一の一意のキーであるため、永続化属性としてこれを使用します。他のLDAP属性はすべて変更可能です。
バックエンドがリレーショナル・データベースの場合、一意性制約が適用される属性を一意キーとして選択します。これは、ArisIDマッピング・プロパティ・ファイルで指定できます。一意キーに基づいてユーザーを検索するメソッドは次のとおりです。
searchUserOnUniqueKey(String UniqueKey, Map<String,Object>)
HashMap
を使用して、操作の実行時に使用するオプションのコンテキスト情報を指定します。現在のリリースでは、次のオプションがサポートされます。
-
検索を実行するプリンシパル・ユーザー: (
ArisIdConstants.APP_CTX_AUTHUSER, (Principal)user
) -
言語の制約(ある場合): (
ArisIdConstants.APP_CTX_LOCALE, "fr"
) -
ページネーション・サポート(ある場合): (
ArisIdConstants.APP_CTX_PAGESIZE, "10"
)
3.3.3 複数言語サポートについて
ロケール固有の結果を必要とするアプリケーション向けに複数言語サポート(MLS)が提供されます。
属性と適切なMLSコードは、ArisIDプロパティ・ファイルのmultiLanguageAttributes
要素に格納されます。
<multiLanguageAttributes>…</multiLanguageAttribute>
displayname
は、最もよく使用される複数言語属性であり、したがってデフォルトで複数言語属性として構成されています。必要に応じて他の属性をArisIDマッピング・ファイルに追加できます。
制限事項
引数としてロケールが指定されるAPIでは、ArisIDプロパティ・ファイルに<multiLanguageAttributes>
としてリストされている、ロケール固有の値を持つすべての属性に対してロケール固有の値が返されます。他の属性についてはすべて、格納されているデフォルト値が返されます。
バックエンドのシステムでは、データはISO-3166に準拠した形式で返されます。たとえば、(英語の他に)フランス語のロケールがある場合、cn
属性に対してcn,:fr
として格納されます。クライアント・アプリケーションのロケールは、プロパティHashMap
にArisIdConstants.APP_CTX_LOCALE, "fr"
と指定し、ArisIDプロパティ・ファイルにcn
をmultiLanguageAttribute
として含め、この属性をマップします。
3.3.4 大規模な結果の処理
場合によっては、大規模な結果セットを取得することがあります。その場合、パフォーマンスやリソースの問題が発生する可能性があります。大規模な結果セットを管理するには、次のサンプル・コードを使用します。
アプリケーションでアイデンティティ・データにアクセスする場合、検索の結果セットが大きすぎてアプリケーションで処理できない場合があります。そのような場合、管理可能なサイズのページに結果を分割することができます。これは、ページで返されるオブジェクトの数を定義することで行います。
次の例に、標準的な使用法を示します。
RoleManager rm = new RoleManager(env); List<PropertyFilterValue> attrFilters = new ArrayList<PropertyFilterValue>(); attrFilters.add(new PropertyFilterValue(Role.NAME, "admin", AttributeFilter.OP_CONTAINS)); HashMap<String,Object> map = new HashMap<String,Object>(); map.put("ArisIdConstants.APP_CTX_PAGESIZE","2"); SearchResults<Role> sr = rm.searchRolesbyPage(attrFilters, map); while(sr.hasMore()) { List<Role> roles = sr.getNextSet(); for (int i=0; i<roles.size(); i++) //do the operations with roles.get(i) }
3.3.5 アプリケーションの保護
ターゲット・システムで作成、読取り、更新および削除(CRUD)操作を実行する一般的なセキュリティ・シナリオが2つあります。これらのシナリオを確認して、十分に理解してください。
パラメータは次のとおりです。
このリリースでは、プロキシ認証はサポートされていません。
3.3.5.1 ドメイン・レベルの資格証明の適用
このシナリオでは、ドメイン内のすべてのアプリケーションで共通の資格証明を使用してターゲット・システムに接続し、その資格証明で操作を実行します。アプリケーションは、ターゲット・システムにフットプリントを保持しません。
LDAPアダプタの構成ファイルadapters.os_xml
には、バックエンド・ディレクトリに接続するための資格証明およびホストとポートの詳細が含まれています。初期化時に他の資格証明を指定しない場合、アプリケーションはLDAPアダプタの構成ファイル内の資格証明を使用してターゲット・システムに接続します。
プロキシ・ユーザー(ログイン・ユーザーID)がAPIのアプリケーション・コンテキストで指定されていない場合、ArisID操作は、LDAPアダプタの構成ファイル内にある資格証明を使用して実行されます。
アプリケーションが共通の資格証明を使用して接続する場合、認可されたユーザーについてのみデータを表示したり、変更するようアプリケーション自体にセキュリティを組み込む必要があります。
LDAPアダプタの構成ファイルadapters.os_xml
がバックエンド・ディレクトリへの接続にドメイン・レベルのuserid
と暗号化されたパスワードを使用するように構成されている次の例について考えます。次に示すのは、adapters.os_xml
のスニペットです。
<binddn>cn=admin</binddn> <bindpass>{OMASK}C2QXW1Nmf+s=</bindpass>
ArisID APIの初期化時、資格証明を指定しません。
Map env = new HashMap(); // Do not set UserManager.SECURITY_PRINCIPAL & SECURITY_CREDENTIALS UserManager uMgr = new UserManager(env); … … // Search Operation (with no proxy user in app context) List<PropertyFilterValue> attrFilters = new ArrayList<PropertyFilterValue>(); attrFilters.add(new PropertyFilterValue("User.FIRSTNAME", "app1", AttributeFilter.OP_CONTAINS)); attrFilters.add(new PropertyFilterValue("User.LASTNAME", "user1", AttributeFilter.OP_BGNSWITH)); Map<String, Object> appCtx = null; users = um.searchUsers(attrFilters, appCtx);
3.3.5.2 アプリケーション・レベルの資格証明の適用
このシナリオでは、各アプリケーションでアプリケーション・レベルの資格証明を使用してターゲット・システムに接続し、その資格証明でCRUD操作を実行します。
この場合、ArisID APIの初期化時にアプリケーションのユーザーIDとパスワードを指定します。そうすると、アプリケーションはそれらの資格証明を使用してターゲット・システムに接続します。
プロキシ・ユーザーがAPIのアプリケーション・コンテキストに指定されていない場合、アプリケーションの資格証明を使用してArisID操作が実行されます。
この使用例には、次の機能があります。
-
各アプリケーションは、ターゲット・システムのデータの表示および更新を行うための異なる権限を持ちます。
-
ターゲット・システムで各アプリケーションによって行われる変更を監査できます。
LDAPアダプタの構成ファイルadapters.os_xml
がバックエンド・ディレクトリへの接続にドメイン・レベルのuseridと暗号化されたパスワードを使用するように構成されているシナリオについて考えます。次に示すのは、adapters.os_xml
のスニペットです。
<binddn>cn=admin</binddn> <bindpass>{OMASK}C2QXW1Nmf+s=</bindpass>
ArisID APIの初期化時、アプリケーションのユーザー資格証明を指定します。
Map env = new HashMap(); env.put(UserManager.SECURITY_PRINCIPAL, "cn=app1_user,cn=users,dc=example,dc=com"); env.put(UserManager.SECURITY_CREDENTIALS, "mypassword"); UserManager uMgr = new UserManager(env); … // Search Operation (with no proxy user in app context) List<PropertyFilterValue> attrFilters = new ArrayList<PropertyFilterValue>(); attrFilters.add(new PropertyFilterValue("User.FIRSTNAME", "app1", AttributeFilter.OP_CONTAINS)); attrFilters.add(new PropertyFilterValue("User.LASTNAME", "user1", AttributeFilter.OP_BGNSWITH));Map<String, Object> appCtx = null; users = um.searchUsers(attrFilters, appCtx);
3.3.6 タイムアウト間隔の構成
LDAP操作のタイムアウト間隔を構成できます。これらの間隔によって、LDAP操作がタイムアウトするまでの時間を指定できます。
デフォルトの接続/読取りタイムアウトは15秒に設定されています。たとえば、IdentityStore
のLDAP操作に15秒以上かかる場合、その操作はタイムアウトし、IGFでは次の例外が発生します。
org.openliberty.arisid.stack.ConnectionException
IdentityStore
に多数のエントリがあり、「次を含む」というフィルタを使用してページング/ソートで検索すると、これらの問合せはタイムアウトする場合があります。
タイムアウト値を0(タイムアウトなし)に設定し、プール・サイズを20まで増やすことをお薦めします。アプリケーションにタイムアウト間隔がある場合は、0より大きい値を設定します。
タイムアウト間隔を構成する手順は、次のとおりです。
-
次のWLSTコマンドを実行し、すべてのアダプタをリストします。
listAdapters()
-
各アダプタに対して次のコマンドを実行し、
timeout
およびmaxpoolsize
を設定します。-
modifyLDAPAdapter('<ADAPTER NAME>', 'OperationTimeout', 0)
-
modifyLDAPAdapter('<ADAPTER NAME>', 'MaxPoolSize', 20)
-
-
WebLogic Serverを再起動します。
3.3.7 検索フィルタでのワイルドカード文字の指定
Oracle Internet Directoryでは、DN属性のワイルドカード検索がサポートされます。
Oracleディレクトリ以外のディレクトリでは、ワイルドカード検索がサポートされないことがあります。そのため、バックエンドのMicrosoft Active Directoryなどとともに検索フィルタでDNを使用して、Identity Governance Framework APIを通じてseachUsers
操作を実行する場合、正常にその操作を実行するには、AttributeFilter.OP_EQUALS
演算子を指定する必要があります。
3.4 ArisID Beanの生成
CARMLファイルの編集が終了したら、アプリケーションで使用するArisID Beanを生成できます。ArisID Beanは、関連する様々な処理メソッドを持ち、ArisID APIの上位レイヤーとなるJava APIを提供します。
ArisID Beanを生成するには、次のコマンドを実行します:
java BeanGenerator [-genmap] <package name> <output dir> [<relationship file>] <carml file>
ここで、
-
-genmap
は、CARMLファイルと同じ場所にCARML-ArisIDStack
マップ・ファイルを生成します。 -
package name
は、生成されたBeanクラスのパッケージ名です。 -
output dir
は、生成されたBeanクラスの書込み先です。 -
relationship file
は、エンティティ間のリレーションシップ定義を含むファイルです。 -
carml file
は、CARML宣言ファイルです。
CARMLファイルからORG
Beanをビルドする手順は次のとおりです。
-
ORG
エンティティ用の適切な属性または相互作用を指定する、CARMLファイル名org.xmlを作成します。 -
Beanジェネレータを使用して、
org
Bean(OrgManager.java
およびOrg.java
)を生成します。build.xmlファイルの内容は、次のサンプルのようになります。<path id="ArisIDBeans.classpath"> <pathelement location="MW_HOME/oracle_common/modules/velocity-dep-1.4.jar" /> <pathelement location="MW_HOME/oracle_common/modules/oracle.jrf_11.1.1/jrf.jar" /> </path> <property name="BeanGeneratorClassPath" refid="ArisIDBeans.classpath"/> <target name="generatebeans" description="generate arisid beans"> <java classname="org.openliberty.arisidbeans.BeanGenerator" dir="${generatedsource.dir}" fork="true"> <arg value="${generatedbean.userrole.packagename}"/> <arg value="."/> <arg value="${carml.dir}/org.xml"/> <classpath> <pathelement path="${BeanGeneratorClassPath}"/> </classpath> <sysproperty key="org.openliberty.arisid.policy.wspolicy.class" value="org.openliberty.arisid.policy.neethi.PolicyImpl" /> </java> </target>
-
生成されたJavaファイル(
Org.java
およびOrgManager.java
)をコンパイルします。 -
生成されたマッピング・ファイル(igf-map-config-.xml)を編集して、
basesearch
、objectclass
、OVD
属性名でそれぞれの値を更新します。 -
アプリケーションでは、CARMLファイル(org.xml)に定義されている相互作用用の生成された
ORG
APIを使用できます。アプリケーションをアプリケーション・サーバーにデプロイした後で、次の作業を行います。-
マッピング・ファイルをDOMAIN_HOME/config/fmwconfig/arisidprovider/confにコピーします。
-
CARMLファイルをDOMAIN_HOME/config/fmwconfig/carmlにコピーします。
-
3.5 IDXユーザーおよびロールBeanの使用例
IDXユーザー/ロールBeanの使用方法を理解することが重要です。IDXユーザー/ロールBeanをアプリケーションに統合する方法を理解するには、次のサンプル・アプリケーションを使用します。
次の各トピックで、IDXユーザー/ロールBeanの使用について説明します。
3.5.1 IDXユーザーおよびロールBeanを使用したユーザーの検索: SearchUsers.jsp
IDXユーザー/ロールBean Javaバージョンを使用してユーザーを検索します。
<%@ page language="java" contentType="text/html; charset=ISO-8859-1" pageEncoding="ISO-8859-1"%> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <%@page import="org.openliberty.arisid.*"%> <%@page import="org.openliberty.arisidbeans.*"%> <%@page import="oracle.igf.userrole.*"%> <%@page import="java.util.*"%> <%@page import="java.net.URI"%> <%!public static UserManager uMgr = null; { try { uMgr = new UserManager(null); } catch (Exception e) { e.printStackTrace(); } } %> <html> <head> <title>Search Users</title> <% String firstname = request.getParameter("firstname"); String lastname = request.getParameter("lastname"); String telephone = request.getParameter("telephone"); List<PropertyFilterValue> attrFilters = new ArrayList<PropertyFilterValue>(); attrFilters.add(new PropertyFilterValue("firstname", firstname, AttributeFilter.OP_BGNSWITH)); attrFilters.add(new PropertyFilterValue("lastname", lastname, AttributeFilter.OP_BGNSWITH)); attrFilters.add(new PropertyFilterValue("telephone", telephone, AttributeFilter.OP_CONTAINS)); List<User> subjs = uMgr.searchUsers(attrFilters); %> </head> <body> <a href="SearchUsers.html">Home</a> <center>List of Users with FirstName starting with "<%=firstname%>", LastName starting with "<%=lastname%>" and TelephoneNumber containing "<%=telephone%>"</center> <% Iterator<User> sIter = subjs.iterator(); while (sIter.hasNext()) { User subj = sIter.next(); Map<String, IAttributeValue> vals = subj.getAllAttributes(); Iterator<IAttributeValue> iter = vals.values().iterator(); %> <table border="0"> <tr> <th>Item</th> <th>Value</th> </tr> <% while (iter.hasNext()) { IAttributeValue val = iter.next(); String name = val.getNameIdRef(); String value = null; if (val.size() > 0) value = val.get(0); if (value != null) { %> <tr> <td><%=name%></td> <td><%=value%></td> </tr> <% } } %> </table> <% } %> <br> <br> <br> <a href="SearchUsers.html">Home</a> </body> </html>
3.5.2 IDXユーザーおよびロールBeanを使用したユーザーの検索: SearchUsers.html
IDXユーザー/ロールBeanコードを使用してユーザーを検索します。
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <HTML> <HEAD><TITLE>Search Users</TITLE></HEAD> <BODY> <FORM METHOD=POST ACTION="SearchUsers.jsp"> First Name Starting with <INPUT TYPE=TEXT NAME=firstname SIZE=30><BR><BR> Last Name Starting with <INPUT TYPE=TEXT NAME=lastname SIZE=30><BR><BR> Telephone Number containing <INPUT TYPE=TEXT NAME=telephone SIZE=15><BR><BR> <P><INPUT TYPE=SUBMIT> </FORM> </BODY> </HTML>
3.6 OpenLDAPに関する考慮事項について
OpenLDAPでは、APIを実装するために必須の属性をいくつか指定します。アプリケーションを実装するとき、これらの属性を考慮しておく必要があります。
OpenLDAPの場合、Role.MEMBER
は次のAPIに必須の属性です。
-
createRole(List<PropertyValue> attrVals, Map<String,Object> appCtxMap)
-
createRole(List<PropertyValue> attrVals)
入力attrVals
リストにRole.MEMBER
が含まれていない場合、ロールの作成は失敗します。