Skip navigation.
Downloads | Product Documentation | Support

Programming WebLogic Security

# Securing Enterprise JavaBeans (EJBs)

WebLogic Server supports the J2EE architecture security model for securing Enterprise JavaBeans (EJBs), which includes support for declarative authorization (also referred to in this document as declarative security) and programmatic authorization (also referred to in this document as programmatic security).

The following topics are covered in this section:

- J2EE Architecture Security Model
- Using Declarative Security With EJBs
- EJB Security-Related Deployment Descriptors
- Using Programmatic Security With EJBs

Note: You can use deployment descriptor files and the Administration Console to secure EJBs. For information on using the Administration Console to secure EJBs, see Securing WebLogic Resources.

# J2EE Architecture Security Model

The document Designing Enterprise Applications with the J2EE Platform, Second Edition, published by Sun Microsystems, Inc., states in Section 9.3 Authorization:

"In the J2EE architecture, a container serves as an authorization boundary between the components it hosts and their callers. The authorization boundary exists inside the container's authentication boundary so that authorization is considered in the context of successful authentication. For inbound calls, the container compares security attributes from the caller's credential with the access control rules for the target component. If the rules are satisfied, the call is allowed. Otherwise, the call is rejected."

"There are two fundamental approaches to defining access control rules: capabilities and permissions. Capabilities focus on what a caller can do. Permissions focus on who can do something. The J2EE application programming model focuses on permissions. In the J2EE architecture, the job of the deployer is to map the permission model of the application to the capabilities of users in the operational environment."

The same document then discusses two ways to control access to application resources using the J2EE architecture, declarative authorization and programmatic authorization.

The document Designing Enterprise Applications with the J2EE Platform, Second Edition, published by Sun Microsystems, Inc., in available online at http://java.sun.com/blueprints/guidelines/designing_enterprise_applications_2e/security/security4.html.

## Declarative Authorization

The document Designing Enterprise Applications with the J2EE Platform, Second Edition, published by Sun Microsystems, Inc., states in Section 9.3.1 Authorization:

"The deployer establishes the container-enforced access control rules associated with a J2EE application. The deployer uses a deployment tool to map an application permission model, which is typically supplied by the application assembler, to policy and mechanisms specific to the operational environment. The application permission model is defined in a deployment descriptor."

WebLogic Server supports the use of deployment descriptors to implement declarative authorization in EJBs.

Note: Declarative authorization is also referred in this document as declarative security.

The document Designing Enterprise Applications with the J2EE Platform, Second Edition, published by Sun Microsystems, Inc., in available online at http://java.sun.com/blueprints/guidelines/designing_enterprise_applications_2e/security/security4.html.

## Programmatic Authorization

The document Designing Enterprise Applications with the J2EE Platform, Second Edition, published by Sun Microsystems, Inc., states in Section 9.3.2 Programmatic Authorization:

"A J2EE container makes access control decisions before dispatching method calls to a component. The logic or state of the component doesn't factor in these access decisions. However, a component can use two methods, EJBContext.isCallerInRole (for use by enterprise bean code) and HttpServletRequest.isUserInRole (for use by Web components), to perform finer-grained access control. A component uses these methods to determine whether a caller has been granted a privilege selected by the component based on the parameters of the call, the internal state of the component, or other factors such as the time of the call."

"The application component provider of a component that calls one of these functions must declare the complete set of distinct roleName values to be used in all calls. These declarations appear in the deployment descriptor as `security-role-ref` elements. Each `security-role-ref` element links a privilege name embedded in the application as a roleName to a security role. Ultimately, the deployer establishes the link between the privilege names embedded in the application and the security roles defined in the deployment descriptor. The link between privilege names and security roles may differ for components in the same application."

"In addition to testing for specific privileges, an application component can compare the identity of its caller, acquired using `EJBContext.getCallerPrincipal` or `HttpServletRequest.getUserPrincipal`, to the distinguished caller identities embedded in the state of the component when it was created. If the identity of the caller is equivalent to a distinguished caller, the component can allow the caller to proceed. If not, the component can prevent the caller from further interaction. The caller principal returned by a container depends on the authentication mechanism used by the caller. Also, containers from different vendors may return different principals for the same user authenticating by the same mechanism. To account for variability in principal forms, an application developer who chooses to apply distinguished caller state in component access decisions should allow multiple distinguished caller identities, representing the same user, to be associated with components. This is recommended especially where application flexibility or portability is a priority."

