| Oracle® BPEL Process Manager Administrator's Guide 10g (10.1.3.1.0) Part Number B28982-03 |
|
|
View PDF |
| 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.
