ejb-security-context-propagation: Demonstrate security context propagation in EJB to remote EJB calls

The ejb-security-context-propagation quickstart demonstrates how the security context can be propagated to a remote EJB using a remote outbound connection configuration

What is it?

The ejb-security-context-propagation quickstart demonstrates how the security context of an EJB can be propagated to a remote EJB in WildFly Application Server.

The quickstart makes use of two EJBs, SecuredEJB and IntermediateEJB, to verify that the security context propagation is correct, and a RemoteClient standalone client.

SecuredEJB

The SecuredEJB has four methods.

String getSecurityInformation();
String guestMethod();
String userMethod();
String adminMethod();

The getSecurityInformation() method can be called by all users that are created in this quickstart. The purpose of this method is to return a String containing the name of the Principal that called the EJB, along with the user’s authorized role information, for example:

[Principal=[quickstartUser], In role [guest]=true, In role [user]=true, In role [admin]=false]

The guestMethod(), userMethod(), and adminMethod()` methods are annotated to require that the calling user is authorized for roles guest, user and admin respectively.

IntermediateEJB: The IntermediateEJB contains a single method. Its purpose is to make use of a remote connection and invoke each of the methods on the SecuredEJB. A summary is then returned with the outcome of the calls.

RemoteClient: Finally there is the RemoteClient stand-alone client. The client makes calls using the identity of the established connection.

In the real world, remote calls between servers in the servers-to-server scenario would truly be remote and separate. For the purpose of this quickstart, we make use of a loopback connection to the same server so we do not need two servers just to run the test.

Browse the source

System Requirements

The application this project produces is designed to be run on WildFly Application Server 32 or later.

All you need to build this project is Java 11.0 (Java SDK 11) or later and Maven 3.6.0 or later. See Configure Maven to Build and Deploy the Quickstarts to make sure you are configured correctly for testing the quickstarts.

Use of the WILDFLY_HOME and QUICKSTART_HOME Variables

In the following instructions, replace WILDFLY_HOME with the actual path to your WildFly installation. The installation path is described in detail here: Use of WILDFLY_HOME and JBOSS_HOME Variables.

When you see the replaceable variable QUICKSTART_HOME, replace it with the path to the root directory of all of the quickstarts.

Prerequisites

This quickstart uses the default standalone configuration plus the modifications described here.

It is recommended that you test this approach in a separate and clean environment before you attempt to port the changes in your own environment.

Add the Authorized Application and Management Users

This quickstart uses secured management interfaces and requires that you create the following application user to access the running application.

UserName	Realm	Password	Roles
quickstartUser	ApplicationRealm	quickstartPwd1!	guest,user
quickstartAdmin	ManagementRealm	adminPwd1!	guest,user,admin

UserName

Realm

Password

Roles

quickstartUser

ApplicationRealm

quickstartPwd1!

guest,user

quickstartAdmin

ManagementRealm

adminPwd1!

guest,user,admin

To add the application user, open a terminal and type the following command:

$ WILDFLY_HOME/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest,user'
$ WILDFLY_HOME/bin/add-user.sh -a -u 'quickstartAdmin' -p 'adminPwd1!' -g 'guest,user,admin'

Note	For Windows, use the `WILDFLY_HOME\bin\add-user.bat` script.

Back Up the WildFly Standalone Server Configuration

Before you begin, back up your server configuration file.

If it is running, stop the WildFly server.
Back up the WILDFLY_HOME/standalone/configuration/standalone.xml file.

After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration.

Start the WildFly Standalone Server

Open a terminal and navigate to the root of the WildFly directory.
Start the WildFly server with the default profile by typing the following command.
```
$ WILDFLY_HOME/bin/standalone.sh 
```
Note
For Windows, use the WILDFLY_HOME\bin\standalone.bat script.

Configure the Server

You configure the security domain by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a configure-elytron.cli script provided in the root directory of this quickstart.

Before you begin, make sure you do the following:
- Back up the WildFly standalone server configuration as described above.
- Start the WildFly server with the standalone default profile as described above.
Review the configure-elytron.cli file in the root of this quickstart directory. This script adds the configuration that enables security for the quickstart deployment. Comments in the script describe the purpose of each block of commands.
Open a new terminal, navigate to the root directory of this quickstart, and run the following command, replacing WILDFLY_HOME with the path to your server:
```
$ WILDFLY_HOME/bin/jboss-cli.sh --connect --file=configure-elytron.cli
```
Note
For Windows, use the WILDFLY_HOME\bin\jboss-cli.bat script.
Because this example quickstart demonstrates security, system exceptions are thrown when secured EJB access is attempted by an invalid user. If you want to review the security exceptions in the server log, you can skip this step. If you want to suppress these exceptions in the server log, run the following command, replacing WILDFLY_HOME with the path to your server:
```
$ WILDFLY_HOME/bin/jboss-cli.sh --connect --file=configure-system-exception.cli
```
Note
For Windows,use the WILDFLY_HOME\bin\jboss-cli.bat script.

You should see the following result when you run the script:
```
The batch executed successfully
```
Stop the WildFly server.

Review the Modified Server Configuration

After stopping the server, open the WILDFLY_HOME/standalone/configuration/standalone.xml file and review the changes.

The following application-security-domain was added to the ejb3 subsystem:
```
<application-security-domains>
    <application-security-domain name="quickstart-domain" security-domain="ApplicationDomain"/>
