User Authentication The User and Role API Reference

25-26 Oracle Fusion Middleware Application Security Guide guid=+usr.getGUID; System.out.printlnuser name = +usr.getName ; modifying user properties System.out.printlnDISPLAY_NAME=+usr.getDisplayName; System.out.printlnmodifying property UserProfile.DISPLAY_NAME; UserProfile usrprofile = usr.getUserProfile; ModProperty mprop = new ModPropertyUserProfile.DISPLAY_NAME, modified display name, ModProperty.REPLACE; usrprofile.setPropertymprop; System.out.printlnget property values UserProfile.DISPLAY_NAME; Property prop = usrprofile.getPropertyUserProfile.DISPLAY_NAME; List values = prop.getValues; Iterator itr = values.iterator; whileitr.hasNext { System.out.printlnUserProfile.DISPLAY_NAME+: + itr.next; } System.out.println; System.out.printlnnow verifying the password; boolean pass = false; try { usrmanager.authenticateUserusrname, password; pass= true; }catch oracle.security.idm.AuthenticationException e { System.out.printlne; e.printStackTrace; } if pass System.out.printlnpassword verification SUCCESS ; else System.out.printlnpassword verification FAILED ; SimpleSearchFilter sf = adStore.getSimpleSearchFilter UserProfile.NAME, SimpleSearchFilter.TYPE_EQUAL, usrname; SearchParameters params = new SearchParameters; params.setFiltersf; Searching for users SearchResponse resp = adStore.searchUsersparams; System.out.printlnSearched users are:; while resp.hasNext { Identity idy = resp.next; System.out.printlnname: +idy.getName+\tUnique name: +idy.getUniqueName; } drop user System.out.printlnNow dropping user +usrname; usrmanager.dropUserusr; System.out.printlnuser dropped; Developing with the User and Role API 25-27 }catch Exception e { e.printStackTrace; } } }

25.8 SSL Configuration for LDAP-based User and Role API Providers

This section describes SSL support for the User and Role API. It contains these topics: ■ Out-of-the-box Support for SSL ■ Customizing SSL Support for the User and Role API

25.8.1 Out-of-the-box Support for SSL

LDAP-based providers for the User and Role API rely on the Sun Java Secure Sockets Extension JSSE to provide secure SSL communication with LDAP-based identity stores. JSSE is part of JDK 1.4 and higher. These LDAP providers are: ■ Microsoft Active Directory ■ Novell eDirectory ■ Oracle Directory Server Enterprise Edition ■ Oracle Internet Directory ■ OpenLDAP ■ Oracle WebLogic Server Embedded LDAP Directory

25.8.1.1 System Properties

To support SSL you must provide the following information in the form of system properties: javax.net.ssl.keyStore javax.net.ssl.keyStorePassword javax.net.ssl.trustStore javax.net.ssl.trustStorePassword Refer to Sun Microsystems’ documentation on JSSE for details.

25.8.1.2 SSL configuration

You need to provide SSL configuration details during User and Role API configuration. Provide your keystore location and password as system properties to the JVM: String keystore = key store location; String keypasswd = key store password; System.setPropertyjavax.net.ssl.trustStore,keystore; System.setPropertyjavax.net.ssl.trustStorePassword, keypasswd; 25-28 Oracle Fusion Middleware Application Security Guide Specify following properties in the environment when creating the IdentityStoreFactory instance: 1. Set the SSL URL of the LDAP server, as in this example: factEnv.putADIdentityStoreFactory.ST_LDAP_URL, ldaps:ldaphost:sslport; 2. Set the security protocol to SSL: factEnv.putjava.naming.security.protocol,SSL;

25.8.2 Customizing SSL Support for the User and Role API

You can customize SSL support by providing a customized SSLSocketFactory to the User and Role API provider.

25.8.2.1 SSL configuration

Specify the following properties when creating the IdentityStoreFactory instance: 1. Specify the custom SSL socket factory name: factEnv.putjava.naming.ldap.factory.socket, fully qualified custom socket factory name; 2. Set the SSL URL of the LDAP server, as in this example: factEnv.putADIdentityStoreFactory.ST_LDAP_URL, ldaps:ldaphost:sslport; 3. Set the security protocol to SSL: factEnv.putjava.naming.security.protocol,SSL;

