8 Security

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:

For more information about WebLogic security, see Oracle Fusion Middleware Understanding Security for Oracle WebLogic Server and Oracle Fusion Middleware Securing Resources Using Roles and Policies for Oracle WebLogic Server.

Container-Managed and Application-Managed Sign-on

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 (http://java.sun.com/j2ee/connector/), 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.

Application-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.

Container-Managed Sign-on

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 username/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.

Password Credential Mapping

The J2CA 1.5 Specification (http://java.sun.com/j2ee/connector/) 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.

Authentication Mechanisms

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 username/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 Oracle Fusion Middleware Securing Oracle WebLogic Server.

Credential Mappings

Credential mappings are specific to outbound resource adapters. You configure credential mappings using the WebLogic Server Administration Console. Before you can configure credential mappings, you must successfully deploy the resource adapter.

Note:

The first time you deploy a resource adapter, it has no configured credential mappings and the initial connections will fail until they 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), the initial connection may fail. To prevent initial connection failure, Oracle recommends you set the initial-capacity element the connection pool to 0 for its connection pool for the initial installation and deployment of a resource adapter. Once the resource adapter is deployed for the first time, 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.

Review the following situations:

Non-initial Connection: Requires ManagedConnection from Adapter Upon Application's Request

WebLogic Server requires a ManagedConnection from the adapter upon an application's request. For example, an application wants to get a connection from a pool but there is no available ManagedConnection in the pool so WebLogic Server needs to make a request to the adapter to create a new ManagedConnection.

Note:

Applies only to Container-Managed sign-on.

The server searches for mappings in the following order:

  1. Specific mappings (or anonymous mapping if unauthenticated) at the connection factory level.

  2. Specific mappings (or anonymous mapping if unauthenticated) at the global level.

  3. Default mappings at the connection factory level.

  4. Default mappings at the global level.

For example, in Example 8-1, consider two connection pools with the following credential mappings:

Example 8-1 Credential Mapping Examples

poolA
   system user name: admin
   system password: adminpw
   default user name: guest1
   default password: guest1pw1

poolB
   wlsjoe user name: harry
   wlsjoe password: harrypw

global
   system user name: sysman
   system password: sysmanpw
   wlsjoe user name: scott
   wlsjoe password: tiger
   default user name: viewer
   default password: viewerpw
   anonymous user name: foo
   anonymous password: bar

Referring to the example provided in Example 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).

If an application authenticated as user1 makes a request against poolA, it finds no mapping for user1 for poolA. The following sequence occurs:

  1. The application searches at the global level, which also has no mapping for user1.

  2. The application searches the poolA mappings for a default mapping and finds a default mapping.

If an application doesn't authenticate to WLS and makes a request against poolA, it finds no mapping for anonymous user for poolA. It then searches at the global level and finds a mapping for the anonymous user (foo/bar).

Initial Connection: Requires a ManagedConnection from Adapter Without Application's Request

WebLogic Server requires a ManagedConnection from adapter without application's request. This can either be when WebLogic Server creates initial connections at deployment time (meaning the initial-capacity element in the weblogic-ra.xml is set to greater than 0), or when WebLogic needs to get a ManagedConnection specifically for XA recovery.

Note:

Applies to both Container-Managed sign-on and Application-Managed sign-on.

The server searches for mappings in the following order:

  1. Initial mappings at the connection factory level.

  2. Initial mappings at the global level.

  3. Default mappings at the connection factory level.

  4. Default mappings at the global level.

If neither initial nor default mapping is defined, WebLogic Server uses null as Subject when calls to adapter to create a ManagedConnection.

For example, consider two connection pools with the following credential mappings:

Example 8-2 Credential Mapping Examples

poolA
   initial user name: admin
   initial password: adminpw

poolB
   wlsjoe user name: harry
   wlsjoe password: harrypw

global
   system user name: sysman
   system password: sysmanpw

Referring to the example provided in Example 8-2, WebLogic Server needs to perform XA Recovery for poolA and so makes a connection request against poolA. Because the initial credential mapping is defined for system for poolA, the resource adapter uses this mapping (admin/adminpw).

If WebLogic Server makes the same request against poolB, there is no corresponding initial credential mapping for poolB. WebLogic Server then searches for the initial credential mapping at the global level where it finds a mapping (sysman/sysmanpw).

Special Users

Three special users are provided for use by resource adapters:

  • Initial User (User for creating initial connections)—If you define a mapping for this user, the specified credentials are used for the initial connections created when:

    • Starting the connection pool for this resource adapter

    • Doing XA transaction recovery for the connection pool

    The InitialCapacity parameter on the pool specifies the number of initial connections. If you do not define a mapping for this user the default mapping (if provided) is used. Otherwise, no credentials are provided for the initial connections.

  • Anonymous User (Unauthenticated WLS User)—If you define a mapping for this user, the specified credentials are used when no user is authenticated for the connection request on the resource adapter.

  • Default User—If you define a mapping for this user, the specified credentials are used when:

    • No other mapping applies for the current user

    • No anonymous mapping is provided in the case where there is no authenticated user.

