Programming WebLogic Resource Adapters
Since a resource adapter needs to be able to establish connections with external systems, it needs to be configured with authentication and other security information necessary to make the connections. The following sections discuss WebLogic Server resource adapter security for outbound communication:
When a resource adapter makes an outbound connection to an Enterprise Information System (EIS), it needs to sign on with valid security credentials. In accordance with the J2CA 1.5 Specification, WebLogic Server supports both container-managed and application-managed sign-on for outbound connections. At runtime, WebLogic Server determines the chosen sign-on mechanism, based on the information specified in either the invoking client component's deployment descriptor or the res-auth element of the resource adapter deployment descriptor. A sign-on mechanism specified in a resource adapter's deployment descriptor takes precedence over one specified in the calling component's deployment descriptor. Even when using container-managed sign-on, any security information explicitly specified by the client component is presented on the call to obtain the connection.
If the Weblogic Server J2EE 1.5 Connector Architecture implementation cannot determine which sign-on mechanism is being requested by the client component, the connector container attempts container-managed sign-on.
With application-managed sign-on, the client component supplies the necessary security credentials (typically a user name and password) when making the call to obtain a connection to an EIS. In this scenario, the application server provides no additional security processing other than to pass along this information in the request for the connection.
WebLogic Server and an EIS each maintain independent security realms. A goal of container-managed sign-on is to permit a user to sign on to WebLogic Server and be able to use applications that access an EIS through a resource adapter without having to sign on separately to the EIS. Container-managed sign-on in WebLogic Server uses credential mappings, which map credentials (either user name/password pairs or security tokens) of WebLogic security principals (which may be either authenticated individual users or client applications) to the corresponding credentials required to access the EIS. For any deployed resource adapter, you can configure credential mappings for applicable security principals. For related information, see Credential Mappings.
The J2CA 1.5 Specification requires storage of credentials in a javax.security.auth.Subject. The credentials are passed to either the createManagedConnection() or the matchManagedConnection() methods of the ManagedConnectionFactory object. Credential mapping information is stored in the WebLogic Server embedded LDAP storage. Credential mappings are specific to outbound resource adapters.
WebLogic Server users must be authenticated whenever they request access to a protected WebLogic Server resource. For this reason, each user is required to provide a credential (a user name/password pair or a digital certificate) to WebLogic Server.
Password authentication is the only authentication mechanism supported by WebLogic Server out of the box. Password authentication consists of a user ID and password. Based on the configured mappings, when a user requests connection to a resource adapter, the appropriate credentials for that user are supplied to the resource adapter.
The SSL (or HTTPS) protocol can be used to provide an additional level of security to password authentication. Because the SSL protocol encrypts the data transferred between the client and WebLogic Server, the user ID and password of the user do not flow in clear text. Using SSL, WebLogic Server can authenticate the user without compromising the confidentiality of the user's ID and password. For more information, see Configuring SSL in Securing WebLogic Server.
Credential mappings are specific to outbound resource adapters. You configure credential mappings using the WebLogic Server Administration Console. Before you can configure credential mappings, however, you must successfully deploy the resource adapter. Note that the first time you deploy a resource adapter, it has no credential mappings configured and initial connections will fail until these are configured.
If the resource adapter requires credentials and is configured to create connections at deployment time (meaning the initial-capacity element in the weblogic-ra.xml is set to greater than 0), this may cause the initial connection to fail. Therefore, BEA recommends that—for the initial installation and deployment of this resource adapter—you set the initial-capacity element to 0 for its connection pool. After you configure the appropriate credentials and after the initial deployment of the resource adapter, you can change the value of the initial-capacity element. For more information, see initial-capacity: Setting the Initial Number of ManagedConnections.
You can configure credential mappings for individual outbound connection pools or globally for all the connection pools in the resource adapter. When the resource adapter receives a request for a connection, WebLogic Server searches for credential mappings configured for a specific connection pool and then checks the mappings configured globally for the resource adapter. The server searches for mappings in the following order:
Referring to the example provided in Listing 8-1, consider an application authenticated as system that makes a connection request against poolA. Because a specific credential mapping is defined for system for poolA, the resource adapter uses this mapping (admin/adminpw).
If the application makes the same request against poolB as system, there is no corresponding specific credential mapping for system; therefore, the server searches for the credential mapping at the global level where it finds a mapping (sysman/sysmanpw).
If another application authenticates as wlsjoe and makes a request against poolA, it finds no mapping for wlsjoe defined for poolA. It then searches at the global level and finds a mapping for wlsjoe (scott/tiger). Against poolB, the application would find the mapping defined for poolB (harry/harrypw).
You can create credential maps with the WebLogic Server Administration Console. If you are using the WebLogic Credential Mapping provider, the credential maps are stored in the embedded LDAP server. For information about how to create a credential map, see Create credential mappings in the Administration Console online help.
A security policy is an association between a WebLogic resource and one or more users, groups, or security roles and is designed to protect the WebLogic resource against unauthorized access. The J2CA 1.5 Specification defines default security policies for resource adapters running in an application server. It also defines how resource adapters can provide their own specific security policies overriding the default. The weblogic.policy file that ships with WebLogic Server establishes the default security policies as specified in the J2CA 1.5 Specification.
If the resource adapter does not have a specific security policy defined, WebLogic Server establishes the runtime environment for the resource adapter with the default security policies specified in the weblogic.policy file, which conforms to the defaults specified by the J2CA 1.5 Specification. If the resource adapter has defined specific security policies, WebLogic Server establishes the runtime environment for the resource adapter with a combination of the default security policies for resource adapters and the specific policies defined for the resource adapter. You define specific security policies for resource adapters using the security-permission-spec element in the ra.xml deployment descriptor file.
For more information on security policy processing requirements, see the "Security Permissions" section of Chapter 18, "Runtime Environment" in the J2CA 1.5 Specification. For more information about security policies and the WebLogic security framework, see "Security Policies" in Securing WebLogic Resources.
This section describes how to configure various security identities for WebLogic Server resource adapters in the
weblogic-ra.xml deployment descriptor. Security identities determine which security principals can perform particular resource adapter functions. In a WebLogic resource adapter, you can either have a single security identity that can perform all functions, or use separate identities for separate classes of functions. You can define the following four types of security identities in the
weblogic-ra.xml deployment descriptor:
Listing 8-2 is an excerpt from a
weblogic-ra.xml deployment descriptor that illustrates how you would configure all four of these available security identities for performing different resource adapter tasks.
Listing 8-3 illustrates how you could use the <default-principal-name> element to configure a single default principal security identity for performing all resource adapter tasks.
For more information on setting security identity properties, see security.
You can define a single security identity that can be used for all resource adapter purposes using the default-principal-name element. If values are not specified for run-as-principal-name, manage-as-principal-name, and run-work-as-principal-name, they default to the value set for default-principal-name.
For example, you can create a single security identity that makes all calls from WebLogic Server into the resource adapter and manages all resource adapter management tasks with a default
system identity as follows:
You can define a management identity that is used for running various resource adapter management tasks such as startup, shutdown, testing, shrinking, and transaction management using the manage-as-principal-name element.
As with default-principal-name, the value of manage-as-principal-name can be set to a defined WebLogic Server user name such as system or to use an anonymous identity (which is the equivalent of having no security identity). If you do not set up a value for the manage-as-principal-name element, it defaults to the value set up for default-principal-name. If no value is set up for default-principal-name, it defaults to the anonymous identity.
Listing 8-6 illustrates how you can configure a resource adapter to run management calls using the WebLogic Server-defined user name system.
Listing 8-7 illustrates how you can configure a resource adapter to run management calls using an anonymous identity.
You define the principal name that should be used by all calls from the connector container into the resource adapter code during connection requests in the run-as-principal-name element. This principal name is used, for example, when resource adapter objects such as the
ManagedConnectionFactory are instantiated—in other words, when the WebLogic Server connector container makes calls to the resource adapter, the identity defined in the run-as-principal-name element is used. This may include calls as part of either inbound or outbound requests or setup, or as part of initialization not specific to either inbound or outbound resource adapters (for example, ResourceAdapter.start()).
If the value of the run-as-principal-name element is not defined, it defaults to the value of the default-principal-name element. If the default-principal-name element is not defined, it defaults to the identity of the requesting caller.
For inbound resource adapters, BEA recommends that you use Work instances to execute inbound requests. To establish the security identity for Work instances launched by a resource adapter, you specify this value using the run-work-as-principal-name element. However, Work instances can also be created as part of outbound resource adapters to execute outbound requests. If an adapter does not use Work instances to handle inbound requests, then inbound requests are either run with no security context established (anonymous) or the resource adapter can make WebLogic Server-specific calls to authenticate as a WebLogic Server user. In this case, the WebLogic Server user security context is used.
If the value of the run-work-as-principal-name element is not defined, it defaults to the value of the default-principal-name element. If the default-principal-name element is not defined, it defaults to the identity of the requesting caller.
You specify authentication and re-authentication mechanisms for a resource adapter in the J2EE standard resource adapter deployment descriptor, ra.xml. These settings apply to all outbound connection factories.
You can override the authentication-mechanism and reauthentication-support values in the ra.xml deployment descriptor by specifying them in the weblogic-ra.xml deployment descriptor. Doing so allows you to apply these settings to a specific connection factory rather than to all connection factories. See authentication-mechanism and reauthentication-support.