25.9 The User and Role API Reference

The User and Role API reference Javadoc is available at: Oracle Fusion Middleware User and Role Java API Reference for Oracle Platform Security Services

25.10 Developing Custom User and Role Providers

This section explains how to develop custom providers that security developers can use to manage identities users and roles. It contains these topics: ■ SPI Overview ■ Types of User and Role Providers ■ Developing a Read-Only Provider ■ Developing a Full-Featured Provider ■ Development Guidelines ■ Testing and Verification ■ Example: Implementing an Identity Provider Developing with the User and Role API 25-29

25.10.1 SPI Overview

The User and Role API is accompanied by a service provider interface SPI that makes it possible to develop custom userrole providers. You can use the service provider interface to develop a custom provider for any identity data repository. The SPI is bundled as the oracle.security.idm.spi package, which is a set of abstract classes. Custom User and Role providers are created by extending this SPI to fit your requirements.

25.10.2 Types of User and Role Providers

The User and Role API offers functions for both search and CreateReadUpdateDelete CRUD operations. A User and Role provider based on read-only functions supports only search operations. A full-featured provider supports both search operations and CRUD operations. In other words, the full-featured provider is a superset of a read-only provider. As a developer you have the choice of creating either read-only or full-functionality providers depending upon the requirements. It is reasonable to develop a read-only provider in the following situations: ■ if the underlying identity repository operates in read-only mode ■ if applications consuming the User and Role API do not make any CRUD API calls For example, it makes sense to develop a read-only provider for use with the SOA identity service.

25.10.3 Developing a Read-Only Provider

This section describes the classes used to implement a provider. Topics include: ■ SPI Classes Requiring Extension ■ oracle.security.idm.spi.AbstractIdentityStoreFactory ■ oracle.security.idm.spi.AbstractIdentityStore ■ oracle.security.idm.spi.AbstractRoleManager ■ oracle.security.idm.spi.AbstractUserManager ■ oracle.security.idm.spi.AbstractRoleProfile ■ oracle.security.idm.spi.AbstractUserProfile ■ oracle.security.idm.spi.AbstractSimpleSearchFilter ■ oracle.security.idm.spi.AbstractComplexSearchFilter ■ oracle.security.idm.spi.AbstractSearchResponse

25.10.3.1 SPI Classes Requiring Extension

Table 25–5 shows that SPI classes that must be extended to implement a read-only provider: See Also: The User and Role SPI Reference Note: All abstract methods must be implemented. 25-30 Oracle Fusion Middleware Application Security Guide Additional requirements and notes for each class are provided below.

25.10.3.2 oracle.security.idm.spi.AbstractIdentityStoreFactory

The class extending this SPI class must have following constructors: 1. The default constructor one which has no arguments. 2. A constructor that accepts a java.util.Hashtable object as an argument. You can use the hash table to accept any configuration properties required by the provider. The configuration properties are passed to this constructor during the user and role configuration phase. The properties are key-value pairs passed in the Hashtable argument: ■ The key must be java.lang.String. ■ The value can be java.lang.Object. It is recommended that the value be of type String. This guarantees that the property can be specified in jps-config.xml, which is a text file.

25.10.3.3 oracle.security.idm.spi.AbstractIdentityStore

The User and Role SPI Reference provides details about the methods that need to be implemented in this class. Note that: ■ Method getStoreConfiguration is optional and can throw OperationNotSupportedException. ■ Method getSubjectParser can return null. When there are no search results to be returned, all search APIs should throw: oracle.security.idm.ObjectNotFoundException Table 25–5 SPI Classes to Extend for Custom Provider Class Usage Notes oracle.security.idm.spi.AbstractIdentityStoreFactory The extending class must include a default constructor and a constructor accepting a java.util.Hashtable object. oracle.security.idm.spi.AbstractIdentityStore oracle.security.idm.spi.AbstractRoleManager oracle.security.idm.spi.AbstractUserManager oracle.security.idm.spi.AbstractRoleProfile oracle.security.idm.spi.AbstractUserProfile oracle.security.idm.spi.AbstractSimpleSearchFilter The constructor of the extending class must call the constructor of the abstract super class. oracle.security.idm.spi.AbstractComplexSearchFilter The constructor of the extending class must call the constructor of the abstract super class. oracle.security.idm.spi.AbstractSearchResponse See Also: The User and Role SPI Reference for details about the methods that need to be implemented in this class. All listed methods must be implemented. Developing with the User and Role API 25-31 Never return an empty SearchResponse.

