Chapter 6. EJB Application Security

6.1. Security Identity

6.1.1. About EJB Security Identity

An EJB can specify an identity to use when invoking methods on other components. This is the EJB security identity, also known as invocation identity.

By default, the EJB uses its own caller identity. The identity can alternatively be set to a specific security role. Using specific security roles is useful when you want to construct a segmented security model - for example, restricting access to a set of components to internal EJBs only.

6.1.2. Set the Security Identity of an EJB

The security identity of the EJB is specified through the <security-identity> tag in the security configuration. If no <security-identity> tag is present, the caller identity of the EJB is used by default.

Example: Set the security identity of an EJB to be the same as its caller

This example sets the security identity for method invocations made by an EJB to be the same as the current caller’s identity. This behavior is the default if you do not specify a <security-identity> element declaration.

<ejb-jar>
  <enterprise-beans>
     <session>
        <ejb-name>ASessionBean</ejb-name>
        <!-- ... -->
        <security-identity>
          <use-caller-identity/>
        </security-identity>
     </session>
     <!-- ... -->
  </enterprise-beans>
</ejb-jar>

Example: Set the security identity of an EJB to a specific role

To set the security identity to a specific role, use the <run-as> and <role-name> tags inside the <security-identity> tag.

<ejb-jar>
  <enterprise-beans>
     <session>
        <ejb-name>RunAsBean</ejb-name>
        <!-- ... -->
        <security-identity>
          <run-as>
             <description>A private internal role</description>
             <role-name>InternalRole</role-name>
          </run-as>
        </security-identity>
     </session>
  </enterprise-beans>
  <!-- ... -->
</ejb-jar>

By default, when you use <run-as>, a principal named anonymous is assigned to outgoing calls. To assign a different principal, uses the <run-as-principal>.

<session>
    <ejb-name>RunAsBean</ejb-name>
    <security-identity>
        <run-as-principal>internal</run-as-principal>
    </security-identity>
</session>
Note

You can also use the <run-as> and <run-as-principal> elements inside a servlet element.

6.2. EJB Method Permissions

6.2.1. About EJB Method Permissions

EJBs can restrict access to their methods to specific security roles.

The EJB <method-permission> element declaration specifies the roles that can invoke the interface methods of the EJB. You can specify permissions for the following combinations:

  • All home and component interface methods of the named EJB
  • A specified method of the home or component interface of the named EJB
  • A specified method within a set of methods with an overloaded name.

6.2.2. Use EJB Method Permissions

Overview

The <method-permission> element defines the logical roles that are allowed to access the EJB methods defined by <method> elements. Several examples demonstrate the syntax of the xml. Multiple method permission statements may be present, and they have a cumulative effect. The <method-permission> element is a child of the <assembly-descriptor> element of the <ejb-jar> descriptor.

The XML syntax is an alternative to using annotations for EJB method permissions.

Example: Allow roles to access all methods of an EJB

<method-permission>
  <description>The employee and temp-employee roles may access any method
  of the EmployeeService bean </description>
  <role-name>employee</role-name>
  <role-name>temp-employee</role-name>
  <method>
    <ejb-name>EmployeeService</ejb-name>
    <method-name>*</method-name>
  </method>
</method-permission>

Example: Allow roles to access only specific methods of an EJB, and limiting which method parameters can be passed

<method-permission>
  <description>The employee role may access the findByPrimaryKey,
  getEmployeeInfo, and the updateEmployeeInfo(String) method of
  the AcmePayroll bean </description>
  <role-name>employee</role-name>
  <method>
    <ejb-name>AcmePayroll</ejb-name>
    <method-name>findByPrimaryKey</method-name>
  </method>
  <method>
    <ejb-name>AcmePayroll</ejb-name>
    <method-name>getEmployeeInfo</method-name>
  </method>
  <method>
    <ejb-name>AcmePayroll</ejb-name>
    <method-name>updateEmployeeInfo</method-name>
    <method-params>
      <method-param>java.lang.String</method-param>
    </method-params>
  </method>
</method-permission>

Example: Allow any authenticated user to access methods of EJBs

Using the <unchecked/> element allows any authenticated user to use the specified methods.

<method-permission>
  <description>Any authenticated user may access any method of the
  EmployeeServiceHelp bean</description>
  <unchecked/>
  <method>
    <ejb-name>EmployeeServiceHelp</ejb-name>
    <method-name>*</method-name>
  </method>
</method-permission>

Example: Completely exclude specific EJB methods from being used