WebLogic Server supports the use of the `EJBContext.isCallerInRole` and `EJBContext.getCallerPrincipal` methods and the use of the `security-role-ref` element in deployment descriptors to implement programmatic authorization in EJBs.

Note: Programmatic authorization is also referred in this document as programmatic security.

The document Designing Enterprise Applications with the J2EE Platform, Second Edition, published by Sun Microsystems, Inc., in available online at http://java.sun.com/blueprints/guidelines/designing_enterprise_applications_2e/security/security4.html.

## Declarative Versus Programmatic Authorization

The document Designing Enterprise Applications with the J2EE Platform, Second Edition, published by Sun Microsystems, Inc., states in Section 9.3.3 Declarative Versus Programmatic Authorization:

"There is a trade-off between the external access control policy configured by the deployer and the internal policy embedded in the application by the component provider. The external policy is more flexible after the application has been written. The internal policy provides more flexible functionality while the application is being written. In addition, the external policy is transparent and completely comprehensible to the deployer, while internal policy is buried in the application and may only be completely understood by the application developer. These trade-offs should be considered in choosing the authorization model for particular components and methods."

The document Designing Enterprise Applications with the J2EE Platform, Second Edition, published by Sun Microsystems, Inc., in available online at http://java.sun.com/blueprints/guidelines/designing_enterprise_applications_2e/security/security4.html.

# Using Declarative Security With EJBs

To implement declarative security in EJBs you use deployment descriptors (`ejb-jar.xml` and `weblogic-ejb-jar.xml`) to define the security requirements. Listing 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 Listing 5-1):

1. Use a text editor to create `ejb-jar.xml` and `weblogic-ejb-jar.xml` deployment descriptor files.
2. In the `ejb-jar.xml` file, define the security role name, the EJB name, and the method name (see bold text).

Note: When specifying security role names, observe the following conventions and restrictions:

- The proper syntax for a security role name is as defined for an `Nmtoken` in 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 BEA suggested convention for security role names is that they be singular.

For more information on configuring security in the `ejb-jar.xml` file, see the Sun Microsystems Enterprise JavaBeans Specification, Version 2.0 which is at this location on the Internet: `http://java.sun.com/products/ejb/docs.html`.

3. In the WebLogic-specific EJB deployment descriptor file, `weblogic-ejb-jar.xml`, define the security role name and link it to one or more principals (users or groups) in a security realm.

For more information on configuring security in the `weblogic-ejb-jar.xml` file, see weblogic-ejb-jar.xml Deployment Descriptor Reference in Programming WebLogic Enterprise JavaBeans.

Listing 5-1 Using the 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

The following topics describe the 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
- weblogic-ejb-jar.xml Deployment Descriptors

## ejb-jar.xml Deployment Descriptors

The following `ejb-jar.xml` deployment descriptor elements are used to define security requirements in WebLogic Server:

- method
- method-permission
- role-name
- run-as
- security-identity
- security-role
- security-role-ref
- unchecked
- use-caller-identity

The information in this section is based on the Document Type Descriptor (DTD) for `ejb-jar.xml` provided by Sun Microsystems, Inc. The DTD for `ejb-jar.xml` is available on the Web at http://java.sun.com/dtd/ejb-jar_2_0.dtd.

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

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 `ejb-jar.xml` file.
`<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.

#### Used Within

The `method` element is used within the `method-permission` element.

#### Example

For an example of how to use the `method` element, see Listing 5-1.

### 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 an `method-permission` element.

Element | Required/ Optional | Description
--- | --- | ---
`<description>` | Optional | A text description of this security constraint.
`<role-name> or` <unchecked> | Required | The `role-name` element or the `unchecked` element must be specified. The `role-name` element contains the name of a security role. The name must conform to the lexical rules for an `NMTOKEN`. The `unchecked` element specifies that a method is not checked for authorization by the container prior to invocation of the method.
<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 `onMessage` method, or a set of methods.

#### Used Within

The `method-permission` element is used within the `assembly-descriptor` element.

#### Example

For an example of how to use the `method-permission` element, see Listing 5-1.

### 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.`

#### Example

For an example of how to use the `role-name` element, see Listing 5-1.

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

#### Used Within

The run-as element is used within the `security-identity` element.

#### Example

For an example of how to use the `run-as` element, see Listing 5-8.

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

