Oracle® BPEL Process Manager Administrator's Guide 10g (10.1.3.1.0) Part Number B28982-03 |
|
|
View PDF |
This chapter describes how to create a custom identity service plug-in to integrate into specific third-party repositories.
This chapter contains the following topics:
You can create a custom identity service plug-in to integrate into specific third-party repositories. After you create a custom plug-in, you perform the following tasks:
Assemble all classes into a custom plug-in JAR file
Deploy the JAR file
Include the JAR file in the Oracle BPEL Process Manager classpath
Configure the is_config.xml
file
Create system (demo) users and roles
This section contains the following topics:
Table 3-1 describes the available interfaces.
Table 3-1 Interfaces
The entry point for identity service implementation is BPMIdentityService
.
package is.custom.plugin; import java.util.*; import javax.servlet.http.HttpServletRequest; import org.w3c.dom.Element; import oracle.tip.pc.infra.exception.*; import oracle.tip.pc.services.common.*; import oracle.tip.pc.services.identity.*; public class CustomIdentityService extends BPMServiceBase implements BPMIdentityService { /** * Constructor */ private CustomIdentityService(ProviderCfg provCfg) throws ServiceException { super(provCfg); } /** * Factory Method */ public static Service getInstance(String realmName) throws ServiceException { try { BPMIdentityConfigService cfgSrv = ServiceFactory.getIdentityConfigServiceInstance(); if ( realmName == null ) { realmName = cfgSrv.getDefaultRealmName(); } Configuration config = cfgSrv.getConfigurationInstance(realmName); ProviderCfg providerCfg = config.getProviderCfg( ProviderCfg.IDENTITY_SERVICE); CustomIdentityService service = new CustomIdentityService(providerCfg); return service; } catch (Exception e) { throw new ServiceException(e, DiagnosticService.SERVICESCOMPONENT); } } … /** * @see oracle.tip.pc.services.identity. BPMAuthorizationService #lookupUser(String) */ public BPMUser lookupUser(String userName) throws BPMIdentityException, BPMIdentityNotFoundException { Logger.debugLog("CustomIdentityService::lookupUser() begin"); if(userName == null) throw new BPMIdentityException( PCExceptionIndex.IDENTITYSERVICE_NAME_IS_NULL); BPMUser user = getProvider().lookupUser(userName); if(user==null) { throw new BPMIdentityNotFoundException( PCExceptionIndex.IDENTITYSERVICE_USER_NOT_FOUND, new String[] {userName, getRealmName()}); } Logger.debugLog("CustomIdentityService::lookupUser() end"); return user; } …. }
In the proceeding example, CustomIdentityService
is a class that implements the BPMIdentityService
interfaces. You must implement the BPMAuthenticationService
or BPMAutorizationService
interface if the configuration specifies CUSTOM
providerType
for only the authentication or authorization service providers:
<?xml version = '1.0' encoding = 'UTF-8'? <ISConfiguration xmlns="http://www.oracle.com/pcbpel/identityservice/isconfig" <configurations <configuration realmName="jazn.com" <provider providerType="JAZN" name="xml" service="Identity" <property name="userPropertiesFile" value="users-properties.xml"/ </provider <provider providerType="CUSTOM name="CustomPlugIn" service="Authentication class=Ópackage.name.CustomAuthenticationServiceÓ / </configuration </configurations </ISConfiguration
In the preceding example, only the authentication provider uses the custom implementation while all other inquiries use the JAZN XML-based provider. The class CustomAuthenticationService
must implement the BPMAuthenticationService
interface.
If the SOA_Oracle_Home
\bpel\system\services\config\
is_config.xml
file specifies CUSTOM
as the providerType
for the identity service, then the BPMIdentityService
interface must be implemented:
<?xml version = '1.0' encoding = 'UTF-8'?>
<ISConfiguration xmlns="http://www.oracle.com/pcbpel/identityservice/isconfig">
<configurations>
<configuration realmName="jazn.com">
<provider providerType="CUSTOM"
name="CustomPlugIn" service="Identity"
class=Ópackage.name.CustomIdentityServiceÓ>
<property name=ÓcustomPropertyÓ value=ÓcustomValueÓ />
</configuration>
</configurations>
</ISConfiguration>
All three service classes implementing the BPMIdentityService
, BPMAuthenticationService
, or BPMAuthorization
interface can extend the oracle.tip.pc.services.identity.BPMServiceBase
class to leverage basic service functionality.
All custom service classes must have the static factory getInstance()
method to create the instance of the service provider:
public static Service getInstance(String realmName) throws ServiceException;
The realmName
is a context of the business process. If realmName
is null
, it assumes the default realm is used. You can get the default realm name by using the configuration service API:
BPMIdentityConfigService cfgService = ServiceFactory.getIdentityConfigServiceInstance(); String defaultRealmName = cfgService.getDefaultRealmName();
The service factory oracle.tip.pc.service.common.ServiceFactory
class defines the following public static methods:
BPMIdentityService getIdentityServiceInstance(String realmName); BPMAutorizationService getAuthorizationServiceInstance(String realmName); BPMAuthenticationService getAuthenticationServiceInstance(String realmName); BPMIdentityService getIdentityServiceInstance(); BPMAutorizationService getAutorizationServiceInstance(); BPMAuthenticationService getAuthenticationServiceInstance();
These methods are used by Java clients to receive the instances of the corresponding services providers. The service factory methods create custom service instances at run time if the CUSTOM
provider type is specified for the service. These methods invoke the custom service getInstance(String realmName)
API.
If the service provider class extends the oracle.tip.pc.services.BPMServiceBase
class, the service factory method must get an instance of the ProviderCfg
class, which defines properties for a given configuration. The service can then be created:
CustomIdentityService service = new CustomIdentityService(providerCfg);
The BPMIdentityConfigService
instance provides access to the Configuration
object by the given realmName
:
Configuration conf = cfgService.getConfigurationInstance(realmName);
The specific provider configuration can then be fetched:
ProviderCfg providerCfg = conf.getProviderCfg(serviceName);
where serviceName
is one of the following values:
ProviderCfg.IDENTITY_SERVICE
— for identity service provider
ProviderCfg.AUTHENTICATION_SERVICE
— for authentication service provider
ProviderCfg.AUTHORIZATION_SERVICE
— for authorization service provider
The easiest way to write authentication and authorization services for a custom plug-in is to implement the BPMProvider
interface for the custom repository. The BPMProvider
interface defines the minimum set of essential operations that must be defined over a custom repository for the identity service to function correctly. All instances of the implementing object can delegate calls to the provider that is responsible for dealing with the repository-specific calls.
For example, the BPMServiceBase
class is an abstract class that your service providers may extend. If they do, the custom service classes must implement the init()
method:
public void init() throws BPMIdentityException { m_provider = CustomerProvider.getInstance(m_providerCfg); m_status = new ServiceStatus(true, "Service is available", -1, }
where m_provider
is a protected member of the BPMServiceBase
to reference the BPMProvider
object. CustomerProvider
is a class that implements the BPMProvider
interface. Optionally, you can load the provider class dynamically. Get the provider class name for the CUSTOM
providerType
from the is_config.xml
file. The name
attribute of the provider element is reserved for that purpose. The m_status
member is a protected member of the BPMServiceBase
class. It stores the ServiceStatus
object.
For the workflow services to instantiate and invoke the plug-in, it must be deployed to a location in the library path of Oracle BPEL Process Manager.
The plug-in code must be compiled, the classes assembled into a JAR file (for example, isplugin.jar
), and the JAR file deployed to the SOA_Oracle_Home
\services\lib
directory.
The library path must also point to the deployed JAR file. For example, isplugin.jar
must be added to the library path by adding the following lines to the application.xml
file in the SOA_Oracle_Home
\j2ee\home\config
directory:
<library path="SOA_Oracle_Home\bpel\system\services\lib\isplugin.jar"/>
The same deployment scheme can be used for any custom plug-in, with minor changes such as the name of the provider JAR file.
Identity service configuration in defined in the is_config.xml
file. The file must be located in a directory that is in the classpath of Oracle BPEL Process Manager. By default, this file is stored in SOA_Oracle_Home
\bpel\system\services\config
.
The following configuration file sample describes the database plug-in implemented as a custom provider for the identity service:
<?xml version = '1.0' encoding = 'UTF-8'?> <ISConfiguration mlns="http://www.oracle.com/pcbpel/identityservice/isconfig"> <configurations> <configuration realmName="realm"> <provider providerType="CUSTOM" service="Identity" name="package.name.CustomerProvider" class=Ópackage.name.CustomIdentityServiceÓ> <property name="dataSource" value="jdbc/BPELSamplesDataSource"/> </provider> </configuration> </configurations> </ISConfiguration>
The name
attribute of the provider
element can load the BPMProvider
class. The class
attribute defines the implementation class for BPMIdentityService
. The custom
property with the name dataSource
gets the data source name for the JDBC connection.
See Also:
"Configuring the Identity Service" for identity service configuration proceduresThe identity service does not define any of the administrative APIs, including the creation of users and roles or the granting of roles to users. You must use tools specific to the user repository to accomplish this task.
See Also:
Appendix A, "Demo User Community" for details about users, roles, and groupsThis chapter describes how to create a custom identity service plug-in to integrate into specific third-party repositories. Details are provided for assembling all classes into a custom plug-in JAR file, deploying the JAR file, including the JAR file in the Oracle BPEL Process Manager classpath, configuring the is_config.xml
file, and creating system users and groups.