bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Programming WebLogic J2EE Connectors

Security

The following sections discuss WebLogic J2EE Connector Architecture security:

- Container-Managed and Application-Managed Sign-on

- Password Credential Mapping Mechanism

- Deprecated Security Principal Map Mechanism

- Deprecated Password Converter Tool

- Security Policy Processing

Container-Managed and Application-Managed Sign-on

As specified in the J2EE Connector Specification, Version 1.0 Final Release, the WebLogic J2EE Connector Architecture implementation supports both container-managed and application-managed sign-on.

At runtime, the Weblogic J2EE Connector Architecture implementation determines— based upon the specified information in the invoking client component's deployment descriptor—the chosen sign-on mechanism. If the Weblogic Server J2EE Connector Architecture implementation is unable to determine what sign-on mechanism is being requested by the client component—typically due to an improper JNDI lookup of the resource adapter Connection Factory—the Connector Architecture attempts container-managed sign-on.

Note: Note that even in this case, if the client component has specified explicit security information, this information is also presented on the call to obtain the connection.

For related information, see Obtaining the ConnectionFactory (Client-JNDI Interaction) in Client Considerations.

Application-Managed Sign-on

With application-managed sign-on, the client component provides the necessary security information (typically a username and password) when making the call to obtain a connection to an Enterprise Information System (EIS). In this scenario, the application server provides no additional security processing other than to pass this information along on the request for the connection. The provided resource adapter uses the client component provided security information to perform the EIS sign-on in a resource adapter implementation specific manner.

Container-Managed Sign-on

With container-managed sign-on, the client component does not present any security information, and the container must determine the necessary sign-on information and provide this information to the resource adapter when making a call to request a connection. In all container-managed sign-on scenarios, the container must determine an appropriate Resource Principal and provide this Resource Principal information to the resource adapter in the form of a Java Authentication and Authorization Service (JAAS) Subject.

Password Credential Mapping Mechanism

The J2EE Connector Specification, Version 1.0 Final Release defines two types of credentials that resource adapters can support: password credentials and generic credentials. In the previous release of WebLogic Server, you specified your password credentials in the security-principal-map element in the weblogic-ra.xml deployment descriptor file. The security-principal-map element was provided to map between the initiating principal and resource principal. BEA also provided a Password Converter Tool for encrypting the password stored in the security-principal-map element.

The storage of user names and passwords for principal maps in weblogic-ra.xml is not the most elegant nor secure storage mechanism. As a result, the security-principal-map element and Password Converter Tool have been deprecated in this release of WebLogic Server. The principal map has been moved from the security-principal-map to an internal WebLogic Server storage mechanism (a directory server).

The J2EE Connector specification, Version 1.0 Final Release requires storage of credentials in a javax.security.auth.Subject; the credentials are passed to either the createManagedConnection() or matchManagedConnection() methods of the ManagedConnectionFactory object.

To comply with this, the WebLogic Server J2EE Connector Architecture builds the Subject and stores the credentials by performing the following steps:

1. Instantiate a weblogic.security.Service.EISResource object as follows:

   EISResource(java.lang.String applicationName, java.lang.String moduleName, java.lang.String eisName)

2. Obtain the Initiating Principal for the connection request.

3. Obtain the Credentials for that Initiating Principal as follows:

   weblogic.security.Service.PrincipalAuthenticator(String initiatingPrincipal, weblogic.security.Service.Resource eisResource)

4. Instantiate a javax.security.auth.Subject.

5. Add the Credentials to the private set in the Subject as follows:

   Subject.getPrivateCredentials().add(Credential)

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. The following types of authentication mechanisms are supported by WebLogic Server:

- Password authentication—a user ID and password are requested from the user and sent to WebLogic Server in clear text. WebLogic Server checks the information and if it is trustworthy, grants access to the protected resource.

  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 the clear. Therefore, WebLogic Server can authenticate the user without compromising the confidentiality of the user's ID and password.