Element | Required/ Optional | Description
--- | --- | ---
`<description>` | Optional | A text description of the security identity.
`<use-caller-identity> or` <run-as> | Required | The `use-caller-identity` element or the run-as element must be specified. 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. 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 Listing 5-3 and Listing 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.

#### Used Within

The `security-role` element is used within the `assembly-descriptor` element.

#### Example

For an example of how to use the `assembly-descriptor` element, see Listing 5-1.

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

#### Used Within

The `security-role-ref` element is used within the `entity` and `session` elements.

#### Example

For an example of how to use the security-role-ref element, see Listing 5-2.

Listing 5-2 Security-role-ref Element Example

>     <!DOCTYPE ejb-jar PUBLIC '-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0//EN' 'http://java.sun.com/dtd/ejb-jar_2_0.dtd'>

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

#### Used Within

The `unchecked` element is used within the `method-permission` element.

#### Example

For an example of how to use the `unchecked` element, see Listing 5-1.

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

#### Used Within

The `use-caller-identity` element is used within the `security-identity` element.

#### Example

For an example of how to use the `use-caller-identity` element, see Listing 5-3.

Listing 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
- client-cert-authentication
- confidentiality
- externally-defined
- identity-assertion
- iiop-security-descriptor
- integrity
- principal-name
- role-name
- run-as-identity-principal
- run-as-principal-name
- run-as-role-assignment
- security-permission
- security-permission-spec
- security-role-assignment
- transport-requirements

### client-authentication

The `client-authentication` element specifies whether the EJB supports or requires client authentication.

The following table defines the possible settings.

Setting | Definition
--- | ---
None | Client authentication is not supported.
`Supported` | Client authentication is supported, but not required.
`Required` | Client authentication is required.

#### Example

For an example of how to use the `client-authentication` element, see Listing 5-6.

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

Setting | Definition
--- | ---
None | Client certificate authentication is not supported.
`Supported` | Client certificate authentication is supported, but not required.
`Required` | Client certificate authentication is required.

#### Example

For an example of how to use the `client-cert-authentication` element, see Listing 5-10.

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

Setting | Definition
--- | ---
None | Confidentiality is not supported.
`Supported` | Confidentiality is supported, but not required.
`Required` | Confidentiality is required.

#### Example

For an example of how to use the `confidentiality` element, see Listing 5-10.

### externally-defined

In WebLogic Server 8.1 and later, the `externally-defined` tag is supported for use in the `weblogic-ejb-jar.xml` deployment descriptors. You can use this tag, instead of the `<principal-name>` tag, to explicitly indicate that you want the security roles defined in the deployment descriptors by the `<role-name>` tag in the `weblogic-ejb-jar.xml` file to use the mappings that you specify in the Administration Console.

Note: The `externally-defined element` replaces the `global-role element` that was used in WebLogic Server 7.0 SP1. The `externally-defined` tag has the same functionality as the `global-role` element. The `global-role` element was deprecated in WebLogic Server 8.1.

The `externally-defined element` gives you the flexibility of not having to specify a specific role mapping for each security role defined in the deployment descriptors for a particular EJB. Rather, you can use the Administration Console to specify and modify a specific role mapping for each defined role at anytime. Additionally, because you may elect to use this tag on some EJBs and not others, it is not necessary to select the ignore roles and polices from DD option for the security realm. You select this option in the On Future Redeploys: field on the General tab of the Security->Realms->myrealm control panel on the Administration Console. Thus, within the same security realm, deployment descriptors can be used to specify and modify security for some EJBs, while the Administration Console can be used to specify and modify security for others.

Note: When specifying security role names, observe the following conventions and restrictions:

- The proper syntax for a security role name is as defined for an `Nmtoken` in 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 BEA suggested convention for security role names is that they be singular.

Listing 5-4 and Listing 5-5 show by comparison how to use the `externally-defined` element in the `weblogic-ejb-jar.xml` file. In Listing 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 Administration Console.

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

Listing 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 Administration Console to configure security for EJBs, see Securing WebLogic Resources.

### identity-assertion

The `identity-assertion` element specifies whether the EJB supports identity assertion.

The following table defines the possible settings.

Setting | Definition
--- | ---
None | Identity assertion is not supported
`Supported` | Identity assertion is supported, but not required.
`Required` | Identity assertion is required.

#### Used Within

The `identity-assertion` element is used with the `iiop-security-descriptor` element.

