5 Securing Enterprise JavaBeans (EJBs)
-
Using Programmatic Security With EJBs
Note:
You can use metadata annotations, deployment descriptor files, the WebLogic Server Administration Console, and JACC to secure EJBs. For information on using the WebLogic Server Administration Console to secure EJBs, see Options for Securing Web Application and EJB Resources in Securing Resources Using Roles and Policies for Oracle WebLogic Server. For information on JACC, see Using the Java Authorization Contract for Containers.
Java EE Architecture Security Model
Enterprise tier and web tier applications are made up of components that are deployed into various containers. These components are combined to build a multitier enterprise application. Security for components is provided by their containers. A container provides two kinds of security: declarative and programmatic.
Java EE 8 includes a Security API specification that defines portable, plug-in interfaces for authentication and identity stores, and a new injectable-type SecurityContext interface that provides an access point for programmatic security. You can use the built-in implementations of these APIs, or define custom implementations.
See Overview of Java EE Security in The Java EE Tutorial, Release 8 for complete details about the Java EE security architecture.
Declarative Security
The Java EE Tutorial, Release 8 states that declarative security expresses an application component's security requirements by using either deployment descriptors or annotations.
A deployment descriptor is an XML file that is external to the application and that expresses an application's security structure, including security roles, access control, and authentication requirements.
Annotations, also called metadata, are used to specify information about security within a class file. When the application is deployed, this information can be either used by or overridden by the application deployment descriptor. Annotations save you from having to write declarative information inside XML descriptors. Instead, you simply put annotations on the code, and the required information gets generated. In the tutorial, annotations are used for securing applications wherever possible.
Declarative Authorization Via Annotations
As of EJB 3.x, to make the deployer's task easier, the application developer can define security roles. Developers can specify security metadata annotations directly in the EJB bean class to identify the roles that are allowed to invoke all, or a subset, of the EJB's methods.
As stated in the Securing an Enterprise Bean Using Declarative Security section of the The Java EE Tutorial, Release 8, "Declarative security enables the application developer to specify which users are authorized to access which methods of the enterprise beans and to authenticate these users with basic, or user name/password, authentication. Frequently, the person who is developing an enterprise application is not the same person who is responsible for deploying the application. An application developer who uses declarative security to define method permissions and authentication mechanisms is passing along to the deployer a security view of the enterprise beans contained in the EJB JAR. When a security view is passed on to the deployer, he or she uses this information to define method permissions for security roles. If you don't define a security view, the deployer will have to determine what each business method does to determine which users are authorized to call each method."
At deployment time, the deployer then creates these security roles if they do not already exist and maps users to these roles using the WebLogic Server Administration Console to update the security realm. For details, see Manage Security Roles in the Oracle WebLogic Server Administration Console Online Help. The deployer can also map any security roles to users using the weblogic-ejb-jar.xml deployment descriptor.
Note:
Deployment descriptor elements always override their annotation counterparts. In the case of conflicts, the deployment descriptor value overrides the annotation value.
The Java EE Security API requires that group principal names are mapped to roles of the same name by default. In WebLogic Server, if the security-role-assignment element in the weblogic-ejb-jar.xml deployment descriptor does not declare a mapping between a security role and one or more principals in the WebLogic Server security realm, then the role name is used as the default principal.
Programmatic Security
The Java EE Tutorial, Release 8 states that for an enterprise bean, code embedded in a business method can be used to access a caller's identity programmatically and uses this information to make security decisions. Programmatic security is useful when declarative security alone is not sufficient to express the security model of an application. The APIs for programmatic security consist of methods of the Java EE 8 SecurityContext interface, EJBContext interface, and the HttpServletRequest interface. These methods allow components to make business-logic decisions based on the security role of the caller or remote user.
The section Securing an Enterprise Bean Programmatically in the The Java EE Tutorial, Release 8 states that, in general, security management should be enforced by the container in a manner that is transparent to the enterprise bean's business methods. The security APIs described in this section should be used only in the less frequent situations in which the enterprise bean business methods need to access the security context information, such as when you want to restrict access to a particular time of day.
The SecurityContext interface, as specified in the Java EE Security API, defines three methods that allow the bean provider to access security information about the enterprise bean’s caller: getCallerPrincipal, getPrincipalsByType, and isCallerInRole.
The javax.ejb.EJBContext interface provides two methods that allow the bean provider to access security information about the enterprise bean's caller: getCallerPrincipal and getPrincipalsByType.
Note that the newer SecurityContext API duplicates some functions of the EJBContext API because it is intended to provide a consistent API across containers. See Using Programmatic Security With EJBs.
Declarative Versus Programmatic Authorization
Programmatic security is used by security-aware applications when declarative security alone is not sufficient to express the security model of the application. When choosing the security model that works best for you, consider who is responsible for managing security in your organization. Developers are most familiar with the application components they build, but they might not necessarily be familiar with the deployment environment in which those components run. In addition, as security policies change, it is more economical to reconfigure security declaratively instead of rebuilding, retesting, and redeploying applications, which may be necessary when making programmatic security updates.
As described in Declarative Authorization Via Annotations, to make the deployer's task easier, the application developer can specify security metadata annotations directly in the EJB bean class to identify the roles that are allowed to invoke all, or a subset, of the EJB's methods. However, deployment descriptor elements always override their annotation counterparts, which gives the deployer final control.
Using Declarative Security With EJBs
You can implement declarative security using the security providers via the Administration Console, or by using Java Authorization Contract for Containers (JACC). You also use deployment descriptors and metadata annotations for implementing declarative security.
There are three ways to implement declarative security:
-
Security providers via the WebLogic Server Administration Console, as described in Securing Resources Using Roles and Policies for Oracle WebLogic Server.
-
Java Authorization Contract for Containers (JACC), as described in Using the Java Authorization Contract for Containers.
-
Deployment descriptors and metadata annotations, which are discussed in this section.
Which of these three methods is used is defined by the JACC flags and the security model. (Security models are described in Options for Securing EJB and Web Application Resources in Securing Resources Using Roles and Policies for Oracle WebLogic Server)
Implementing Declarative Security Via Metadata Annotations
As of EJB 3.0, (see What Was New and Changed in EJB 3.0 in Developing Enterprise JavaBeans for Oracle WebLogic Server), you are no longer required to create the deployment descriptor files (such as ejb-jar.xml). You can now use metadata annotations in the bean file itself to configure metadata.
You can still use XML deployment descriptors in addition to, or instead of, the metadata annotations if you so choose.
Note:
Deployment descriptor elements always override their annotation counterparts. In the case of conflicts, the deployment descriptor value overrides the annotation value.
To use metadata annotations:
-
Use the metadata annotations feature and create an annotated EJB bean file.
-
At deployment time, the deployer must then create these security roles if they do not already exist and map users to these roles using the WebLogic Server Administration Console to update the security realm. See Manage Security Roles in the Oracle WebLogic Server Administration Console Online Help.
The annotations are part of the javax.security.annotation package. The following security-related annotations are available:
-
javax.annotation.security.DeclareRoles — Explicitly lists the security roles that will be used to secure the EJB.
-
javax.annotation.security.RolesAllowed — Specifies the security roles that are allowed to invoke all the methods of the EJB (when specified at the class-level) or a particular method (when specified at the method-level.)
-
javax.annotation.security.DenyAll — Specifies that the annotated method can not be invoked by any role.
-
javax.annotation.security.PermitAll — Specifies that the annotated method can be invoked by all roles.
-
javax.annotation.security.RunAs — Specifies the role which runs the EJB. By default, the EJB runs as the user who actually invokes it.
Security-Related Annotation Code Examples
The section Securing Access to the EJB in Developing Enterprise JavaBeans for Oracle WebLogic Server provides an example of a simple stateless session EJB that uses all of the security-related annotations.
The section Specifying Authorized Users by Declaring Security Roles in the Java EE Tutorial, Release 8 also discusses how to use annotations to specify the method permissions for the methods of a bean class, with accompanying code examples.
Implementing Declarative Security Via Deployment Descriptors
To implement declarative security in EJBs you can use deployment descriptors (ejb-jar.xml and weblogic-ejb-jar.xml) to define the security requirements. Example 5-1 shows examples of how to use the ejb-jar.xml and weblogic-ejb-jar.xml deployment descriptors to map security role names to a security realm. The deployment descriptors map the application's logical security requirements to its runtime definitions. And at runtime, the EJB container uses the security definitions to enforce the requirements.
To configure security in the EJB deployment descriptors, perform the following steps (see Example 5-1):
Example 5-1 Using ejb-jar.xml and weblogic-ejb-jar.xml Files to Map Security Role Names to a Security Realm
ejb-jar.xml entries:
...
<assembly-descriptor>
<security-role>
<role-name>manger</role-name>
</security-role>
<security-role>
<role-name>east</role-name>
</security-role>
<method-permission>
<role-name>manager</role-name>
<role-name>east</role-name>
<method>
<ejb-name>accountsPayable</ejb-name>
<method-name>getReceipts</method-name>
</method>
</method-permission>
...
</assembly-descriptor>
...
weblogic-ejb-jar.xml entries:
<security-role-assignment>
<role-name>manager</role-name>
<principal-name>al</principal-name>
<principal-name>george</principal-name>
<principal-name>ralph</principal-name>
</security-role-assignment>
...EJB Security-Related Deployment Descriptors
WebLogic Server supports several deployment descriptor elements that are used in the ejb-jar.xml and weblogic-ejb-jar.xml files to define security requirements in EJBs.
ejb-jar.xml Deployment Descriptors
The following ejb-jar.xml deployment descriptor elements are used to define security requirements in WebLogic Server:
method
The method element is used to denote a method of an enterprise bean's home or component interface, or, in the case of a message-driven bean, the bean's onMessage method, or a set of methods.
The following table describes the elements you can define within an method element.
Table 5-1 method Element
| Element | Required/Optional | Description |
|---|---|---|
<description> |
Optional |
A text description of the method. |
<ejb-name> |
Required |
Specifies the name of one of the enterprise beans declared in the |
<method-intf> |
Optional |
Allows you to distinguish between a method with the same signature that is multiply defined across both the home and component interfaces of the enterprise bean. |
<method-name> |
Required |
Specifies a name of an enterprise bean method or the asterisk (*) character. The asterisk is used when the element denotes all the methods of an enterprise bean's component and home interfaces. |
<method-params> |
Optional |
Contains a list of the fully-qualified Java type names of the method parameters. |
method-permission
The method-permission element specifies that one or more security roles are allowed to invoke one or more enterprise bean methods. The method-permission element consists of an optional description, a list of security role names or an indicator to state that the method is unchecked for authorization, and a list of method elements.
The security roles used in the method-permission element must be defined in the security-role elements of the deployment descriptor, and the methods must be methods defined in the enterprise bean's component and/or home interfaces.
The following table describes the elements you can define within a method-permission element.
Table 5-2 method-permission Element
| Element | Required/Optional | Description |
|---|---|---|
<description> |
Optional |
A text description of this security constraint. |
<role-name> or <unchecked> |
Required |
The The The |
<method> |
Required |
Specifies a method of an enterprise bean's home or component interface, or, in the case of a message-driven bean, the bean's |
role-name
The role-name element contains the name of a security role. The name must conform to the lexical rules for an NMTOKEN.
Used Within
The role-name element is used within the method-permission, run-as, security-role, and security-role-ref elements.
run-as
The run-as element specifies the run-as identity to be used for the execution of the enterprise bean. It contains an optional description, and the name of a security role.
security-identity
The security-identity element specifies whether the caller's security identity is to be used for the execution of the methods of the enterprise bean or whether a specific run-as identity is to be used. It contains an optional description and a specification of the security identity to be used.
The following table describes the elements you can define within an security-identity element.
Table 5-3 security-identity Element
| Element | Required/Optional | Description |
|---|---|---|
<description> |
Optional |
A text description of the security identity. |
<use-caller-identity> or <run-as> |
Required |
The The The run-as element specifies the run-as identity to be used for the execution of the enterprise bean. It contains an optional description, and the name of a security role. |
Used Within
The security-identity element is used within the entity, message-driven, and session elements.
Example
For an example of how to use the security-identity element, see Example 5-3 and Example 5-8.
security-role
The security-role element contains the definition of a security role. The definition consists of an optional description of the security role, and the security role name.
security-role-ref
The security-role-ref element contains the declaration of a security role reference in the enterprise bean's code. The declaration consists of an optional description, the security role name used in the code, and an optional link to a security role. If the security role is not specified, the Deployer must choose an appropriate security role.
The value of the role-name element must be the String used as the parameter to the EJBContext.isCallerInRole(String roleName) method or the HttpServletRequest.isUserInRole(String role) method.
Example
For an example of how to use the security-role-ref element, see Example 5-2.
Example 5-2 Security-role-ref Element Example
<!DOC<weblogic-ejb-jar xmlns="http://www.bea.com/ns/weblogic/90"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.bea.com/ns/weblogic/90
http://www.bea.com/ns/weblogic/90/weblogic-ejb-jar.xsd">
<ejb-jar>
<enterprise-beans>
...
<session>
<ejb-name>SecuritySLEJB</ejb-name>
<home>weblogic.ejb20.security.SecuritySLHome</home>
<remote>weblogic.ejb20.security.SecuritySL</remote>
<ejb-class>weblogic.ejb20.security.SecuritySLBean</ejb-class>
<session-type>Stateless</session-type>
<transaction-type>Container</transaction-type>
<security-role-ref>
<role-name>rolenamedifffromlink</role-name>
<role-link>role121SL</role-link>
</security-role-ref>
<security-role-ref>
<role-name>roleForRemotes</role-name>
<role-link>roleForRemotes</role-link>
</security-role-ref>
<security-role-ref>
<role-name>roleForLocalAndRemote</role-name>
<role-link>roleForLocalAndRemote</role-link>
</security-role-ref>
</session>
...
</enterprise-beans>
</ejb-jar>
unchecked
The unchecked element specifies that a method is not checked for authorization by the container prior to invocation of the method.
use-caller-identity
The use-caller-identity element specifies that the caller's security identity be used as the security identity for the execution of the enterprise bean's methods.
Example
For an example of how to use the use-caller-identity element, see Example 5-3.
Example 5-3 use-caller-identity Element Example
<ejb-jar>
<enterprise-beans>
<session>
<ejb-name>SecurityEJB</ejb-name>
<home>weblogic.ejb20.SecuritySLHome</home>
<remote>weblogic.ejb20.SecuritySL</remote>
<local-home>
weblogic.ejb20.SecurityLocalSLHome
</local-home>
<local>weblogic.ejb20.SecurityLocalSL</local>
<ejb-class>weblogic.ejb20.SecuritySLBean</ejb-class>
<session-type>Stateless</session-type>
<transaction-type>Container</transaction-type>
</session>
<message-driven>
<ejb-name>SecurityEJB</ejb-name>
<ejb-class>weblogic.ejb20.SecuritySLBean</ejb-class>
<transaction-type>Container</transaction-type>
<security-identity>
<use-caller-identity/>
</security-identity>
</message-driven>
</enterprise-beans>
</ejb-jar>
weblogic-ejb-jar.xml Deployment Descriptors
The following weblogic-ejb-jar.xml deployment descriptor elements are used to define security requirements in WebLogic Server:
client-authentication
The client-authentication element specifies whether the EJB supports or requires client authentication.
The following table defines the possible settings.
Table 5-4 client-authentication Element
| Setting | Definition |
|---|---|
none |
Client authentication is not supported. |
supported |
Client authentication is supported, but not required. |
required |
Client authentication is required. |
client-cert-authentication
The client-cert-authentication element specifies whether the EJB supports or requires client certificate authentication at the transport level.
The following table defines the possible settings.
Table 5-5 client-cert-authentication Element
| Setting | Definition |
|---|---|
none |
Client certificate authentication is not supported. |
supported |
Client certificate authentication is supported, but not required. |
required |
Client certificate authentication is required. |
confidentiality
The confidentiality element specifies the transport confidentiality requirements for the EJB. Using the confidentiality element ensures that the data is sent between the client and server in such a way as to prevent other entities from observing the contents.
The following table defines the possible settings.
Table 5-6 confidentiality Element
| Setting | Definition |
|---|---|
none |
Confidentiality is not supported. |
supported |
Confidentiality is supported, but not required. |
required |
Confidentiality is required. |
externally-defined
The externally-defined element lets you explicitly indicate that you want the security roles defined by the role-name element in the weblogic-ejb-jar.xml deployment descriptors to use the mappings specified in the WebLogic Server Administration Console. The element gives you the flexibility of not having to specify a specific security role mapping for each security role defined in the deployment descriptors for a particular Web application. Therefore, within the same security realm, deployment descriptors can be used to specify and modify security for some applications while the WebLogic Server Administration Console can be used to specify and modify security for others.
Note:
Starting in version 9.0, the default role mapping behavior is to create empty role mappings when none are specified. In version 8.1, EJB required that role mappings be defined in the weblogic-ejb-jar.xml descriptor or deployment would fail. With 9.0, EJB and WebApp behavior are consistent in creating empty role mappings.
For information on role mapping behavior and backward compatibility settings, see the section Understanding the Combined Role Mapping Enabled Setting in Securing Resources Using Roles and Policies for Oracle WebLogic Server. The role mapping behavior for a server depends on which security deployment model is selected on the WebLogic Server Administration Console. For information on security deployment models, see Options for Securing EJB and Web Application Resources in Securing Resources Using Roles and Policies for Oracle WebLogic Server.
When specifying security role names, observe the following conventions and restrictions:
-
The proper syntax for a security role name is as defined for an
Nmtokenin the Extensible Markup Language (XML) recommendation available on the Web at:http://www.w3.org/TR/REC-xml#NT-Nmtoken. -
Do not use blank spaces, commas, hyphens, or any characters in this comma-separated list: \t, < >, #, |, &, ~, ?, ( ), { }.
-
Security role names are case sensitive.
-
The suggested convention for security role names is that they be singular.
Example 5-4 and Example 5-5 show by comparison how to use the externally-defined element in the weblogic-ejb-jar.xml file. In Example 5-5, the specification of the "manager" externally-defined element in the weblogic-ejb-jar.xml means that for security to be correctly configured on the getReceipts method, the principals for manager will have to be created in the WebLogic Server Administration Console.
Example 5-4 Using the ejb-jar.xml and weblogic-ejb-jar.xml Deployment Descriptors to Map Security Roles in EJBs
ejb-jar.xml entries:
...
<assembly-descriptor>
<security-role>
<role-name>manger</role-name>
</security-role>
<security-role>
<role-name>east</role-name>
</security-role>
<method-permission>
<role-name>manager</role-name>
<role-name>east</role-name>
<method>
<ejb-name>accountsPayable</ejb-name>
<method-name>getReceipts</method-name>
</method>
</method-permission>
...
</assembly-descriptor>
...
weblogic-ejb-jar.xml entries:
<security-role-assignment>
<role-name>manager</role-name>
<principal-name>joe</principal-name>
<principal-name>Bill</principal-name>
<principal-name>Mary</principal-name>
...
</security-role-assignment>
... Example 5-5 Using the externally-defined Element in EJB Deployment Descriptors for Role Mapping
ejb-jar.xml entries:
...
<assembly-descriptor>
<security-role>
<role-name>manger</role-name>
</security-role>
<security-role>
<role-name>east</role-name>
</security-role>
<method-permission>
<role-name>manager</role-name>
<role-name>east</role-name>
<method>
<ejb-name>accountsPayable</ejb-name>
<method-name>getReceipts</method-name>
</method>
</method-permission>
...
</assembly-descriptor>
...
weblogic-ejb-jar.xml entries:
<security-role-assignment>
<role-name>manager</role-name>
<externally-defined/>
...
</security-role-assignment>
...
For more information on using the WebLogic Server Administration Console to configure security for EJBs, see Options for Securing EJB and Web Application Resources in Securing Resources Using Roles and Policies for Oracle WebLogic Server.
identity-assertion
The identity-assertion element specifies whether the EJB supports identity assertion.
The following table defines the possible settings.
Table 5-7 identity-assertion Element
| Setting | Definition |
|---|---|
none |
Identity assertion is not supported |
supported |
Identity assertion is supported, but not required. |
required |
Identity assertion is required. |
iiop-security-descriptor
The iiop-security-descriptor element specifies security configuration parameters at the bean-level. These parameters determine the IIOP security information contained in the interoperable object reference (IOR).
Example
For an example of how to use the iiop-security-descriptor element, see Example 5-6.
Example 5-6 iiop-security-descriptor Element Example
<weblogic-enterprise-bean>
<iiop-security-descriptor>
<transport-requirements>
<confidentiality>supported</confidentiality>
<integrity>supported</integrity>
<client-cert-authorization>
supported
</client-cert-authentication>
</transport-requirements>
<client-authentication>supported<client-authentication>
<identity-assertion>supported</identity-assertion>
</iiop-security-descriptor>
</weblogic-enterprise-bean>integrity
The integrity element specifies the transport integrity requirements for the EJB. Using the integrity element ensures that the data is sent between the client and server in such a way that it cannot be changed in transit.
The following table defines the possible settings.
Table 5-8 integrity Element
| Setting | Definition |
|---|---|
none
|
Integrity is not supported. |
supported
|
Integrity is supported, but not required. |
required
|
Integrity is required. |
principal-name
The principal-name element specifies the name of the principal in the WebLogic Server security realm that applies to role name specified in the security-role-assignment element. At least one principal is required in the security-role-assignment element. You may define more than one principal-name for each role name.
Note:
If you need to list a significant number of principals, consider specifying groups instead of users. There are performance issues if you specify too many users.
role-name
The role-name element identifies an application role name that the EJB provider placed in the companion ejb-jar.xml file. Subsequent principal-name elements in the stanza map WebLogic Server principals to the specified role-name.
run-as-identity-principal
The run-as-identity-principal element specifies which security principal name is to be used as the run-as principal for a bean that has specified a security-identity run-as role-name in its ejb-jar deployment descriptor. For an explanation about how run-as role-names are mapped to run-as-identity-principals (or run-as-principal-names, see run-as-role-assignment.
Note:
Deprecated: The run-as-identity-principal element is deprecated in WebLogic Server 8.1. Use the run-as-principal-name element instead.
Used Within
The run-as-identity-principal element is used within the run-as-role-assignment element.
Example
For an example of how to use the run-as-identity-principal element, see Example 5-7.
Example 5-7 run-as-identity-principal Element Example
ebj-jar.xml:
<ejb-jar>
<enterprise-beans>
<session>
<ejb-name>Caller2EJB</ejb-name>
<home>weblogic.ejb11.security.CallerBeanHome</home>
<remote>weblogic.ejb11.security.CallerBeanRemote</remote>
<ejb-class>weblogic.ejb11.security.CallerBean</ejb-class>
<session-type>Stateful</session-type>
<transaction-type>Container</transaction-type>
<ejb-ref><ejb-ref-name>Callee2Bean</ejb-ref-name>
<ejb-ref-type>Session</ejb-ref-type>
<home>weblogic.ejb11.security.CalleeBeanHome</home>
<remote>weblogic.ejb11.security.CalleeBeanRemote</remote>
</ejb-ref>
<security-role-ref>
<role-name>users1</role-name>
<role-link>users1</role-link>
</security-role-ref>
<security-identity>
<run-as>
<role-name>users2</role-name>
</run-as>
</security-identity>
</session>
</enterprise-beans>
</ejb-jar>
woblogic-ejb-jar.xml:
<weblogic-ejb-jar>
<weblogic-enterprise-bean>
<ejb-name>Caller2EJB</ejb-name>
<reference-descriptor>
<ejb-reference-description>
<ejb-ref-name>Callee2Bean</ejb-ref-name>
<jndi-name>security.Callee2Bean</jndi-name>
</ejb-reference-description>
</reference-descriptor>
<run-as-identity-principal>wsUser3</run-as-identity-principal>
</weblogic-enterprise-bean>
<security-role-assignment>
<role-name>user</role-name>
<principal-name>wsUser2</principal-name>
<principal-name>wsUser3</principal-name>
<principal-name>wsUser4</principal-name>
</security-role-assignment>
</weblogic-ejb-jar>
run-as-principal-name
The run-as-principal-name element specifies which security principal name is to be used as the run-as principal for a bean that has specified a security-identity run-as role-name in its ejb-jar deployment descriptor. For an explanation of how the run-as role-names map to run-as-principal-names, see run-as-role-assignment.
run-as-role-assignment
The run-as-role-assignment element is used to map a given security-identity run-as role-name that is specified in the ejb-jar.xml file to a run-as-principal-name specified in the weblogic-ejb-jar.xml file. The value of the run-as-principal-name element for a given role-name is scoped to all beans in the ejb-jar.xml file that use the specified role-name as their security-identity. The value of the run-as-principal-name element specified in weblogic-ejb-jar.xml file can be overridden at the individual bean level by specifying a run-as-principal-name element under that bean's weblogic-enterprise-bean element.
Note:
For a given bean, if there is no run-as-principal-name element specified in either a run-as-role-assignment element or in a bean specific run-as-principal-name element, then the EJB container will choose the first principal-name of a security user in the weblogic-enterprise-bean security-role-assignment element for the role-name and use that principal-name as the run-as-principal-name.
Example
For an example of how to use the run-as-role-assignment element, see Example 5-8.
Example 5-8 run-as-role-assignment Element Example
In the ejb-jar.xml file:
// Beans "A_EJB_with_runAs_role_X" and "B_EJB_with_runAs_role_X"
// specify a security-identity run-as role-name "runAs_role_X".
// Bean "C_EJB_with_runAs_role_Y" specifies a security-identity
// run-as role-name "runAs_role_Y".
<ejb-jar>
<enterprise-beans>
<session>
<ejb-name>SecurityEJB</ejb-name>
<home>weblogic.ejb20.SecuritySLHome</home>
<remote>weblogic.ejb20.SecuritySL</remote>
<local-home>
weblogic.ejb20.SecurityLocalSLHome
</local-home>
<local>weblogic.ejb20.SecurityLocalSL</local>
<ejb-class>weblogic.ejb20.SecuritySLBean</ejb-class>
<session-type>Stateless</session-type>
<transaction-type>Container</transaction-type>
</session>
<message-driven>
<ejb-name>SecurityEJB</ejb-name>
<ejb-class>weblogic.ejb20.SecuritySLBean</ejb-class>
<transaction-type>Container</transaction-type>
<security-identity>
<run-as>
<role-name>runAs_role_X</role-name>
</run-as>
</security-identity>
<security-identity>
<run-as>
<role-name>runAs_role_Y</role-name>
</run-as>
</security-identity>
</message-driven>
</enterprise-beans>
</ejb-jar>
weblogic-ejb-jar file:
<weblogic-ejb-jar>
<weblogic-enterprise-bean>
<ejb-name>A_EJB_with_runAs_role_X</ejb-name>
</weblogic-enterprise-bean>
<weblogic-enterprise-bean>
<ejb-name>B_EJB_with_runAs_role_X</ejb-name>
<run-as-principal-name>Joe</run-as-principal-name>
</weblogic-enterprise-bean>
<weblogic-enterprise-bean>
<ejb-name>C_EJB_with_runAs_role_Y</ejb-name>
</weblogic-enterprise-bean>
<security-role-assignment>
<role-name>runAs_role_Y</role-name>
<principal-name>Harry</principal-name>
<principal-name>John</principal-name>
</security-role-assignment>
<run-as-role-assignment>
<role-name>runAs_role_X</role-name>
<run-as-principal-name>Fred</run-as-principal-name>
</run-as-role-assignment>
</weblogic-ejb-jar>
Each of the three beans shown in Example 5-8 will choose a different principal name to run as.
-
A_EJB_with_runAs_role_X
This bean's run-as role-name is
runAs_role_X. The jar-scoped<run-as-role-assignment>mapping will be used to look up the name of the principal to use. The<run-as-role-assignment>mapping specifies that for <role-name>runAs_role_Xwe are to use<run-as-principal-name>Fred. Therefore,Fredis the principal name that will be used. -
B_EJB_with_runAs_role_X
This bean's run-as role-name is also
runAs_role_X. This bean will not use the jar scoped<run-as-role-assignment>to look up the name of the principal to use because that value is overridden by this bean's<weblogic-enterprise-bean> <run-as-principal-name>valueJoe. ThereforeJoeis the principal name that will be used. -
C_EJB_with_runAs_role_Y
This bean's run-as role-name is
runAs_role_Y. There is no explicit mapping ofrunAs_role_Yto a run-as principal name, that is, there is no jar scoped<run-as-role-assignment>forrunAs_role_Ynor is there a bean scoped<run-as-principal-name>specified in this bean's<weblogic-enterprise-bean>. To determine the principal name to use, the<security-role-assignment>for<role-name>runAs_role_Yis examined. The first<principal-name>corresponding to a user that is not a Group is chosen. Therefore,Harryis the principal name that will be used.
security-permission
The security-permission element specifies a security permission that is associated with a Java EE Sandbox.
security-permission-spec
The security-permission-spec element specifies a single security permission based on the Security policy file syntax.
See the implementation of the security permission specification:
http://docs.oracle.com/javase/8/docs/technotes/guides/security/PolicyFiles.html#FileSyntax
Note:
Disregard the optional codebase and signedBy clauses.
Example
For an example of how to use the security-permission-spec element, see Example 5-9.
Example 5-9 security-permission-spec Element Example
<weblogic-ejb-jar>
<security-permission>
<description>Optional explanation goes here</description>
<security-permission-spec>
<!
A single grant statement following the syntax of
http://xmlns.jcp.org/j2se/1.5.0/docs/guide/security/PolicyFiles.html#FileSyntax,
without the codebase and signedBy clauses, goes here. For example:
-->
grant {
permission java.net.SocketPermission *, resolve;
};
</security-permission-spec>
</security-permission>
</weblogic-ejb-jar>
In Example 5-9, permission java.net.SocketPermission is the permission class name, "*" represents the target name, and resolve (resolve host/IP name service lookups) indicates the action.
security-role-assignment
The security-role-assignment element maps application roles in the ejb-jar.xml file to the names of security principals available in WebLogic Server.
Note:
For information on using the security-role-assignment element in a weblogic-application.xml deployment descriptor for an enterprise application, see Enterprise Application Deployment Descriptor Elements in Developing Applications for Oracle WebLogic Server.
transport-requirements
The transport-requirements element defines the transport requirements for the EJB.
Example
For an example of how to use the transport-requirements element, see Example 5-10.
Example 5-10 transport-requirements Element Example
<weblogic-enterprise-bean>
<iiop-security-descriptor>
<transport-requirements>
<confidentiality>supported</confidentiality>
<integrity>supported</integrity>
<client-cert-authorization>
supported
</client-cert-authentication>
</transport-requirements>
</iiop-security-descriptor>
<weblogic-enterprise-bean>Using Programmatic Security With EJBs
To implement programmatic security in EJBs, WebLogic Server supports the use of the Java EE Security API getCallerPrincipal, getPrincipalsByType, and isCallerInRole methods of the SecurityContext interface, and the getCallerPrincipal and isCallerInRole methods of the javax.ejb.EJBContext interface.
The following sections describe these methods in more detail:
SecurityContext Interface Methods
The SecurityContext interface, as specified in the Java EE Security API, defines three methods that allow the bean provider to access security information about the enterprise bean’s caller:
-
getCallerPrincipal()retrieves the Principal that represents the name of the authenticated caller. This is the container-specific representation of the caller principal. The type may differ from the type of the caller principal originally established by anHttpAuthenticationMechanism. This method returns null for an unauthenticated caller in either the Servlet Container or the EJB Container. Note that this behavior differs from the behavior of theEJBContext.getCallerPrincipal()method, which returns a special principal to represent an anonymous caller. -
getPrincipalsByType()retrieves all principals of the given type from the authenticated callers subject. This method returns an emptySetif the caller is unauthenticated, or if the requested type is not found.Where both a container caller principal and an application caller principal are present, the value returned by
getName()is the same for both principals. -
isCallerInRole()takes a String argument that represents the specific role to be verified. The result must be the same as if the corresponding container-specific call had been made (for exampleEJBContext.isCallerInRole()).
EJBContext Interface Methods
The javax.ejb.EJBContext interface defines two methods that allow the bean provider to access security information about the enterprise bean’s caller:
-
getCallerPrincipalallows the enterprise bean methods to obtain the current caller principal's name. The methods might, for example, use the name as a key to information in a database. This method never returns null. Instead, it returns a principal with a special username to indicate an anonymous/unauthenticated caller. Note that this behavior differs from the behavior of theSecurityContext.getCallerPrincipal()method, which returns null for an unauthenticated caller.In WebLogic Server, you use the
getCallerPrincipal()method to determine the caller of the EJB. Thejavax.ejb.EJBContext.getCallerPrincipal()method returns aWLSUserPrincipalif one exists in theSubjectof the calling user. In the case of multipleWLSUserPrincipals, the method returns the first in the ordering defined by theSubject.getPrincipals().iterator()method. If there are noWLSUserPrincipals, then thegetCallerPrincipal()method returns the first non-WLSGroupPrincipal. If there are noPrincipalsor allPrincipalsare of typeWLSGroup, this method returnsweblogic.security.WLSPrincipals.getAnonymousUserPrincipal(). This behavior is similar to the semantics ofweblogic.security.SubjectUtils.getUserPrincipal()except thatSubjectUtils.getUserPrincipal()returns anullwhereasEJBContext.getCallerPrincipal()returnsWLSPrincipals.getAnonmyousUserPrincipal(). -
isCallerInRoleallows the developer to code the security checks that cannot be easily defined using method permissions. Such a check might impose a role-based limit on a request, or it might depend on information stored in the database. The enterprise bean code can use theisCallerInRolemethod to test whether the current caller has been assigned to a given security role. Security roles are defined by the bean provider or the application assembler and are assigned by the deployer to principals or principal groups that exist in the operational environment.In WebLogic Server, the
isCallerInRole()method is used to determine if the caller (the current user) has been assigned a security role that is authorized to perform actions on the WebLogic resources in that thread of execution. For example, the methodjavax.ejb.EJBContext.isCallerInRole("admin")will returntrueif the current user hasadminprivileges.
For information about using these methods, see the Enterprise Java Beans specification.