- Certificate authentication—when an SSL or HTTPS client request is initiated, WebLogic Server responds by presenting its digital certificate to the client. The client then verifies the digital certificate and an SSL connection is established. The CertAuthenticator class then extracts data from the client's digital certificate to determine which WebLogic Server User owns the certificate and then retrieves the authenticated User from the WebLogic Server security realm.

  You can also use mutual authentication. In this case, WebLogic Server not only authenticates itself, it also requires authentication from the requesting client. Clients are required to submit digital certificates issued by a trusted certificate authority. Mutual authentication is useful when you must restrict access to trusted clients only. For example, you might restrict access by accepting only clients with digital certificates provided by you.

For more information, see the following sections in Managing WebLogic Security:

- "Configuring the SSL Protocol"

- "Configuring Mutual Authentication"

Upgrading Security Principle Mappings

If you deploy a resource adapter that has a weblogic-ra.xml deployment descriptor file containing a defined security-principal-map element, the data of this file is imported into the WebLogic Server Embedded LDAP Server as if it had been configured through the Admin Console. (The Embedded LDAP Server is where credentials and mappings are stored persistently.)

However, the original resource adapter remains unchanged. Therefore, if you redeploy the original resource adapter, the data must once again be imported from the weblogic-ra.xml file.

It is therefore important to bear in mind that if you deploy a resource adapter containing the deprecated security-principal-map element and then use the Admin Console credential mapping interface to add or modify entries, these changes are erased if the resource adapter is deployed again with the security-principal-map element still in place.

To work around this, you should deploy the resource adapter, then modify its weblogic-ra.xml file to remove the security-principal-map element. This way, all security-principal-map information that was stored in the weblogic-ra.xml file before is now in the Embedded LDAP Server. When the resource adapter is redeployed without the security-principal-map element, the information will not be erased.

For instructions on editing elements in the weblogic-ra.xml file, see weblogic-ra.xml Deployment Descriptor Elements.

Defining Users and Groups

The following sections discuss the definition of users and groups. For more information on how to create users and groups, see Managing WebLogic Security.

Users

Users are entities that can be authenticated in a WebLogic Server security realm. A User can be a person or a software entity, such as a Java client. Each User is given a unique identity within a WebLogic Server security realm. As a system administrator you must guarantee that no two Users in the same security realm are identical.

Defining Users in a security realm involves specifying a unique name and password for each User that will access resources in the WebLogic Server security realm in the Users window of the Administration Console.

Three special users are provided for use by resource adapters. They are as follows:

- wls_ra_initial—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. 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 wls_ra_default (if provided) is used. Otherwise, no credentials are provided for the initial connections.

- wls_ra_anonymous—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.

- wls_ra_default—If you define a mapping for this user, the specified credentials are used when no other mapping applies for the current user or when no anonymous mapping is provided in the case where there is no authenticated user.

Groups

A Group represents a set of Users who usually have something in common, such as working in the same department in a company. Groups are a means of managing a number of Users in an efficient manner. When a Group is granted a permission in an ACL, all members of the Group effectively receive that permission. BEA recommends assigning permissions to Groups rather than to individual Users.

Deprecated Security Principal Map Mechanism

This release provides a standard method for resource adapter deployers to plug in their specified authorization/authentication mechanism through secure password credential storage. This WebLogic Server storage mechanism has replaced the Security Principal Mapping mechanism provided with the weblogic-ra.xml deployment descriptor within the resource adapter archive.

As a result, the weblogic-ra.xml <security-principal-map> element has been deprecated. However, instructions for using the Security Principal Mapping mechanism are still in place.