25.10.3.4 oracle.security.idm.spi.AbstractRoleManager

The User and Role SPI Reference provides details about the methods that need to be implemented in this class. Note that only the following methods need concreteactual implementations: ■ getGrantedRoles ■ getOwnedRoles ■ getManagedRoles ■ isGranted ■ isManagedBy ■ isOwnedBy ■ isDropRoleSupported – should always return false ■ isCreateRoleSupported – should always return false ■ isModifyRoleSupported – should always return false The remaining methods must throw the following in their respective implementations: oracle.security.idm.OperationNotSupportedException

25.10.3.5 oracle.security.idm.spi.AbstractUserManager

The User and Role SPI Reference provides details about the methods that need to be implemented in this class. Only the following methods need concreteactual implementations: ■ authenticateUserUser, char[] ■ authenticateUserString, char[] ■ isDropUserSupported – should always return false ■ isCreateUserSupported – should always return false ■ isModifyUserSupported – should always return false The remaining methods must throw the following in their respective implementations: oracle.security.idm.OperationNotSupportedException

25.10.3.6 oracle.security.idm.spi.AbstractRoleProfile

oracle.security.idm.spi.AbstractRoleProfile is an abstract class that can be used to return a detailed role profile. The User and Role SPI Reference provides details about the methods that need to be implemented in this class. Only the following methods need concreteactual implementations: ■ getDisplayName ■ getGUID ■ getName 25-32 Oracle Fusion Middleware Application Security Guide ■ getUniqueName ■ getPrincipal ■ getDescription ■ getGrantees ■ getManagers ■ getOwners ■ getProperty - If requested property is not setvalid for corresponding role then null should be returned as value. ■ isApplicationRole - must always return false ■ isEnterpriseRole - must always return false ■ isSeeded - must always return false ■ getRoleProfile – should return reference to current object. The remaining methods must throw the following in their respective implementations: oracle.security.idm.OperationNotSupportedException

25.10.3.7 oracle.security.idm.spi.AbstractUserProfile

oracle.security.idm.spi.AbstractUserProfile is an abstract class that can be used to return a detailed user profile. The User and Role SPI Reference provides details about the methods that need to be implemented in this class. Only the following methods need concreteactual implementations: ■ getDisplayName ■ getGUID ■ getName ■ getUniqueName ■ getPrincipal ■ getProperty - If the requested property is not setvalid for corresponding role then a null value must be returned. ■ getProperties – If the requested property is not setvalid for the corresponding user, then a null value must be returned. ■ getAllUserProperties – Only the properties set for the corresponding user should be returned. ■ getReportees ■ getManagementChain ■ getUserProfile – must return reference to current object. These two methods: ■ setProperty ■ setProperties must throw the following in their implementation: Developing with the User and Role API 25-33 oracle.security.idm.OperationNotSupportedException

25.10.3.8 oracle.security.idm.spi.AbstractSimpleSearchFilter

oracle.security.idm.spi.AbstractSimpleSearchFilter is an abstract class that can be extended to implement a simple search filter. The implementing class must have a constructor that calls the constructor of the abstract class: AbstractSimpleSearchFilter String attrname, int type, Object value The User and Role SPI Reference provides details about the methods that need to be implemented in this class. Only the following methods need concreteactual implementations: ■ getNativeRepresentation – convert filter into the native representation to be used with the underlying identity repository. ■ getWildCardChar – wild card character, for example , to be used in searches. The specific character depends on the underlying identity repository.

25.10.3.9 oracle.security.idm.spi.AbstractComplexSearchFilter

oracle.security.idm.spi.AbstractComplexSearchFilter is an abstract class that can be extended to implement a search filter of any complexity. The implementing class must have a constructor that calls the constructor of the abstract class: AbstractComplexSearchFilter oracle.security.idm.SearchFilter[] filters, int oper_type The User and Role SPI Reference provides details about the methods that need to be implemented in this class. Only the following methods need concreteactual implementations: ■ getNativeRepresentation – convert the filter into the native representation to be used with the underlying identity repository.