</application-security-domains>
```
The application-security-domain enables security for the quickstart EJBs. It maps the quickstart-domain security domain that is set in the EJBs using the Java annotation @SecurityDomain("quickstart-domain") to the Elytron ApplicationDomain that is responsible for authenticating and authorizing access to the EJBs.
The following ejb-outbound-configuration authentication configuration and ejb-outbound-context authentication context were added to the elytron subsystem:
```
<authentication-configuration name="ejb-outbound-configuration" security-domain="ApplicationDomain" sasl-mechanism-selector="PLAIN"/>
<authentication-context name="ejb-outbound-context">
    <match-rule authentication-configuration="ejb-outbound-configuration"/>
</authentication-context>
```
The ejb-outbound-configuration contains the authentication configuration that will be used when invoking a method on a remote EJB, for example when IntermediateEJB calls the methods on the SecuredEJB. The above configuration specifies that the identity that is currently authenticated to the ApplicationDomain will be used to establish the connection to the remote EJB. The sasl-mechanism-selector defines the SASL mechanisms that should be tried. In this quickstart the PLAIN mechanism has been chosen because other challenge-response mechanisms such as DIGEST-MD5 can’t provide the original credential to establish the connection to the remote EJB.

The ejb-outbound-context is the authentication context that is used by the remote outbound connection and it automatically selects the ejb-outbound-configuration.
The following ejb-outbound outbound-socket-binding connection was created within the standard-sockets socket-binding-group:
```
<outbound-socket-binding name="ejb-outbound">
    <remote-destination host="localhost" port="8080"/>