The "EIS Sign-on" section of the J2EE Connector Specification, Version 1.0 Final Release (http://java.sun.com/j2ee/download.html#connectorspec) identifies a number of possible options for defining a Resource Principal on whose behalf the sign-on is being performed. The previous Weblogic Server implementation implemented the Security Principal Map option identified in the specification.

Under this option, a resource principal is determined by mapping from the identity of the initiating/caller principal for the invoking component. The resultant resource principal does not inherit the identity or security attributes of the principal that it is mapped from, but instead gets its identity and security attributes (password) based upon the defined mapping.

Therefore, in order to enable and use container-managed sign-on, Weblogic Server must provide a mechanism to specify the initiating-principal to resource- principal association. WebLogic Server does this through a Security Principal Map that can be defined for each deployed resource adapter.

If container-managed sign-on is requested by the client component and no Security Principal Map is configured for the deployed resource adapter, an attempt is made to obtain the connection, but the provided JAAS Subject will be NULL. Support for this scenario will be based upon the resource adapter implementation.

A scenario in which omitting configuration of a Security Principal Map might be considered valid is the case in which a resource adapter internally obtains all of its EIS connections with a hard-coded and pre-configured set of security information, and therefore does not depend on the security information passed to it on requests for new connections. (In a sense, this is a third scenario, outside of application-managed sign-on and container-managed sign-on.)

While the defined connection management system contracts define how security information is exchanged between WebLogic Server and the provided resource adapter, the determination of whether to use container-managed sign-on or application-managed sign-on is based on deployment information defined for the client application that is requesting a connection. For more information on how a connection management system contract is specified, see Client Considerations.

For more information on how client components specify the sign-on mechanism, see the "Application Programming Model" section of the "Connection Management" chapter in the J2EE Connector Specification, Version 1.0 Final Release (http://java.sun.com/j2ee/download.html#connectorspec).

For more information on the J2EE Connector Architecture application security model, see the "Application Security Model" of the same document.

Using Container-Managed Sign-On

To use container-managed sign-on, WebLogic Server must identify a resource principal and then request the connection on behalf of the resource principal. In order to make this identification, WebLogic Server looks for a Security Principal Mapping specified with the security-principal-map element in the weblogic-ra.xml deployment descriptor file.

A security-principal-map element defines the relationship of initiating-principal to a resource-principal.

Each security-principal-map element provides a mechanism to define appropriate resource principal values for resource adapter and EIS sign-on processing. The security-principal-map elements allow you to specify a defined set of initiating principals and the corresponding resource principal's username and password to be used when allocating managed connections and connection handles.

Default Resource Principal

A default resource principal can be defined for the connection factory in the security-principal-map element. If you specify an initiating-principal value of '*' and a corresponding resource-principal value, the defined resource-principal is utilized whenever the current identity is not matched elsewhere in the map.

This is an optional element, however. You must specify it in some form if container-managed sign-on is supported by the resource adapter and used by any client.

In addition, the deployment-time population of the Connection Pool with Managed Connections is attempted using the defined 'default' resource principal if one is specified.

For instructions on configuring the J2EE Connector Architecture security-principal-map and associating it with the deployed RAR (resource adapter), refer to Configuring the Deprecated Security Principal Map Mechanism in Configuration.

Deprecated Password Converter Tool

The Password Converter Tool is a deprecated tool due to the fact that the new WebLogic Server storage mechanism has replaced the Security Principal Mapping mechanism provided with the weblogic-ra.xml deployment descriptor within the resource adapter archive.

However, instructions for using the Password Converter Tool are still in place. For more information, refer to Configuring the Deprecated Security Principal Map Mechanism, in Configuration.

Security Policy Processing

The J2EE Connector Specification, Version 1.0 Final Release defines default security policies for any resource adapters running in an application server. It also defines a way for a resource adapter to provide its own specific security policies overriding the default.

In compliance with this specification, WebLogic Server dynamically modifies the runtime environment for resource adapters. If the resource adapter has not defined specific security policies, WebLogic Server overrides the runtime environment for the resource adapter with the default security policies specified in the J2EE Connector Architecture Specification. If the resource adapter has defined specific security policies, WebLogic Server first overrides the runtime environment for the resource adapter first with a combination of the default security policies for resource adapters and the specific policies defined for the resource adapter. Resource adapters define specific security policies 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 the "Runtime Environment" chapter in the J2EE Connector Specification, Version 1.0 Final Release (http://java.sun.com/j2ee/download.html#connectorspec).