This chapter includes the following sections:
For more information about WebLogic security, see Understanding Security for Oracle WebLogic Server and Securing Resources Using Roles and Policies for Oracle WebLogic Server.
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 JSR 322: Java EE Connector Architecture 1.6, WebLogic Server supports both container-managed and application-managed sign-on for outbound connections. At run time, 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 Java EE 1.6 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 outbound 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 outbound credential mappings for applicable security principals. For related information, see Outbound Credential Mappings.
JSR 322: Java EE Connector Architecture 1.6 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. Outbound credential mapping information is stored in the WebLogic Server embedded LDAP server. Outbound credential mappings are specific to outbound resource adapters.
When creating outbound credential mappings of WebLogic Server users to usernames in an EIS to which you want to connect using a resource adapter, note the following:
WebLogic Server supports creating outbound credential mappings for WebLogic Server users who are defined in the default security realm only. If you are using a security realm that you have customized, you need to define it as the default security realm before configuring outbound credential mappings for resource adapters. For more information, see "Customizing the Default Security Configuration" in Administering Security for Oracle WebLogic Server 12c (12.2.1) and "Change the default security realm" in Oracle WebLogic Server Administration Console Online Help.
You must define the authentication-mechanism element for the connection pool in either of the following deployment descriptor files:
ra.xml, which works for all connection pools of the resource adapter
weblogic-ra.xml for each individual connection pool
If there is no valid authentication-mechanism element defined, the outbound credential mapping will not take effect, as explained in Authentication Mechanisms. The following is a sample ra.xml file snippet:
<authentication-mechanism> <authentication-mechanism-type>BasicPassword</authentication-mechanism-type> <credential-interface>javax.resource.spi.security.PasswordCredential</credential-interface> </authentication-mechanism>
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 Administering Security for Oracle WebLogic Server 12c (12.2.1).
Outbound credential mappings are specific to outbound resource adapters. You configure outbound 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 outbound 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 outbound 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 outbound credential mappings configured for a specific connection pool and then checks the mappings configured globally for the resource adapter.
Review the situations described in the following sections:
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 outbound mappings in the following order:
Example 9-1 Outbound Credential Mapping Examples
poolA system user name: admin system password: admin_password default user name: guest1 default password: guest1_password poolB wlsjoe user name: harry wlsjoe password: harry_password global system user name: sysman system password: sysman_password wlsjoe user name: scott wlsjoe password: scott_password default user name: viewer default password: viewer_password anonymous user name: foo anonymous password: foo_password
Referring to the example provided in Example 9-1, consider an application authenticated as system that makes a connection request against poolA. Because a specific outbound credential mapping is defined for system for poolA, the resource adapter uses this mapping (admin/admin_password).
If the application makes the same request against poolB as system, there is no corresponding specific outbound credential mapping for system. Therefore, the server searches for the credential mapping at the global level where it finds a mapping (sysman/sysman_password).
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/scott_password). Against poolB, the application would find the mapping defined for poolB (harry/happy_password).
If an application authenticated as user1 makes a request against poolA, it finds no mapping for user1 for poolA. The following sequence occurs:
The application searches at the global level, which also has no mapping for user1.
The application searches the poolA outbound mappings for a default mapping and finds a default mapping.
If an application does not authenticate to WebLogic Server and makes a request against poolA, it finds no outbound mapping for anonymous user for poolA. It then searches at the global level and finds a mapping for the anonymous user (foo/foo_password).
For example, in Example 9-1, consider two connection pools with the following outbound credential mappings:
WebLogic Server requires a ManagedConnection from an adapter without the application's request. This can either be when WebLogic Server creates initial connections at deployment time (meaning the initial-capacity element in weblogic-ra.xml is set to greater than 0), or when WebLogic Server needs to get a ManagedConnection specifically for XA recovery.
Note:
Applies to both Container-Managed sign-on and Application-Managed sign-on.
WebLogic Server searches for outbound mappings in the following order:
Example 9-2 Credential Mapping Examples
poolA initial user name: admin initial password: admin_password poolB default user name: harry default password: harry_password global initial user name: sysman initial password: sysman_password
Referring to Example 9-2, WebLogic Server needs to perform XA Recovery for poolA and so makes a connection request against poolA. Because the initial outbound credential mapping is defined for system for poolA, the resource adapter uses this mapping (admin/admin_password).
If WebLogic Server makes the same request against poolB, there is no corresponding initial outbound credential mapping for poolB. WebLogic Server then searches for the initial credential mapping at the global level where it finds a mapping (sysman/sysman_password).
If neither an initial nor default mapping is defined, WebLogic Server uses null as the Subject when making calls to the adapter to create a ManagedConnection.
For example, consider two connection pools with the following outbound credential mappings:
Three special users are provided for use by resource adapters:
Initial User (user for creating initial connections) — If you define an outbound credential 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 WebLogic Server 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.
You can create outbound credential maps with the WebLogic Server Administration Console. If you are using the WebLogic Credential Mapping provider, the outbound credential maps are stored in the embedded LDAP server. For information about how to create an outbound credential map, see "Create outbound credential mappings" in the Oracle WebLogic Server Administration Console Online Help.
JSR 322: Java EE Connector Architecture 1.6 defines a standard, generic security context between the EIS/resource adapter and the application server that leverages the work done in JSR 196: Java Authentication Service Provider Interface for Containers. The security context enables a resource adapter to establish security information that is used when submitting a Work instance for execution and delivering messages to message endpoints that are hosted in WebLogic Server.
JSR 322: Java EE Connector Architecture 1.6:
Defines an abstract class SecurityContext as the contract between the resource adapter and the application server
Defines two scenarios on how to handle flown-in identities based on whether or not they belong to the application server's security domain:
Case 1 (see Section 16.4.3, "Case 1: Identity in the Container Security Domain," in JSR 322: Java EE Connector Architecture 1.6.)
Case 2 (Section 16.4.4, "Case 2: Identity Translated Between Security Domains.")
Uses the CallbackHandler defined in the JSR 196: Java Authentication Service Provider Interface for Containers.
Uses three callbacks from JSR 196: CallerPrincipalCallback, GroupPrincipalCallback, and PasswordValidationCallback.
Note:
When the WebLogic Server Connector container calls the setupSecurityContext method of the SecurityContext implementation provided by the resource adapter, the serviceSubject passed to the adapter will always be null.
A resource adapter deployed in the WebLogic Connector container can flow in an identity (that is, a caller principal, a group principal, or both) into a container, and the identity may be defined in either the WebLogic domain (as in the Case 1 scenario) or in the EIS security domain (as in the Case 2 scenario).
If the identity is defined in the EIS security domain, the WebLogic Connector container must be able to map the flown-in principal to a principal defined in the WebLogic domain. To support this scenario, WebLogic Server provides the ability to create an inbound principal mapping between the EIS principal and the corresponding WebLogic domain.
The following mappings can be created:
Default mapping of EIS user names to either a specific WebLogic user, or the WebLogic user anonymous
A specific EIS user name to either a specific WebLogic user, or the WebLogic user anonymous
Default mapping of EIS group names to a WebLogic group name
A specific EIS group name to a WebLogic group name
A principal name defined in an inbound principal mapping configuration must contain at least one non-space character. A string that contains only space characters is not a valid principal name (and is not accepted by the WebLogic Server Administration Console).
Note the following behavior regarding inbound principal mapping:
Although JSR 322: Java EE Connector Architecture 1.6 allows a resource adapter to pass any user and group combination to the container, Connector Architecture 1.6 also allows the container to apply security restrictions. In the case of WebLogic Server, not all user and group combinations are valid: the WebLogic principals specified in the mapping must currently be defined in the WebLogic security realm, and the user must be defined in the WebLogic security realm as being a valid member of the group specified in the mapping. This is a requirement imposed by WebLogic Server.
For example, if a mapping specifies a particular user and group combination, and either the user or the group is not defined in the WebLogic Server security realm, the mapping is not valid. Additionally, if both the user and group are defined in the security realm, but the user is not a member of the particular group specified in the mapping, the mapping is not valid. When WebLogic Server determines that a mapping is not valid, it throws an exception.
Note also that WebLogic Server does not validate users or groups at the time an inbound principal mapping is configured. Because a security realm can be modified after the resource adapter has been deployed, WebLogic principals specified in an inbound principal mapping are validated only at run time.
A flown-in identity cannot run as a principal (that is, a user or group) that is mapped to an administrator role, such as Admin, AdminChannelUser, Deployer, Operator, or Monitor.
If no default inbound mapping is configured for an EIS user principal, and no mapping specific to the EIS user is configured, the user is mapped to an unauthenticated user.
If no default inbound mapping is configured for a EIS group principal, and no mapping specific to the EIS group is configured, the group principal is ignored.
Inbound principal mappings can be configured after the resource adapter has been deployed.
For information about how to create an inbound principal mapping using the WebLogic Server Administration Console, see "Create inbound principal mappings" in Oracle WebLogic Server Administration Console Online Help.
When a resource adapter flows in a identity that is used by the application server through handling CallerPrincipalCallback, GroupPrincipalCallback, and PasswordValidationCallback, JSR 322: Java EE Connector Architecture 1.6 does not specify any restrictions how those callbacks may be combined. However, not all combinations are valid in WebLogic Server Connector Architecture 1.6. The WebLogic Connector container validates these callbacks according to the requirements described in this section. You must design resource adapters so that they meet these requirements when they pass callbacks to the WebLogic Connector container. Otherwise, those callbacks are rejected.
WebLogic Server imposes the following requirements on callbacks passed to the Connector container:
If a resource adapter handles a PasswordValidationCallback, the adapter must also handle a CallerPrincipalCallback. The WebLogic Security Service requires that a caller principal that is established by means of a CallerPrincipalCallback must match the user name that is authenticated by means of the PasswordValidationCallBack.
If a resource adapter handles a GroupPrincipalCallback, the adapter must also handle a CallerPrincipalCallback.
A resource adapter must not handle a PasswordValidationCallback in Case 2 (see Section 16.4.4, "Case 2: Identity Translated Between Security Domains," in JSR 322: Java EE Connector Architecture 1.6). Because the username and password in the PasswordValidationCallback belong to the EIS security domain, the application server (that is, WebLogic Server) cannot authenticate them.
WebLogic Server allows a resource adapter to use a configured principal to execute the Work.run() method. This principal can be configured in the WebLogic Server Administration Console, as described in "Configure security principals" in Oracle WebLogic Server Administration Console Online Help, or in the weblogic-ra.xml file using the run-work-as-principal-name and default-principal-name.
The Work.run() method then executes using the principal, if configured, or anonymous, by default, if this principal is not configured.
This mechanism provides a basic security configuration at the adapter level that applies to all Work instances submitted by the adapter. However, other security principals cannot be used selectively for different Work instances.
The security context feature in Connector Architecture 1.6 provides more flexibility by allowing each Work instance to provide its own SecurityContext, allowing each Work instance to be run under a different security principal.
Because the WebLogic Server Connector container is backward compatible with 1.0 and 1.5 adapters, note the following behavior when a resource adapter submits a Work instance:
If the Work instance is submitted without a SecurityContext, the Work instance uses the principal defined in the run-work-as-principal-name and default-principal-name elements in the weblogic-ra.xml file.
If the Work instance is submitted with a SecurityContext, the Work instance runs under the security principals that are defined according to the description of the SecurityContext class in JSR 322: Java EE Connector Architecture 1.6. The principals defined in the run-work-as-principal-name and default-principal-name elements, if present, are ignored.
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. JSR 322: Java EE Connector Architecture 1.6 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 Java EE Connector Architecture 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 Java EE Connector Architecture 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 21, "Runtime Environment," in JSR 322: Java EE Connector Architecture 1.6. For more information about security policies and the WebLogic security framework, see "Security Policies" in Securing Resources Using Roles and Policies for Oracle WebLogic Server.
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 — Security principal that can perform all resource adapter tasks.
run-as principal — Security principal used by calls from the connector container into the resource adapter code during connection requests.
run-work-as principal — Security principal used for Work instances launched by the resource adapter.
manage-as principal — Security principal used for resource adapter management tasks, such as startup, shutdown, testing, and transaction management.
Example 9-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 9-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 9-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 9-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.
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) as shown inExample 9-5
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 9-6:
Example 9-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 9-6 Setting Up an Anonymous Identity
<security>
<default-principal-name>
<use-anonymous-identity>true</use-anonymous-identity>
</default-principal-name>
</security>
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 9-7 illustrates how you can configure a resource adapter to run management calls using the WebLogic Server-defined user name system.
Example 9-7 Using a Defined WebLogic Server Name
<security>
<manage-as-principal-name>
<principal-name>system</principal-name>
</manage-as-principal-name>
</security>
Example 9-8 illustrates how you can configure a resource adapter to run management calls using an anonymous identity.
Example 9-8 Setting Up an Anonymous Identity
<security>
<manage-as-principal-name>
<use-anonymous-identity>true</use-anonymous-identity>
</manage-as-principal-name>
</security>
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.
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 9-9:
Example 9-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>
You specify authentication and re-authentication mechanisms for a resource adapter in the Java EE 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 Example -00 and Example -00 in Table A-18.