Properties for Provider Configuration

Developing with the User and Role API 25-15

25.3.9.2 Considerations when Using IdentityStore Objects

Keep the following considerations in mind when coding your applications. Thread Safety The current IdentityStore implementations are not thread-safe. The User and Role API assumes that the store instances are not generally shared among threads. If the store instance is shared among threads, the application code must take care to handle any required thread safety issues. There are trade-offs between thread safety and performance. Use cases that need to implement thread safety must be willing to consider the performance implications of doing so. One Store Instance per Session In applications such as Delegated Administration Server, each session corresponding to one logged-in user can change its own createsearch bases and various other runtime settings; these are defined as runtime properties in the User and Role API. The IdentityStore object encapsulates all these settings and changes its runtime behavior accordingly. For this reason, the rule of one IdentityStore instance per session is enforced.

25.3.10 Provider Life cycle

A given provider exists for the lifetime of the factory instance created for that provider. The life of a factory instance ends whenever the close API is called on that instance. When the provider instance ends, all the objects that were created using that instance become invalid, and subsequent API calls on those objects return unanticipated output. Similar considerations apply to IdentityStore instances.

25.4 Searching the Repository

The User and Role API provides two types of query functions: ■ functions that return a single identity ■ functions that return a list of identities This section describes searches and related tasks you can accomplish with the API, and provides details on specifying search parameters: ■ Searching for a Specific Identity ■ Searching for Multiple Identities ■ Specifying Search Parameters ■ Using Search Filters ■ Searching by GUID Note: ■ Factory instances are thread-safe while this is not the case with IdentityStore instances. ■ It is best practice to cascade close server connections and explicitly delete objects and instances no longer in use. 25-16 Oracle Fusion Middleware Application Security Guide

25.4.1 Searching for a Specific Identity

You can query the identity store directly for a specific user or role using the searchUser and searchRole APIs: IdentityStore.searchUserString name; IdentityStore.searchUserPrincipal principal; IdentityStore.searchUserint searchType, String name; where searchType can be: ■ SEARCH_BY_NAME ■ SEARCH_BY_UNIQUE_NAME IdentityStore.searchRoleint searchType, Sting value; These functions facilitate simple queries where a particular userrole identity is known to exist in the store, and you simply need the object reference to that identity. The functions are minimal in that: ■ they accept only string values ■ they do not support regular expressions The functions raise an exception if multiple entities with the same value exist in the store.

25.4.2 Searching for Multiple Identities

The User and Role APIs contain several functions that can perform searches to return multiple identities: IdentityStore.searchSearchParams params; IdentityStore.searchUsersSearchParams params; IdentityStore.searchRolesint searchType, SearchParams params; IdentityStore.searchProfilesSearchParams params; Each function accepts a search object and returns a search response object.

25.4.3 Specifying Search Parameters

The SearchParams Object The SearchParams object contains the following information: ■ Search Filter - this is discussed in Section 25.4.4, Using Search Filters ■ Search Identity of type - you can search identities of type Roles or Users ■ Page Size - By default the paging option is turned off. If the query needs paging, set the page size to a relevant positive value. ■ Timeout limit – timeout is specified in seconds ■ Count Limit – limits the number of results returned by the query The SearchResponse Object SearchResponse is a data structure used when retrieving multiple identities. Your code can iterate through the identities contained in this structure using these functions: Developing with the User and Role API 25-17 ■ hasNext - returns true if more elements are present, false otherwise ■ next – returns the next element if it is available, an exception otherwise

25.4.4 Using Search Filters

The User and Role API includes different types of search filters to facilitate a variety of search operations. This section explains key facts about the use of search filters: ■ Operators in Search Filters ■ Handling Special Characters when Using Search Filters ■ Examples of Using Search Filters

25.4.4.1 Operators in Search Filters

Observe these rules when using search filter operators. Supported Operators The standard LDAP store accepts only = equals operator, less-than operator, greater-than operator, AND operator, | OR operator and NOT operator. IdentityStore provides two more operators to simplify usage, namely = less than or equal to and = greater than or equal to. The operators =, ,, = and = are used to create simple search filters while the and | operators are used to combine two or more search strings to make a complex search filter. NOT Operator You can use the NOT operator in both the simple search filter and complex search filters. This operator is used to negate the state of the filter, that is, the state of the filter is changed to accept the entities which were earlier rejected by the filter or the converse. The NOT operator is accessible using the following SearchFilter API: ■ void negate; ■ boolean isNegated;

25.4.4.2 Handling Special Characters when Using Search Filters

According to RFC-2254 String Representation of LDAP Search Filters, , , ,\ and NULL characters are to be handled separately. The User and Role API handles , and \ operators but does not handle the operator, which is also a wild-card character for LDAP stores. The API user is not required to separately handle these characters as the User and Role API framework handles these characters.

25.4.4.3 Examples of Using Search Filters

Several usage examples are presented below. Example 1: Simple Filter to Retrieve Users by Name The implementation of the simple search filter depends on the underlying store; you can obtain an instance of the search filter through the store instance. In this example, the filter allows all entries with a non-null value for the name field: 25-18 Oracle Fusion Middleware Application Security Guide SimpleSearchFilter sf = oidStore.getSimpleSearchFilterUserProfile.NAME, SimpleSearchFilter.TYPE_EQUAL, null; sf.setValuesf.getWildCardChar; Example 2: Simple Filter to Find Users by Language Preference This example retrieves users whose preferred language is not English: SimpleSearchFilter sf = oidStore.getSimpleSearchFilter UserProfile.PREFERRED_LANGUAGE, SimpleSearchFilter.TYPE_EQUAL, english; sf.negate; Example 3: Complex Filter for Names by Starting Letter This complex filter combines multiple search filters with operators or |. It searches for users whose name starts with a letter between a and j: SimpleSearchFilter sf1 = oidStore.getSimpleSearchFilter UserProfile.NAME, SimpleSearchFilter.TYPE_GREATER, null; sf1.setValuea+sf1.getWildCardChar; SimpleSearchFilter sf2 = oidStore.getSimpleSearchFilterUserProfile.NAME, SimpleSearchFilter.TYPE_LESS, null; sf2.setValuej+sf2.getWildCardChar; SimpleSearchFilter sfArray[] = new SimpleSearchFilter[] {sf1, sf2}; ComplexSearchFilter cf1 = store.getComplexSearchFiltersfArray, ComplexSearchFilter.TYPE_AND; Example 4: Complex Filter with Restrictions on Starting Letter In this example, complex filters are nested to enable a search for users whose name starts with a letter between a and j but not with the letter i: [continue from Example 3] SimpleSearchFilter sf3 = oidStore.getSimpleSearchFilter UserProfile.NAME, SimpleSearchFilter.TYPE_EQUAL, null; sf3.setValue“i”+sf3.getWildCardChar; sf3.negate; SearchFilter sfArray2[] = new SearchFilter[] {cf1, sf3}; ComplexSearchFilter cf2 = store.getComplexSearchFiltersfArray2, ComplexSearchFilter.TYPE_AND; Example 5: Complete Search with Output This example filters names starting with the letter a and outputs the return values: