Example 2: Java EE Application with Wallet Store

25-2 Oracle Fusion Middleware Application Security Guide This API framework provides a convenient way to access repositories programmatically in a portable way, freeing the application developer from the potentially difficult task of accounting for the intricacies of particular identity sources. The framework allows an application to work against different repositories seamlessly. An application can switch between various identity repositories without any code changes being required. Supported operations include creating, updating, or deleting users and roles, or searching users and roles for attributes or information of interest. For example, you may want to search for the e-mail addresses of all users in a certain role. You can use a basic usage model without container integration or a usage model with container integration that allows your code to be portable. When the application is intended to run in the context of an Oracle WebLogic Server container, the principal class should be cast to weblogic.security.principal.WLSUserImpl. A Note about Using the User and Role API As a general rule of thumb, authentication should only be performed by authentication providers, not through the User and Role API. Additionally, it is recommended that authentication providers be configured with the connect DN of a user that does not have write privileges.

25.1.1 User and Role API and the Oracle WebLogic Server Authenticators

The User and Role API is automatically configured to use the first Oracle WebLogic Server authenticator and does not require any special configuration. F Note, however, that configuration is required if the User and Role API is going against other authenticators. The API can access data only from the first LDAP authenticator listed in an Oracle WebLogic Server domain. When more than one authenticator is present, the precedence is determined by their control flag priority. If both have the same priority, the first one is picked. Any LDAP authenticators below the first one on the list are not accessed. About Concurrent Use of WebLogic APIs Your application should not try to use both the User and Role API and the WebLogic LDAPAuthenticator API such as EmbeddedLDAPAuthenticator, OracleInternetDirectoryAuthenticator, OracleVirturalDirectoryAuthenticator to work on entries in the same LDAP server concurrently. To understand why, consider two LDAP clients, both with caching enabled, that access the same LDAP server; one is deleting entries, and the other tries to use the deleted entries. Note: These APIs are not meant for authentication or authorization functions, but for maintaining identity information. Note: The following are required to invoke the User and Role API: ■ The identity store is LDAP-based ■ The domain administration server is up and running Developing with the User and Role API 25-3 The conflict caused by the two clients cannot be resolved unless caching capability is disabled, and the LDAP operations are coordinated among the clients.

25.2 Summary of Roles and Classes

