24-12 Oracle Fusion Middleware Application Security Guide
codesource grantee
permissions permission
classoracle.security.jps.service.credstore.CredentialAccessPermission class
namecontext=SYSTEM,mapName=pc_map,keyName=name actionsread,writeactions
permission permission
classoracle.security.jps.service.credstore.CredentialAccessPermission class
namecontext=SYSTEM,mapName=gc_map,keyName=gc_keyname actionswriteactions
permission permissions
grant
Note that the first map and key permissions enable both read and write operations; the second enable write operations but not reads.
jps-config.xml File A portion of the default configuration file jps-config.xml showing the credential
store configuration is as follows:
jpsConfig serviceProviders
serviceProvider type=CREDENTIAL_STORE name=credstoressp class=oracle.security.jps.internal.credstore.ssp.SspCredentialStoreProvider
descriptionSecretStore-based CSF providerdescription serviceProvider
serviceProviders serviceInstances
serviceInstance name=credstore provider=credstoressp property name=location value=.
serviceInstance serviceInstances
jpsContexts default=default jpsContext name=default
... serviceInstanceRef ref=credstore
... jpsContext
jpsContexts jpsConfig
The location property specifies the wallet location; this specification is essentially the same as in Example 1, except that in this example the wallet is located inside the
configuration directory. The wallet name is always cwallet.sso.
Java Code package demo;
import demo.util.CsfUtil; import java.io.IOException;
import java.io.PrintWriter;
Developing with the Credential Store Framework 24-13
import java.net.URL; import java.util.Date;
import javax.servlet.; import javax.servlet.http.;
import oracle.security.jps.JpsException; import oracle.security.jps.service.JpsServiceLocator;
import oracle.security.jps.service.credstore.CredentialStore; public class CsfDemoServlet extends HttpServlet {
private static final String CONTENT_TYPE = texthtml; charset=windows-1252; public void initServletConfig config throws ServletException {
super.initconfig; }
public void doGetHttpServletRequest request, HttpServletResponse response throws ServletException,
IOException { response.setContentTypeCONTENT_TYPE;
PrintWriter out = response.getWriter; ServletOutputStream out = response.getOutputStream;
try { response.setContentTypetexthtml;
out.printlnhtmlbody bgcolor=\FFFFFF\; out.printlnbCurrent Time: b + new Date.toString +
brbr; This is to get hold of app-level CSF service store
Outside app context, this call returns domain-level CSF store This call also works in Java SE env
final CredentialStore store = JpsServiceLocator.getServiceLocator.lookupCredentialStore.class;
CsfUtil csf = new CsfUtilstore; csf.doPrivilegedCredOperation;
out.printlnCredential operations completed using privileged code.; } catch JpsException e {
e.printStackTraceout; }
} }
The credential create operation is conducted using privileged code. The success of the operation can be verified by using the WLST listCred command:
listCredmap=pc_map, key=pc_key
Note About Java SE Environment In the Java SE environment, the following calls are equivalent:
CredentialStore store = JpsServiceLocator.getServiceLocator.lookupCredentialStore.class;
and: CredentialStore store =
24-14 Oracle Fusion Middleware Application Security Guide
JpsContextFactory.getContextFactory.getContext.getServiceInstanceCredentialSt ore.class;
The latter call is shown in Section 24.7.2, Example 1: Java SE Application with Wallet
Store .
24.7.4 Example 3: Java EE Application with LDAP Store
This example uses the same Java EE application used earlier in Example 2. The only difference is that the credential store is LDAP-based and not file wallet based.
You need to configure the following properties in the domain-level jps-config.xml file:
■
root name property name=oracle.security.jps.ldap.root.name
value=cn=OracleJpsContainer
■
farm name property name=oracle.security.jps.farm.name value=cn=OracleFarmContainer
The configuration of the LDAP store in jps-config.xml is as follows: jpsConfig
serviceProviders serviceProvider name=credstore_ldap_provider
class=oracle.security.jps.internal.credstore.ldap.LdapCredentialStoreProvider descriptionPrototype LDAP-based CSF providerdescription
serviceProvider serviceProviders
serviceInstances
serviceInstance provider=ldap.credentialstore.provider name=credstore.ldap
property value=bootstrap name=bootstrap.security.principal.key
property value=cn=wls-jrfServer name=oracle.security.jps.farm.name
property value=cn=jpsTestNode name=oracle.security.jps.ldap.root.name
property value=ldap:mynode.us.mycorp.com:1234 name=ldap.url
serviceInstance
serviceInstances jpsContexts default=appdefault
jpsContext name=appdefault serviceInstanceRef ref=credstore_ldap_instance
jpsContext jpsContexts
jpsConfig
The highlighted lines define the LDAP parameters necessary to locate the credentials.
Developing with the Credential Store Framework 24-15
24.8 Best Practices
In a clustered environment, use the Credential Store Mbean API over the Credential Store Framework API to create, retrieve, update, and delete credentials for an
application.
If you are simply reading credentials, however, either API can be used.
24-16 Oracle Fusion Middleware Application Security Guide
25
Developing with the User and Role API 25-1
25
Developing with the User and Role API
This chapter describes how to work with the API for user and role management. Prior to using this information, it is strongly recommended that you familiarize yourself
with the context in which the API is used. For details, see:
■
Chapter 19, Developing Secure Applications with Oracle Platform Security Services
■
Section 19.2.2, The User and Role API This chapter contains these topics:
■
Introduction to the User and Role API Framework
■
Summary of Roles and Classes
■
Working with Service Providers
■
Searching the Repository
■
User Authentication
■
Creating and Modifying Entries in the Identity Store
■
SSL Configuration for LDAP-based User and Role API Providers
■
The User and Role API Reference
■
Developing Custom User and Role Providers
■
The User and Role SPI Reference
25.1 Introduction to the User and Role API Framework
The User and Role API framework allows applications to access identity information users and roles in a uniform and portable manner regardless of the particular
underlying identity repository. The repository could be an LDAP directory server such as Oracle Internet Directory, Active Directory from Microsoft, or Oracle Directory
Server Enterprise Edition, or could be a database, flat file, or some other custom repository.
Note: The User and Role API is deprecated and may be withdrawn
in a future release. Your new applications should be developed on the Identity Governance Framework. Plan to migrate existing applications
to the Identity Governance Framework in a future release.
For details, see the Oracle Fusion Middleware Identity Governance Framework ArisID API Developers Guide.
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
25-6 Oracle Fusion Middleware Application Security Guide
25.3.2 Setting Up the Environment
Jar Configuration Several jars must be present in your environment:
■
the provider jar file, which implements the desired underlying identity repository
■
the User and Role API jars
■
other component jars which the provider may need, including Toplink, jdbc, xdb, and so on
Ensure that your application classpath includes the relevant jars.
User Classes in jps-config.xml Oracle Virtual Directory only
For efficiency when fetching user attributes, add the following entry in jps-config.xml to specify the user object classes for the search:
. .
serviceInstance name=idstore.ldap provider=idstore.ldap.provider property name=idstore.config.provider
value=oracle.security.jps.wls.internal.idstore.WlsLdapIdStoreConfigProvider property name=CONNECTION_POOL_CLASS
value=oracle.security.idm.providers.stdldap.JNDIPool extendedProperty
nameuser.object.classesname values
valuetopvalue valuepersonvalue
valueinetorgpersonvalue valueorganizationalpersonvalue
valueotherActiveDirectorySpecificClassesvalue ...
values extendedProperty
. .
25.3.3 Selecting the Provider
Oracle Platform Security Services support a range of user repositories, including the following LDAP directories:
■
Microsoft Active Directory
■
Novell eDirectory
■
Oracle Directory Server Enterprise Edition
■
Oracle Internet Directory
■
Oracle Virtual Directory
■
OpenLDAP
Note: Make this change only for the Oracle Virtual Directory
authenticator.
Developing with the User and Role API 25-7
■
Oracle WebLogic Server Embedded LDAP Directory
■
Microsoft ADAM
■
IBM Tivoli The choice of identity repository dictates the provider class to use with the provider.
The provider class must implement the interface specified by the User and Role API framework.
Table 25–2 shows the available provider classes:
25.3.4 Creating the Provider Instance
Once the provider’s class name is identified, take these steps to create the provider:
1.
Use the getIdentityStoreFactory method of the IdentityStoreFactoryBuilder class to build a factory instance. The builder class API accepts:
■
the provider class name
■
the necessary environment properties from a hash table
2.
Use the getIdentityStoreInstance method of the IdentityStoreFactory class to create a store instance
The following example creates a factory instance for the Oracle Internet Directory store:
IdentityStoreFactoryBuilder builder = new IdentityStoreFactoryBuilder ;
IdentityStoreFactory oidFactory = builder.getIdentityStoreFactory “oracle.security.idm.providers.oid.OIDIdentityStoreFactory, factEnv;
Now obtain the store reference, which is the actual handle to the identity store: oidStore = oidFactory.getIdentityStoreInstancestoreEnv;
Note that two hash-table objects are supplied in these examples:
Table 25–2 LDAP Identity Provider Classes
Provider Factory Name
Microsoft Active Directory
oracle.security.idm.providers.ad.ADIdentityStoreFactory Novell eDirectory
oracle.security.idm.providers.edir.EDIdentityStoreFactory Oracle Directory
Server Enterprise Edition
oracle.security.idm.providers.iplanet.IPIdentityStoreFactory Oracle Internet
Directory oracle.security.idm.providers.oid.OIDIdentityStoreFactory
OpenLDAP oracle.security.idm.providers.openldap.OLdapIdentityStoreFactory
Oracle WebLogic Server Embedded
LDAP Directory oracle.security.idm.providers.wlsldap.WLSLDAPIdentityStoreFactory
Oracle Virtual Directory
oracle.security.idm.providers.ovd.OVDIdentityStoreFactory Microsoft ADAM
oracle.security.idm.providers.ad.ADIdentityStoreFactory IBM Tivoli
oracle.security.idm.providers.openldap.OLdapIdentityStoreFactory
25-8 Oracle Fusion Middleware Application Security Guide
■
the factEnv hash table provides the factory instance environment
■
the storeEnv hash table provides the store instance environment
25.3.5 Properties for Provider Configuration
Configuration is dependent on the identity store provider being used. You can fine-tune the behavior of all types of LDAP-based identity store providers by
configuring a number of properties for the factory instance and the store instance. The following properties are relevant for LDAP-based providers only:
■
URL
■
the port at which the repository runs
■
the user and password to use in accessing the repository For a list of supported LDAP-based providers, see
Section 25.3.3, Selecting the Provider
. This section explains the following provider configuration topics:
■
Start-time and Run-time Configuration
■
ECID Propagation
■
When to Pass Configuration Values
25.3.5.1 Start-time and Run-time Configuration
The properties that can be configured fall into two categories:
■
Start-time configuration - the naming convention uses property names starting with ST_.
■
Run-time configuration - the naming convention uses property names starting with RT_.
Start-time Configuration Properties Start-time configuration is performed only once, and once set, the configuration
settings persist for the duration of the provider’s lifetime.
With the exception of ST_SUBSCRIBER_NAME, the start-time properties are specified when creating the provider factory instance; ST_SUBSCRIBER_NAME is set when
creating the store instance.
Table 25–3 lists the start-time configuration properties:
Table 25–3 Start-time Identity Provider Configuration Properties
Property Name Description
ST_BINARY_ATTRIBUTES An array of Array of String objects containing the names of
binary attributes stored in the underlying LDAP server. The provider will treat these attributes as binary while sending data
to and receiving it from the LDAP server.
ST_CONNECTION_POOL External connection pool, an instance of class
oracle.idm.connection.ConnectionPool. If set, the provider uses this pool to acquire connections to the LDAP server, and the
properties ST_SECURITY_PRINCIPAL, ST_SECURITY_ CREDENTIALS, and ST_LDAP_URL are ignored.
ST_USER_NAME_ATTR The attribute used to determine the username of the user in the
identity repository.