<exclude-list>
  <description>No fireTheCTO methods of the EmployeeFiring bean may be
  used in this deployment</description>
  <method>
    <ejb-name>EmployeeFiring</ejb-name>
    <method-name>fireTheCTO</method-name>
  </method>
</exclude-list>

Example: A complete <assembly-descriptor> containing several <method-permission> blocks

<ejb-jar>
    <assembly-descriptor>
        <method-permission>
            <description>The employee and temp-employee roles may access any
                method of the EmployeeService bean </description>
            <role-name>employee</role-name>
            <role-name>temp-employee</role-name>
            <method>
                <ejb-name>EmployeeService</ejb-name>
                <method-name>*</method-name>
            </method>
        </method-permission>
        <method-permission>
            <description>The employee role may access the findByPrimaryKey,
                getEmployeeInfo, and the updateEmployeeInfo(String) method of
                the AcmePayroll bean </description>
            <role-name>employee</role-name>
            <method>
                <ejb-name>AcmePayroll</ejb-name>
                <method-name>findByPrimaryKey</method-name>
            </method>
            <method>
                <ejb-name>AcmePayroll</ejb-name>
                <method-name>getEmployeeInfo</method-name>
            </method>
            <method>
                <ejb-name>AcmePayroll</ejb-name>
                <method-name>updateEmployeeInfo</method-name>
                <method-params>
                    <method-param>java.lang.String</method-param>
                </method-params>
            </method>
        </method-permission>
        <method-permission>
            <description>The admin role may access any method of the
                EmployeeServiceAdmin bean </description>
            <role-name>admin</role-name>
            <method>
                <ejb-name>EmployeeServiceAdmin</ejb-name>
                <method-name>*</method-name>
            </method>
        </method-permission>
        <method-permission>
            <description>Any authenticated user may access any method of the
                EmployeeServiceHelp bean</description>
            <unchecked/>
            <method>
                <ejb-name>EmployeeServiceHelp</ejb-name>
                <method-name>*</method-name>
            </method>
        </method-permission>
        <exclude-list>
            <description>No fireTheCTO methods of the EmployeeFiring bean may be
                used in this deployment</description>
            <method>
                <ejb-name>EmployeeFiring</ejb-name>
                <method-name>fireTheCTO</method-name>
            </method>
        </exclude-list>
    </assembly-descriptor>
</ejb-jar>

6.3. EJB Security Annotations

6.3.1. About EJB Security Annotations

EJB javax.annotation.security annotations are defined in JSR250.

EJBs use security annotations to pass information about security to the deployer. These include:

@DeclareRoles
Declares which roles are available.
@RunAs
Configures the propagated security identity of a component.

6.3.2. Use EJB Security Annotations

Overview

You can use either XML descriptors or annotations to control which security roles are able to call methods in your Enterprise JavaBeans (EJBs). For information on using XML descriptors, refer to Use EJB Method Permissions.

Any method values explicitly specified in the deployment descriptor override annotation values. If a method value is not specified in the deployment descriptor, those values set using annotations are used. The overriding granularity is on a per-method basis.

Annotations for Controlling Security Permissions of EJBs

@DeclareRoles
Use @DeclareRoles to define which security roles to check permissions against. If no @DeclareRoles is present, the list is built automatically from the @RolesAllowed annotation. For information about configuring roles, refer to the Java EE 7 Tutorial Specifying Authorized Users by Declaring Security Roles.
@RolesAllowed, @PermitAll, @DenyAll
Use @RolesAllowed to list which roles are allowed to access a method or methods. Use @PermitAll or @DenyAll to either permit or deny all roles from using a method or methods. For information about configuring annotation method permissions, refer to the Java EE 7 Tutorial Specifying Authorized Users by Declaring Security Roles.
@RunAs
Use @RunAs to specify a role a method uses when making calls from the annotated method. For information about configuring propagated security identities using annotations, refer to the Java EE 7 Tutorial section 49.2.3, Propagating a Security Identity (Run-As).

Example: Security Annotations Example

@Stateless
@RolesAllowed({"admin"})
@SecurityDomain("other")
public class WelcomeEJB implements Welcome {
    @PermitAll
    public String WelcomeEveryone(String msg) {
        return "Welcome to " + msg;
    }
    @RunAs("tempemployee")
    public String GoodBye(String msg) {
        return "Goodbye, " + msg;
    }
    public String GoodbyeAdmin(String msg) {
        return "See you later, " + msg;
    }
}

In this code, all roles can access method WelcomeEveryone. The GoodBye method uses the tempemployee role when making calls. Only the admin role can access method GoodbyeAdmin, and any other methods with no security annotation.

6.4. Remote Access to EJBs

6.4.1. Use Security Realms with Remote EJB Clients