25.10.3.10 oracle.security.idm.spi.AbstractSearchResponse

The SearchResponse object contains search results being returned from a repository. Each result entry corresponds to one user or role in the underlying identity repository, represented by the corresponding UserProfileRoleProfile class implementation. The SearchResponse object must return one or more results. This means that the hasNext method must return TRUE at least once. Do not use if there are zero results to return. When no results are to be returned, the corresponding search API should throw the following exception: oracle.security.idm.ObjectNotFoundException 25-34 Oracle Fusion Middleware Application Security Guide

25.10.4 Developing a Full-Featured Provider

The full-featured provider implements all the functionality supported by a read-only provider, and additionally supports CRUD operations. This requires that the CRUD APIs be implemented in the SPI implementation classes. In the read-only provider, these APIs were implemented simply by throwing an OperationNotSupportedException see the class descriptions in Section 25.10.3, Developing a Read-Only Provider . For a full-featured provider, this needs to be replaced by concreteactual implementation of the corresponding CRUD operations.

25.10.5 Development Guidelines

This section provides some guidelines for developing providers. Mapping of Names Be aware of the usage of naming constants such as UserProfile.NAME, UNIQUE_ NAME, UserProfile.USER_NAME, UserProfile.USER_ID. ■ NAME – name of the user or role in the underlying repository. ■ UNIQUE_NAME – Complete name with which the user or role is represented in the underlying repository. ■ USER_NAME – login ID of the user in the underlying repository. ■ USER_ID – always same as USER_NAME constant mapping. Depending on the identity repository, these constants might map to the same underlying identity repository attribute or they might map to different attributes. If the underlying repository is an LDAP v3 server, the mappings are as follows: ■ NAME – mapped to naming attribute of usergroup entry, for example cn ■ UNIQUE_NAME - mapped to DN of usergroup entry ■ USER_NAMEUSER_ID – mapped to login attribute, for example uid or mail Thread Safety The following objects are likely to be shared among multiple threads: ■ IdentityStoreFactory, ■ IdentityStore, ■ UserManager, ■ RoleManager You should ensure that there are no thread safety-related issues in the corresponding implementation classes of your provider.

25.10.6 Testing and Verification

The User and Role API ships with a test suite to enable you to test the basic operations of providers that you develop. The test suite can be used to test both read-only and full-featured providers. Usage java oracle.security.idm.tests.SPITest propertiesfile Developing with the User and Role API 25-35 where propertiesfile contains the provider class name and any configuration data for the provider. It also contains information about the tests to be run. You need to edit this file and update it with correct information before running the tests; the file contents are self-explanatory. One such file ffprovider.properties is available with the sample provider discussed in Section 25.10.7.1, About the Sample Provider . Results The test will produce the results on-screen. All providers that you develop must pass the Lookup tests, Role membership tests and Profile tests in the test suite. Full-featured providers must pass all the tests in the suite including CreateDrop tests. The log of test results will be output to the file results.out in current working directory.

25.10.7 Example: Implementing an Identity Provider

The distribution includes a sample identity provider that you can use to understand how custom providers are built. This section describes how to access the sample provider, and explains the steps needed to implement a custom provider. The steps rely on the sample for illustration. ■ About the Sample Provider ■ Overview of Implementation ■ Configure jps-config.xml to use the Sample Identity Provider ■ Configure Oracle WebLogic Server

25.10.7.1 About the Sample Provider

The sample provider is bundled in sampleprovider.zip. Unzip the file. It should generate the following structure: sampleprovider build.xml - ant build file ffprovider.properties - properties file required for testing jlib - provider jar file location out - location of generated class files samples - Folder for samples src - provider source code Run ant help for instructions on building and testing this provider. The provider relies on an ad-hoc identity repository for fetching identity information and has been tested with Oracle SOA Suite. It is not intended for production use without appropriate testing for your environment.

25.10.7.2 Overview of Implementation

The sample identity provider used in this example is a custom IdentityAuthentication provider that uses an RDBMS as the underlying store. It can be used as both an identity provider and an authentication provider.