</outbound-socket-binding>
```
For the purpose of the quickstart we just need an outbound connection that loops back to the same server. This will be sufficient to demonstrate the server-to-server capabilities.

The following ejb-outbound-connection remote-outbound-connection was added to the outbound-connections within the remoting subsytem:

<outbound-connections>
    <remote-outbound-connection name="ejb-outbound-connection" outbound-socket-binding-ref="ejb-outbound" authentication-context="ejb-outbound-context"/>
</outbound-connections>

Finally, the application-sasl-authentication factory was updated in the elytron subsystem to include the PLAIN mechanism:

<sasl-authentication-factory name="application-sasl-authentication" sasl-server-factory="configured" security-domain="ApplicationDomain">
    <mechanism-configuration>
        <mechanism mechanism-name="PLAIN"/>
        <mechanism mechanism-name="JBOSS-LOCAL-USER" realm-mapper="local"/>
        <mechanism mechanism-name="DIGEST-MD5">
            <mechanism-realm realm-name="ApplicationRealm"/>
        </mechanism>
    </mechanism-configuration>
</sasl-authentication-factory>

Note that the http-connector in the remoting subsystem uses this application-sasl-authentication authentication factory. It allows for the identity that was established in the connection authentication to be propagated to the components.

If you ran the script to suppress system exceptions, you should see the following configuration in the ejb3 subsystem.
```
<log-system-exceptions value="false"/>
```

Build and Deploy the Quickstart

Make sure WildFly server is started.
Open a terminal and navigate to the root directory of this quickstart.
Type the following command to build the quickstart.
```
$ mvn clean install
```
Type the following command to deploy the quickstart.
```
$ mvn wildfly:deploy
```

This deploys the ejb-security-context-propagation/target/ejb-security-context-propagation.jar to the running instance of the server.

You should see a message in the server log indicating that the archive deployed successfully.

Run the Integration Tests

This quickstart includes integration tests, which are located under the src/test/ directory. The integration tests verify that the quickstart runs correctly when deployed on the server.

Follow these steps to run the integration tests.

Make sure WildFly server is started.
Make sure the quickstart is deployed.
Type the following command to run the verify goal with the integration-testing profile activated.
```
$ mvn verify -Pintegration-testing 
```

Investigate the Console Output

When you run the integration tests, you see the following output. Note there may be other log messages interspersed between these.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* * IntermediateEJB - Begin Testing with principal quickstartUser * *

Remote Security Information: [Principal=[quickstartUser], In role [guest]=true, In role [user]=true, In role [admin]=false]
Can invoke guestMethod? true
Can invoke userMethod? true
Can invoke adminMethod? false

* * IntermediateEJB - End Testing * *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* * IntermediateEJB - Begin Testing with principal quickstartAdmin * *

Remote Security Information: [Principal=[quickstartAdmin], In role [guest]=true, In role [user]=true, In role [admin]=true]
Can invoke guestMethod? true
Can invoke userMethod? true
Can invoke adminMethod? true

* * IntermediateEJB - End Testing * *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

As can be seen from the output the identities authenticated to the intermediate EJB were propagated all the way to the remote secured EJB and their roles have been correctly evaluated.

Investigate the Server Console Output

If you did not run the script to suppress system exceptions, you should see the following exceptions in the WildFly server console or log. The exceptions are logged for each of the tests where a request is rejected because the user is not authorized.

ERROR [org.jboss.as.ejb3.invocation] (default task-57) WFLYEJB0034: EJB Invocation failed on component SecuredEJB for method public abstract java.lang.String org.jboss.as.quickstarts.ejb_security_context_propagation.SecuredEJBRemote.adminMethod(): jakarta.ejb.EJBAccessException: WFLYEJB0364: Invocation on method: public abstract java.lang.String org.jboss.as.quickstarts.ejb_security_context_propagation.SecuredEJBRemote.adminMethod() of bean: SecuredEJB is not allowed
    at org.jboss.as.ejb3.security.RolesAllowedInterceptor.processInvocation(RolesAllowedInterceptor.java:67)
    at org.jboss.invocation.InterceptorContext.proceed(InterceptorContext.java:422)
    at org.jboss.as.ejb3.security.SecurityDomainInterceptor.processInvocation(SecurityDomainInterceptor.java:44)
    at org.jboss.invocation.InterceptorContext.proceed(InterceptorContext.java:422)
    at org.jboss.as.ejb3.deployment.processors.StartupAwaitInterceptor.processInvocation(StartupAwaitInterceptor.java:22)
    at org.jboss.invocation.InterceptorContext.proceed(InterceptorContext.java:422)
    at org.jboss.as.ejb3.component.interceptors.ShutDownInterceptorFactory$1.processInvocation(ShutDownInterceptorFactory.java:64)
    at org.jboss.invocation.InterceptorContext.proceed(InterceptorContext.java:422)
    at org.jboss.as.ejb3.deployment.processors.EjbSuspendInterceptor.processInvocation(EjbSuspendInterceptor.java:57)
    at org.jboss.invocation.InterceptorContext.proceed(InterceptorContext.java:422)
    at org.jboss.as.ejb3.component.interceptors.LoggingInterceptor.processInvocation(LoggingInterceptor.java:67)
    at org.jboss.invocation.InterceptorContext.proceed(InterceptorContext.java:422)
    at org.jboss.as.ee.component.NamespaceContextInterceptor.processInvocation(NamespaceContextInterceptor.java:50)
    at org.jboss.invocation.InterceptorContext.proceed(InterceptorContext.java:422)
    at org.jboss.as.ejb3.component.interceptors.AdditionalSetupInterceptor.processInvocation(AdditionalSetupInterceptor.java:54)
    at org.jboss.invocation.InterceptorContext.proceed(InterceptorContext.java:422)
    at org.jboss.invocation.ContextClassLoaderInterceptor.processInvocation(ContextClassLoaderInterceptor.java:60)
    at org.jboss.invocation.InterceptorContext.proceed(InterceptorContext.java:422)
    at org.jboss.invocation.InterceptorContext.run(InterceptorContext.java:438)
    at org.wildfly.security.manager.WildFlySecurityManager.doChecked(WildFlySecurityManager.java:609)
    at org.jboss.invocation.AccessCheckingInterceptor.processInvocation(AccessCheckingInterceptor.java:57)
    at org.jboss.invocation.InterceptorContext.proceed(InterceptorContext.java:422)
    at org.jboss.invocation.ChainedInterceptor.processInvocation(ChainedInterceptor.java:53)
    at org.jboss.as.ee.component.ViewService$View.invoke(ViewService.java:198)
    at org.wildfly.security.auth.server.SecurityIdentity.runAsFunctionEx(SecurityIdentity.java:380)
    at org.jboss.as.ejb3.remote.AssociationImpl.invokeWithIdentity(AssociationImpl.java:492)
    at org.jboss.as.ejb3.remote.AssociationImpl.invokeMethod(AssociationImpl.java:487)
    at org.jboss.as.ejb3.remote.AssociationImpl.lambda$receiveInvocationRequest$0(AssociationImpl.java:188)
    at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1142)
    at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:617)
    at java.lang.Thread.run(Thread.java:745)

Run the Integration Tests

This quickstart includes integration tests, which are located under the src/test/ directory. The integration tests verify that the quickstart runs correctly when deployed on the server.

Follow these steps to run the integration tests.

Make sure WildFly server is started.
Make sure the quickstart is deployed.
Type the following command to run the verify goal with the integration-testing profile activated.
```
$ mvn verify -Pintegration-testing 
```

Undeploy the Quickstart

When you are finished testing the quickstart, follow these steps to undeploy the archive.

Make sure WildFly server is started.
Open a terminal and navigate to the root directory of this quickstart.
Type this command to undeploy the archive:
```
$ mvn wildfly:undeploy
```

Restore the WildFly Standalone Server Configuration

You can restore the original server configuration using either of the following methods.

You can run the restore-configuration.cli script provided in the root directory of this quickstart.
You can manually restore the configuration using the backup copy of the configuration file.

Restore the WildFly Standalone Server Configuration by Running the JBoss CLI Script

Start the WildFly server as described above.
Open a new terminal, navigate to the root directory of this quickstart, and run the following command, replacing WILDFLY_HOME with the path to your server:
```
$ WILDFLY_HOME/bin/jboss-cli.sh --connect --file=restore-configuration.cli
```
Note
For Windows, use the WILDFLY_HOME\bin\jboss-cli.bat script.

This script reverts the changes made to the ejb3, elytron and remoting subsystems. You should see the following result when you run the script.

The batch executed successfully
process-state: reload-required

Note

If you ran the script to suppress system exceptions, you need to restore the logging of system exceptions. Run the above command, passing restore-system-exception.cli instead of restore-configuration.cli for the file name. You should see the following result when you run the script.

The batch executed successfully

Restore the WildFly Standalone Server Configuration Manually

When you have completed testing the quickstart, you can restore the original server configuration by manually restoring the backup copy the configuration file.

If it is running, stop the WildFly server.
Replace the WILDFLY_HOME/standalone/configuration/standalone.xml file with the backup copy of the file.

Building and running the quickstart application with provisioned WildFly server

Instead of using a standard WildFly server distribution, you can alternatively provision a WildFly server to deploy and run the quickstart, by activating the Maven profile named provisioned-server when building the quickstart:

$ mvn clean install -Pprovisioned-server

The provisioned WildFly server, with the quickstart deployed, can then be found in the target/server directory, and its usage is similar to a standard server distribution, with the simplification that there is never the need to specify the server configuration to be started.

The quickstart user should be added before running the provisioned server:

$ target/server/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest,user'

Note	For Windows, use the `WILDFLY_HOME\bin\add-user.bat` script.

The quickstart admin should be added before running the provisioned server:

$ target/server/bin/add-user.sh -a -u 'quickstartAdmin' -p 'adminPwd1!' -g 'guest,user,admin'

Note	For Windows, use the `WILDFLY_HOME\bin\add-user.bat` script.

The server provisioning functionality is provided by the WildFly Maven Plugin, and you may find its configuration in the quickstart pom.xml:

        <profile>
            <id>provisioned-server</id>
            <build>
                <plugins>
                    <plugin>
                        <groupId>org.wildfly.plugins</groupId>
                        <artifactId>wildfly-maven-plugin</artifactId>
                        <configuration>
                            <feature-packs>
                                <feature-pack>
                                    <location>org.wildfly:wildfly-galleon-pack:${version.server}</location>
                                </feature-pack>
                            </feature-packs>
                            <layers>...</layers>
                            <!-- deploys the quickstart on root web context -->
                            <name>ROOT.war</name>
                        </configuration>
                        <executions>
                            <execution>
                                <goals>
                                    <goal>package</goal>
                                </goals>
                            </execution>
                        </executions>
                    </plugin>
                    ...
                </plugins>
            </build>
        </profile>

Note	Since the plugin configuration above deploys quickstart on root web context of the provisioned server, the URL to access the application should not have the `/ejb-security-context-propagation` path segment after `HOST:PORT`.

Run the Integration Tests with a provisioned server

The integration tests included with this quickstart, which verify that the quickstart runs correctly, may also be run with a provisioned server.

Follow these steps to run the integration tests.

Make sure the server is provisioned.

$ mvn clean install -Pprovisioned-server

Add the quickstart user:

$ target/server/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest,user'

Add the quickstart admin:

$ target/server/bin/add-user.sh -a -u 'quickstartAdmin' -p 'adminPwd1!' -g 'guest,user,admin'

For Windows, use the WILDFLY_HOME\bin\add-user.bat script.

Start the WildFly provisioned server, this time using the WildFly Maven Plugin, which is recommended for testing due to simpler automation. The path to the provisioned server should be specified using the jbossHome system property.
```
$ mvn wildfly:start -DjbossHome=target/server 
```
Type the following command to run the verify goal with the integration-testing profile activated, and specifying the quickstart’s URL using the server.host system property, which for a provisioned server by default is http://localhost:8080.
```
$ mvn verify -Pintegration-testing -Dserver.host=http://localhost:8080 
```
Shutdown the WildFly provisioned server, this time using the WildFly Maven Plugin too.
```
$ mvn wildfly:shutdown
```

WildFly for OpenShift Incompatibility

This quickstart is not compatible with WildFly for OpenShift.