#### Example

For an example of how to the `identity-assertion` element, see Listing 5-6.

### 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 Listing 5-6.

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

Setting | Definition
--- | ---
None | Integrity is not supported.
`Supported` | Integrity is supported, but not required.
`Required` | Integrity is required.

#### Used Within

The `integrity` element is used within the `transport-requirements` element.

#### Example

For an example of how to use the `integrity` element, see Listing 5-10.

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

#### Used Within

The `principal-name` element is used within the `security-role-assignment` element.

#### Example

For an example of how to use the `principal-name` element, see Listing 5-1.

### 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`.

#### Used Within

The `role-name` element is used within the `security-role-assignment` element.

#### Example

For an example of how to use the `role-name` element, see Listing 5-1.

### 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 of how of run-as role-names to 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 the 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 Listing 5-7.

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

#### Used Within

The `run-as-principal-name` element is used within the `run-as-role-assignment` element.

#### Example

For an example of how to use the `run-as-principal-name` element, see Listing 5-8.

### 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 Listing 5-8.

Listing 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 Listing 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_X" we are to use <run-as-principal-name> "Fred". Therefore, 'Fred' is 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> value "Joe". Therefore "Joe" is 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 of "runAs_role_Y to a run-as principal name, that is, there is no jar scoped <run-as-role-assignment> for "runAs_role_Y" nor 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_Y" is examined. The first <principal-name> corresponding to a user that is not a Group is chosen. Therefore, "Harry" is the principal name that will be used.

### security-permission

The `security-permission` element specifies a security permission that is associated with a J2EE Sandbox.

#### Example

For an example of how to use the `security-permission` element, see Listing 5-9.

### security-permission-spec

The `security-permission-spec` element specifies a single security permission based on the Security policy file syntax.

For more information, see Sun's implementation of the security permission specification:

http://java.sun.com/j2se/1.3/docs/guide/security/PolicyFiles.html#FileSyntax

Note: Disregard the optional codebase and signedBy clauses.

#### Used Within

The `security-permission-spec` element is used within the `security-permission` element.

#### Example

For an example of how to use the `security-permission-spec` element, see Listing 5-9.

Listing 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://java.sun.com/j2se/1.3/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 Listing 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.

#### Example

For an example of how to use the `security-role-assignment` element, see Listing 5-1.

### transport-requirements

The `transport-requirements` element defines the transport requirements for the EJB.

#### Used Within

The `transport-requirements` element is used within the iiop-security-descriptor element.

#### Example

For an example of how to use the `transport-requirements` element, see Listing 5-10.

Listing 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 you use the `javax.ejb.EJBContext`.`getCallerPrincipal()` and the `javax.ejb.EJBContext.isCallerInRole()` methods.

#### getCallerPrincipal

You use the `getCallerPrincipal()` method to determine the caller of the EJB. The `javax.ejb.EJBContext`.`getCallerPrincipal()` method returns a `WLSUser` `Principal` if one exists in the `Subject` of the calling user. In the case of multiple `WLSUser` `Principals`, the method returns the first in the ordering defined by the `Subject.getPrincipals().iterator()` method. If there are no `WLSUser` `Principals`, then the `getCallerPrincipal()` method returns the first non-`WLSGroup` `Principal`. If there are no `Principals` or all `Principals` are of type `WLSGroup`, this method returns `weblogic.security.WLSPrincipals.getAnonymousUserPrincipal()`. This behavior is similar to the semantics of `weblogic.security.SubjectUtils.getUserPrincipal()` except that `SubjectUtils.getUserPrincipal()` returns a `null` whereas `EJBContext`.`getCallerPrincipal()`returns `WLSPrincipals.getAnonmyousUserPrincipal()`.

For more information about how to use the `getCallerPrincipal()` method, see http://java.sun.com/j2ee/1.4/docs/tutorial/doc/Security7.html#79857.

#### isCallerInRole

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 method `javax.ejb.EJBContext.isCallerInRole("admin")`will return `true` if the current user has `admin` privileges.

For more information about how to use the `isCallerInRole()` method, see http://java.sun.com/j2ee/1.4/docs/tutorial/doc/Security7.html#79857.

For Javadoc for the `isCallerInRole()` method, see http://java.sun.com/products/ejb/javadoc-1.1/javax/ejb/EJBContext.html#isCallerInRole(java.lang.String).