One way to add security to clients which invoke EJBs remotely is to use security realms. A security realm is a simple database of username/password pairs and username/role pairs. The terminology is also used in the context of web containers, with a slightly different meaning.

To authenticate a specific username/password pair that exists in a security realm against an EJB, follow these steps:

  • Add a new security realm to the domain controller or standalone server.
  • Add the following parameters to the jboss-ejb-client.properties file, which is in the classpath of the application. This example assumes the connection is referred to as default by the other parameters in the file.

    remote.connection.default.username=appuser
    remote.connection.default.password=apppassword
  • Create a custom Remoting connector on the domain or standalone server, which uses your new security realm.
  • Deploy your EJB to the server group which is configured to use the profile with the custom Remoting connector, or to your standalone server if you are not using a managed domain.

6.4.2. Add a New Security Realm

  1. Run the Management CLI:

    Start the jboss-cli.sh or jboss-cli.bat command and connect to the server.

  2. Create the new security realm itself:

    Run the following command to create a new security realm named MyDomainRealm on a domain controller or a standalone server.

    For a domain instance, use this command:

    /host=master/core-service=management/security-realm=MyDomainRealm:add()

    For a standalone instance, use this command:

    /core-service=management/security-realm=MyDomainRealm:add()
  3. Create a properties file named myfile.properties:

    For a standalone instance, create a file EAP_HOME/standalone/configuration/myfile.properties and for a domain instance, create a file EAP_HOME/domain/configuration/myfile.properties. These files need to have read and write access for the file owner.

    chmod 600 myfile.properties
  4. Create the references to the properties file which will store information about the new role:

    Run the following command to create a pointer to the myfile.properties file, which will contain the properties pertaining to the new role.

    Note

    The properties file will not be created by the included add-user.sh and add-user.bat scripts. It must be created externally.

    For a domain instance, use this command:

    /host=master/core-service=management/security-realm=MyDomainRealm/authentication=properties:add(path=myfile.properties)

    For a standalone instance, use this command:

    /core-service=management/security-realm=MyDomainRealm/authentication=properties:add(path=myfile.properties)

Your new security realm is created. When you add users and roles to this new realm, the information will be stored in a separate file from the default security realms. You can manage this new file using your own applications or procedures.

Note

When using the add-user.sh script to add a user to a non-default file, other than application-users.properties, you have to pass it the argument --user-properties myfile.properties otherwise it will try to use application-users.properties.

6.4.3. Add a User to a Security Realm

  1. Run the add-user.sh or add-user.bat command. Open a terminal and change directories to the /bin/ directory. If you are on Red Hat Enterprise Linux or any other UNIX-like operating system, run add-user.sh. If you are on Microsoft Windows Server, run add-user.bat.
  2. Choose whether to add a management user or application user. For this procedure, type b to add an application user.
  3. Choose the realm the user will be added to. By default, the only available realm is ApplicationRealm. If you have added a custom realm, you may add the user to that instead.
  4. Type the username, password, and roles, when prompted. Type the desired username, password, and optional roles when prompted. Verify your choice by typing yes, or type no to cancel the changes. The changes are written to each of the properties files for the security realm.

6.4.4. Relationship Between Security Domains and Security Realms

Important

For EJBs to be secured by security realms, they have to use a security domain which is configured to retrieve user credentials from the security realm. This means that the domain needs to contain the Remoting and RealmDirect login modules. Assigning a security domain is done by the @SecurityDomain annotation, which can be applied on an EJB.

The other security domain retrieves the user and password data from the underlying security realm. This security domain is the default one if there is no @SecurityDomain annotation on the EJB but the EJB contains any of the other security-related annotations to be considered secured.

The underlying http-remoting connector, which is used by the client to establish a connection, decides which security realm is used. For more information on http-remoting connector, see About the Remoting Subsystem in the JBoss EAP Configuration Guide.

The security realm of the default connector can be changed this way:

/subsystem=remoting/http-connector=http-remoting-connector:write-attribute(name=security-realm,value=MyDomainRealm)

6.4.5. About Remote EJB Access Using SSL Encryption

By default, the network traffic for Remote Method Invocation (RMI) of EJB2 and EJB3 Beans is not encrypted. In instances where encryption is required, Secure Sockets Layer (SSL) can be utilized so that the connection between the client and server is encrypted. Using SSL also has the added benefit of allowing the network traffic to traverse some firewalls, depending on the firewall configuration.

Warning

Red Hat recommends that SSLv2, SSLv3, and TLSv1.0 be explicitly disabled in favor of TLSv1.1 or TLSv1.2 in all affected packages.