include::../shared-doc/attributes.adoc[]

= ejb-security-context-propagation: Demonstrate security context propagation in EJB to remote EJB calls
:author: Stefan Guilhen
:level: Advanced
:technologies: EJB, Security

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

:standalone-server-type: default
:archiveType: jar
:includes-cli-scripts:
:restoreScriptName: restore-configuration.cli
:app-user-groups: guest,user
:admin-user-groups: guest,user,admin

== 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 {productNameFull}.

The quickstart makes use of two EJBs, xref:secured_ejb[`SecuredEJB`] and xref:intermediate_ejb[`IntermediateEJB`], to verify that the security context propagation is correct, and a xref:remote_client[`RemoteClient`] standalone client.

[[secured_ejb]]
SecuredEJB::

The `SecuredEJB` has four methods.
+
[source,java,options="nowrap"]
----
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:
+
[source,options="nowrap"]
----
[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.

[[intermediate_ejb]]
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.

[[remote_client]]
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.

// System Requirements
include::../shared-doc/system-requirements.adoc[leveloffset=+1]
// Use of {jbossHomeName}
include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1]

== 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
include::../shared-doc/add-application-and-management-users.adoc[leveloffset=+1]
// Back Up the {productName} Standalone Server Configuration
include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+1]
//  Start the {productName} Standalone Server
include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1]

[[configure_the_server]]
== 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:

* xref:back_up_standalone_server_configuration[Back up the {productName} standalone server configuration] as described above.
* xref:start_the_eap_standalone_server[Start the {productName} 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 Elytron 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 `__{jbossHomeName}__` with the path to your server:
+
[source,subs="+quotes,attributes+",options="nowrap"]
----
$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-elytron.cli
----
+
NOTE: For Windows, use the `__{jbossHomeName}__\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 `__{jbossHomeName}__` with the path to your server:
[[suppress_system_exceptions]]
+
[source,subs="+quotes,attributes+",options="nowrap"]
----
$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-system-exception.cli
----
+
NOTE: For Windows,use the `__{jbossHomeName}__\bin\jboss-cli.bat` script.
+

You should see the following result when you run the script:
+
[source,options="nowrap"]
----
The batch executed successfully
----

. Stop the {productName} server.

== Review the Modified Server Configuration

After stopping the server, open the `__{jbossHomeName}__/standalone/configuration/standalone.xml` file and review the changes.

. The following `application-security-domain` was added to the `ejb3` subsystem:
+
[source,xml,options="nowrap"]
----
<application-security-domains>
    <application-security-domain name="quickstart-domain" security-domain="ApplicationDomain"/>
</application-security-domains>
----
+
The `application-security-domain` enables Elytron 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:
+
[source,xml,options="nowrap"]
----
<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:
+
[source,xml,options="nowrap"]
----
<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:
+
[source,xml,options="nowrap"]
----
<outbound-connections>
    <remote-outbound-connection name="ejb-outbound-connection" outbound-socket-binding-ref="ejb-outbound" authentication-context="ejb-outbound-context"/>
</outbound-connections>
----

. The `http-connector` in the `remoting` subsystem was updated to use the `application-sasl-authentication` authentication factory. It allows for the identity that was established in the connection authentication to be propagated to the components.
+
[source,xml,options="nowrap"]
----
<http-connector name="http-remoting-connector" connector-ref="default" security-realm="ApplicationRealm" sasl-authentication-factory="application-sasl-authentication"/>
----
. Finally, the `application-sasl-authentication` factory was updated in the `elytron` subsystem to include the `PLAIN` mechanism:
+
[source,xml,options="nowrap"]
----
<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>
----

. If you xref:suppress_system_exceptions[ran the script to suppress system exceptions], you should see the following configuration in the `ejb3` subsystem.
+
[source,xml,options="nowrap"]
----
<log-system-exceptions value="false"/>
----

// Build and Deploy the Quickstart JAR
include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1]

== Run the Client

Before you run the client, make sure you have already successfully deployed the EJBs to the server in the previous step and that your terminal is still in the same folder.

Type this command to execute the client:

[source,options="nowrap"]
----
$ mvn exec:exec
----

== Investigate the Console Output

When you run the `mvn exec:exec` command, you see the following output. Note there may be other log messages interspersed between these.

[source,options="nowrap"]
----
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* * 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 xref:suppress_system_exceptions[run the script to suppress system exceptions], you should see the following exceptions in the {productName}
server console or log. The exceptions are logged for each of the tests where a request is rejected because the user is not
authorized.

[source,options="nowrap"]
----
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(): javax.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)
----

// Undeploy the Quickstart
include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1]
// Restore the {productName} Standalone Server Configuration
include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+1]

// Additional information about this 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.

[source,options="nowrap"]
----
The batch executed successfully
process-state: reload-required
----

[NOTE]
====
If you xref:suppress_system_exceptions[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.

[source,options="nowrap"]
----
The batch executed successfully
----
====

// Restore the {productName} Standalone Server Configuration Manually
include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+2]
// Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse
include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1]

// Additional JBoss Developer Studio instructions
This quickstart requires additional configuration and deploys and runs differently in JBoss Developer Studio than the other quickstarts.

. Make sure you xref:add_the_application_users[Add the Application Users] as described above.
. Follow the steps above to xref:configure_the_server[Configure the Server]. Stop the server at the end of that step.
. To deploy the application to the {productName} server, right-click on the *{artifactId}* project and choose *Run As* -> *Run on Server*.
. To access the application, right-click on the *{artifactId}* project and choose *Run As* -> *Java Application*.
. Choose *RemoteClient - org.jboss.as.quickstarts.ejb_security_context_propagation* and click *OK*.
. Review the output in the console window.
. To undeploy the project, right-click on the *{artifactId}* project and choose *Run As* -> *Maven build*. Enter `wildfly:undeploy` for the *Goals* and click *Run*.
. Make sure you xref:restore_the_server_configuration[restore the server configuration] when you have completed testing this quickstart.

// Debug the Application
include::../shared-doc/debug-the-application.adoc[leveloffset=+1]