Table 25–1 lists the classes and interfaces of the User and Role API. Table 25–1 Classes and Interfaces in the User and Role API Name Type Description AuthenticationException Class This exception is thrown when an authentication error occurs while accessing the identity store. An authentication error can happen, for example, when the credentials supplied by the user program is invalid or otherwise fails to authenticate the user to the identity store. AuthenticationWarningException Class This class extends IMException see below. ComplexSearchFilter Interface A complex search filter represents a complex logical expression that can be used to filter results from underlying identity repository. Complex search filter combines multiple SearchFilter instances together with a single logical operator ANDOR. Each of these component SearchFilter can itself be a complex filter, enabling you to form a complex nested search filter. See the Javadoc Section 25.9, The User and Role API Reference for an example of creating a complex search filter. ConfigurationException Class This exception is thrown when there is a configuration problem. This can arise when configuration information required to access the service provider is malformed or missing. Identity Interface This interface represents a basic identity in the identity repository. IdentityStore Interface IdentityStore represents a handle to actual identity repository. This handle can be used to search, create, drop, and modify identities in the repository. IdentityStoreFactory Interface IdentityStoreFactory is a programmatic representation of underlying identity repository. Actual handle to the identity repository can be obtained by calling getIdentityStoreInstanceHashtable on this object. IdentityStoreFactoryBuilder Class This class builds the identity store factory. IMException Class This exception is the superclass of all the exceptions thrown by ADF identity management APIs. The nature of failure is described by the name of the subclass. See the Javadoc Section 25.9, The User and Role API Reference for a list of the direct known subclasses. ModProperty Class This class represents the modification of a property object. ModProperty is called with property name, modified values and type of modification. Modification type can be one of ADD, REMOVE, or REPLACE. NoPermissionException Class This exception is thrown when attempting to perform an operation for which the API caller has no permission. The access controlpermission model is dictated by the underlying identity store. 25-4 Oracle Fusion Middleware Application Security Guide ObjectExistsException Class This exception is thrown when an identity with given name is already present in the underlying identity store. For example this exception is thrown when create user API call tries to create a user with the name of an existing user. ObjectNotFoundException Class This exception is thrown when a specified identity does not exist in the identity store. OperationFailureException Class This exception is thrown when an operation fails during execution in the underlying identity store. OperationNotSupportedException Class This exception is thrown by an service provider if it does not support an operation. For example this can be thrown by the service provider, in IdentityStore.getUserManager call, if it does not provide support for UserManager. PasswordPolicyException Class This class extends IMException see above. Property Class Property contains name-value information. PropertySet Class A collection of property name and value pairs. Property class is used to represent the property name and values pair. PropertySet guarantees that no two properties have same name. Role Interface This interface represents a role in the identity store. RoleManager Interface This interface represents a role manager that manages execution of various operations, involving roles, in the identity repository. RoleProfile Interface This interface represents the detailed profile of a role. SearchFilter Interface This interface represents a search filter to be used in searching the identity repository. SearchParameters Class This class represents search parameters that need to be specified while performing searches on the identity store. These search parameters are: ■ Search filter, ■ Search identity type, ■ page size, ■ time limit, and ■ count limit. SearchResponse Interface This interface represents search results obtained after searching the identity store. Its implementation is service provider-specific. SimpleSearchFilter Interface This interface represents a simple search filter to be used while searching the identity repository. Each simple search filter is a logical expression consisting of a search attributeproperty, evaluation operator and value. This logical expression will be applied to the underlying identity repository while searching and matching results will be filtered out. See the Javadoc Section 25.9, The User and Role API Reference for an example of a simple search filter. StoreConfiguration Interface StoreConfiguration holds the configuration properties for a given IdentityStore instance. The behavior of this IdentityStore instance can be controlled by changing the properties in this configuration object. The actual configuration properties and their values are specific to the service provider. Some service providers may not support any configuration property at all. Table 25–1 Cont. Classes and Interfaces in the User and Role API Name Type Description Developing with the User and Role API 25-5

25.3 Working with Service Providers

In this section we describe basic provider concepts and life cycle, and explain how to set up, configure, and use the provider to work with user repositories in an Oracle Platform Security Services environment. After ensuring the environment is properly set up, implementing the provider involves: ■ identifying the underlying repository and selecting the provider factory class appropriate to that repository ■ creating instances of the provider factory and the identity store ■ configuring the provider This section contains these topics: ■ Understanding Service Providers ■ Setting Up the Environment ■ Selecting the Provider ■ Properties for Provider Configuration ■ Programming Considerations ■ Provider Life cycle

25.3.1 Understanding Service Providers

Although the User and Role API is called for user and role management, the API does not directly interact with the underlying identity repository. Instead, security applications make use of providers which carry out the actual communication with the underlying repository. This offers flexibility since the same code can be used with various underlying repositories simply by modifying the providerconnection information. SubjectParser Interface This interface provides utility methods for extracting out the user and role principals from the given Subject. Service provider needs to provide the implementation for this interface. User Interface This interface represents a user in the identity store. UserManager Interface This interface represents a user manager that manages execution of various operations, involving users, in the identity repository. UserProfile Interface This interface represents the detailed profile of a user. It allows for user properties to be accessed in a generic manner. You can read or modify any property of user with these APIs: ■ getPropertyjava.lang.String ■ getPropertiesjava.lang.String[] ■ setPropertyoracle.security.idm.ModProperty ■ setPropertiesoracle.security.idm.ModProperty[] Table 25–1 Cont. Classes and Interfaces in the User and Role API Name Type Description