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>
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
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 Certain Methods of an EJB and Limit Method Parameters
<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
<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 JSR-250.
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
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, see 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, see 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, see 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, see the Java EE 7 tutorial 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.
Configure the
wildfly-config.xml
file, which is located in the class path of the application, as shown in the following example:<configuration> <authentication-client xmlns="urn:elytron:1.0.1"> <authentication-rules> <rule use-configuration="default" /> </authentication-rules> <authentication-configurations> <configuration name="default"> <sasl-mechanism-selector selector="DIGEST-MD5" /> <set-user-name name="admin" /> <credentials> <clear-password password="password123!" /> </credentials> <providers> <use-service-loader /> </providers> </configuration> </authentication-configurations> </authentication-client> <jboss-ejb-client xmlns="urn:jboss:wildfly-client-ejb:3.0"> <connections> <connection uri="remote+http://127.0.0.1:8080" /> </connections> </jboss-ejb-client> </configuration>
- Create a custom remoting connector on the domain or standalone server that 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
Run the management CLI:
Execute the
jboss-cli.sh
orjboss-cli.bat
script and connect to the server.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()
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 fileEAP_HOME/domain/configuration/myfile.properties
. These files need to have read and write access for the file owner.$ chmod 600 myfile.properties
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.NoteThe properties file will not be created by the included
add-user.sh
andadd-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.
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
-
Run the
add-user
script. Open a terminal and change directories to theEAP_HOME/bin/
directory. If you are on Red Hat Enterprise Linux or any other UNIX-like operating system, runadd-user.sh
. If you are on Windows Server, runadd-user.bat
. -
Choose whether to add a management user or application user. For this procedure, type
b
to add an application user. -
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. -
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 typeno
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
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.
Red Hat recommends that SSLv2, SSLv3, and TLSv1.0 be explicitly disabled in favor of TLSv1.1 or TLSv1.2 in all affected packages.
6.5. Elytron Integration with the EJB Subsystem
Starting with JBoss EAP 7.1, it is now possible to map deployments so that their security is handled by the elytron
subsystem. If a deployment references a mapped security domain, its security will be handled by Elytron, otherwise its security will be handled by the legacy security subsystem. This mapping is defined in the ejb
subsystem.
Within the ejb
subsystem, mappings are created from a security domain name, as referenced within a deployment, to a referenced Elytron security-domain. When a mapped security domain name is configured for a bean in a deployment, this indicates that security should be handled by Elytron. New EJB security interceptors are set up instead of the existing ones.
The new EJB security interceptors make use of the Elytron SecurityDomain
associated with the invocation to obtain the current SecurityIdentity
and perform the following tasks:
-
Establish the
run-as
principal. -
Create any extra roles for the
run-as
principal. -
Create the
run-as
roles. - Make authorization decisions.
JBoss EAP 7.1 introduces a new management resource in the ejb
subsystem, application-security-domains
. The application-security-domains
element contains the application security domains that should be mapped to an Elytron security domain.
Attribute | Description |
---|---|
| This attribute refers to the name of the security domain as specified in a deployment. |
| This attribute is a reference to the Elytron security domain that should be used. |
| This attribute enables authorization using JACC. |
| This is a runtime attribute that lists all deployments currently referencing the ASD. |
You can configure the application-security-domain
in the ejb
subsystem in either of the following ways. You can use the management console, or you can use the management CLI.
6.5.1. Configure the Application Security Domain Using the Management Console
- Access the management console. For more information, see Management Console in the JBoss EAP Configuration Guide.
-
Navigate to Configuration
Subsystems EJB 3 click View. - In the Container tab, select Security Domains Mapping.
6.5.2. Configure the Application Security Domain Using the Management CLI
In the following example, MyAppSecurity
is a security domain that is referenced in the deployment and ApplicationDomain
is an Elytron security domain that has been configured in the elytron
subsystem.
/subsystem=ejb3/application-security-domain=MyAppSecurity:add(security-domain=ApplicationDomain)
The following XML is added to the ejb
subsystem of the server configuration file as a result of this command.
<application-security-domains> <application-security-domain name="MyAppSecurity" security-domain="ApplicationDomain"/> </application-security-domains>
See the ejb-security
quickstart that ships with JBoss EAP for a simple working example of an EJB that uses Elytron to handle security.