Creating Credential Mappings Using the Console

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 Oracle Fusion Middleware Oracle WebLogic Server Administration Console Help.

Security Policy Processing

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 (http://java.sun.com/j2ee/connector/) 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 Using Roles and Policies.

Configuring Security Identities for Resource Adapters

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:

  • default principal - a security principal that can perform all resource adapter tasks.

  • run-as principal - a security principal used by calls from the connector container into the resource adapter code during connection requests.

  • run-work-as principal - a security principal used for Work instances launched by the resource adapter.

  • manage-as principal - a security principal used for resource adapter management tasks, such as startup, shutdown, testing, and transaction management.

Example 8-3 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.

Example 8-3 Configuring All Security Identities for Resource Adapters

<weblogic-connector xmlns="http://xmlns.oracle.com/weblogic/weblogic-connector">
   <jndi-name>900blackbox-notx</jndi-name> 
   <security>
      <default-principal-name>
         <principal-name>system</principal-name>
      </default-principal-name>
      <run-as-principal-name>
         <principal-name>raruser</principal-name>
      </run-as-principal-name>
      <run-work-as-principal-name>
         <principal-name>workuser</principal-name>
      </run-work-as-principal-name> 
      <manage-as-principal-name>
         <principal-name>raruser</principal-name>
      </manage-as-principal-name>
   </security> 
</weblogic-connector>

Example 8-4 illustrates how you could use the <default-principal-name> element to configure a single default principal security identity for performing all resource adapter tasks.

Example 8-4 Configuring a Single Default Principal Identity for a Resource Adapter

<weblogic-connector xmlns="http://xmlns.oracle.com/weblogic/weblogic-connector"> 
   <jndi-name>900blackbox-notx</jndi-name> 
   <security>
      <default-principal-name>
         <principal-name>system</principal-name>
      </default-principal-name>
   </security> 
</weblogic-connector>

For more information on setting security identity properties, see security.

default-principal-name: Default Identity

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.

The value of default-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).

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 shown in Example 8-6:

Example 8-5 Using a Defined WebLogic Server Name

<security>
   <default-principal-name>
      <principal-name>system</principal-name>
   </default-principal-name>
</security>

You can set the default-principal-name element to anonymous as follows:

Example 8-6 Setting Up an Anonymous Identity

<security>
   <default-principal-name>
      <use-anonymous-identity>true</use-anonymous-identity>
   </default-principal-name>
</security>

manage-as-principal-name: Identity for Running Management Tasks

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.

Example 8-7 illustrates how you can configure a resource adapter to run management calls using the WebLogic Server-defined user name system.

Example 8-7 Using a Defined WebLogic Server Name

<security>
   <manage-as-principal-name>
      <principal-name>system</principal-name>
   </manage-as-principal-name>
</security>

Example 8-8 illustrates how you can configure a resource adapter to run management calls using an anonymous identity.

Example 8-8 Setting Up an Anonymous Identity

<security>
   <manage-as-principal-name>
      <use-anonymous-identity>true</use-anonymous-identity>
   </manage-as-principal-name>
</security>

run-as-principal-name: Identity Used for Connection Calls from the Connector Container into the Resource Adapter

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()).

The value of the run-as-principal-name element can be set in one of three ways:

  • To a defined WebLogic Server name

  • To use an anonymous identity

  • To use the security identity of the calling code.

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.

run-work-as-principal-name: Identity Used for Performing Resource Adapter Management Tasks

For inbound resource adapters, Oracle 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.

The value of the run-work-as-principal-name element can be set in one of three ways:

  • To a defined WebLogic Server name

  • To use an anonymous identity

  • To use the security identity of the calling code

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.

To run work using the requesting caller's identity, you specify the run-work-as-principal-name element as shown in Example 8-9:

Example 8-9 Using the Requesting Caller's Identity

<security>
   <run-work-as-principal-name>
      <use-caller-identity>true</use-caller-identity>
   </run-work-as-principal-name>
</security>

Configuring Connection Factory-Specific Authentication and Re-authentication Mechanisms

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.

  • The authentication-mechanism element specifies an authentication mechanism to be used by all outbound connection factories.

  • The reauthentication-support element specifies whether outbound connection factories support re-authentication of existing Managed-Connection instances. This is intended to be the default value for all connection factories of the resource adapter.

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 in Table A-13, "default-connection-properties subelements".