Chapter 16. Jakarta Connectors Management

Resource adapters can be deployed just like other deployments using the management CLI or the management console. When running a standalone server, you can also copy the archive to the deployments directory to be picked up by the deployment scanner.

Deploy a Resource Adapter using the Management CLI

To deploy the resource adapter to a standalone server, enter the following management CLI command.

deploy /path/to/resource-adapter.rar

To deploy the resource adapter to all server groups in a managed domain, enter the following management CLI command.

deploy /path/to/resource-adapter.rar --all-server-groups

Deploy a Resource Adapter using the Management Console

Deploy a Resource Adapter Using the Deployment Scanner

To deploy a resource adapter manually to a standalone server, copy the resource adapter archive to the server deployments directory, for example, EAP_HOME/standalone/deployments/. This will be picked up and deployed by the deployment scanner.

You can configure resource adapters using the management interfaces. The below example shows how to configure a resource adapter using the management CLI. See your resource adapter vendor’s documentation for supported properties and other important information.

Add the Resource Adapter Configuration

Add the resource adapter configuration.

/subsystem=resource-adapters/resource-adapter=eis.rar:add(archive=eis.rar, transaction-support=XATransaction)

Configure the Resource Adapter Settings

Configure any of the following settings as necessary.

See Resource Adapter Attributes for all available configuration options for resource adapters.

Activate the Resource Adapter

Activate the resource adapter.

/subsystem=resource-adapters/resource-adapter=eis.rar:activate

Two types of communications occur between the server and the resource adapter in IronJacamar.

One of them is when the server opens a resource adapter connection. As defined by the specifications, this can be secured by container-managed sign-on, which requires propagation of a JAAS subject with principal and credentials to the resource adapter when opening the connection. This sign-on can be delegated to Elytron.

IronJacamar supports security inflow. This mechanism enables a resource adapter to establish security information when submitting a work to the work manager, and when delivering messages to endpoints residing in the same JBoss EAP instance.

Container-managed Sign-On

In order to achieve container-managed sign-on with Elytron, the elytron-enabled attribute needs to be set to true. This will result in all connections to the resource adapter to be secured by Elytron.

/subsystem=resource-adapters/resource-adapter=RAR_NAME/connection-definitions=FACTORY_NAME:write-attribute(name=elytron-enabled,value=true)

The elytron-enabled attribute can be configured using the management CLI by setting the elytron-enabled attribute, in the resource-adapters subsystems, to true. By default this attribute is set to false.

The authentication-context attribute defines the name of the Elytron authentication context that will be used for performing sign-on.

An Elytron authentication-context attribute can contain one or more authentication-configuration elements, which in turn contains the credentials you want to use.

If the authentication-context attribute is not set, JBoss EAP will use the current authentication-context, which is the authentication-context used by the caller code that is opening the connection.

/subsystem=elytron/authentication-configuration=exampleAuthConfig:add(authentication-name=sa,credential-reference={clear-text=sa})

/subsystem=elytron/authentication-context=exampleAuthContext:add(match-rules=[{authentication-configuration=exampleAuthConfig}])

Security Inflow

It is also possible for the resource manager to inflow security credentials when submitting the work which is to be executed by the work manager. Security inflow allows the work to authenticate itself before execution. If authentication succeeds, the submitted work will be executed under the resulting authentication context. If it fails, the work execution will be rejected.

To enable Elytron security inflow, set the wm-elytron-security-domain attribute when configuring the resource adapter work manager. Elytron will perform the authentication based on the specified domain.

/subsystem=jca/workmanager=customWM:add(name=customWM, elytron-enabled=true)

In the example configuration of jca subsystem below, we can see the configuration of a resource adapter called ra-with-elytron-security-domain. This resource adapter configures work manager security to use the Elytron security domain’s wm-realm.

<subsystem xmlns="urn:jboss:domain:jca:5.0">
    <archive-validation enabled="true" fail-on-error="true" fail-on-warn="false"/>
    <bean-validation enabled="true"/>
    <default-workmanager>
        <short-running-threads>
            <core-threads count="50"/>
            <queue-length count="50"/>
            <max-threads count="50"/>
            <keepalive-time time="10" unit="seconds"/>
        </short-running-threads>
        <long-running-threads>
            <core-threads count="50"/>
            <queue-length count="50"/>
            <max-threads count="50"/>
            <keepalive-time time="10" unit="seconds"/>
        </long-running-threads>
    </default-workmanager>
    <workmanager name="customWM">
        <elytron-enabled>true</elytron-enabled>
        <short-running-threads>
            <core-threads count="20"/>
            <queue-length count="20"/>
            <max-threads count="20"/>
        </short-running-threads>
    </workmanager>
    <bootstrap-contexts>
        <bootstrap-context name="customContext" workmanager="customWM"/>
    </bootstrap-contexts>
    <cached-connection-manager/>
</subsystem>

The work manager is then referenced using the boostrap context from the resource-adapter subsystem.

<subsystem xmlns="urn:jboss:domain:resource-adapters:5.0">
    <resource-adapters>
        <resource-adapter id="ra-with-elytron-security-domain">
            <archive>
                ra-with-elytron-security-domain.rar
            </archive>
            <bootstrap-context>customContext</bootstrap-context>
            <transaction-support>NoTransaction</transaction-support>
            <workmanager>
                <security>
                    <elytron-security-domain>wm-realm</elytron-security-domain>
                    <default-principal>wm-default-principal</default-principal>
                    <default-groups>
                        <group>
                            wm-default-group
                        </group>
                    </default-groups>
                </security>
            </workmanager>
        </resource-adapter>
    </resource-adapters>
</subsystem>

/subsystem=elytron/properties-realm=wm-properties-realm:add(users-properties={path=/security-dir/users.properties, plain-text=true}, groups-properties={path=/security-dir/groups.properties})

/subsystem=elytron/simple-role-decoder=wm-role-decoder:add(attribute=groups)

/subsystem=elytron/constant-permission-mapper=wm-permission-mapper:add(permissions=[{class-name="org.wildfly.security.auth.permission.LoginPermission"}])

/subsystem=elytron/security-domain=wm-realm:add(default-realm=wm-properties-realm, permission-mapper=wm-permission-mapper, realms=[{role-decoder=wm-role-decoder, realm=wm-properties-realm}])

The Work class is responsible for providing the credentials for Elytron’s authentication under the specified domain. For that, it must implement javax.resource.spi.work.WorkContextProvider.

public interface WorkContextProvider {
   /**
    * Gets an instance of <code>WorkContexts</code> that needs to be used
    * by the <code>WorkManager</code> to set up the execution context while
    * executing a <code>Work</code> instance.
    *
    * @return an <code>List</code> of <code>WorkContext</code> instances.
    */
   List<WorkContext> getWorkContexts();
}

This interface allows the Work class to use the WorkContext to configure some aspects of the context in which the work will be executed. One of those aspects is the security inflow. For that, the List<WorkContext> getWorkContexts method must provide a javax.resource.spi.work.SecurityContext. This context will use javax.security.auth.callback.Callback objects as defined by Jakarta Authentication. For more information about the specification, see Jakarta Authentication specification.

public class ExampleWork implements Work, WorkContextProvider {

    private final String username;
    private final String role;

    public MyWork(TestBean bean, String username, String role) {
        this.principals = null;
        this.roles = null;
        this.bean = bean;
        this.username = username;
        this.role = role;
    }

    public List<WorkContext> getWorkContexts() {
        List<WorkContext> l = new ArrayList<>(1);
        l.add(new MySecurityContext(username, role));
        return l;
    }

    public void run() {
        ...
    }

    public void release() {
        ...
    }

    public class ExampleSecurityContext extends SecurityContext {

        public void setupSecurityContext(CallbackHandler handler, Subject executionSubject, Subject serviceSubject) {
            try {
                List<javax.security.auth.callback.Callback> cbs = new ArrayList<>();
                cbs.add(new CallerPrincipalCallback(executionSubject, new SimplePrincipal(username)));
                cbs.add(new GroupPrincipalCallback(executionSubject, new String[]{role}));
                handler.handle(cbs.toArray(new javax.security.auth.callback.Callback[cbs.size()]));
            } catch (Throwable t) {
                throw new RuntimeException(t);
            }
        }
    }

In the above example, ExampleWork implements the WorkContextProvider interface to provide ExampleSecurityContext. That context will create the callbacks necessary to provide the security information that will be authenticated by Elytron upon work execution.

You can find the instructions for deploying the IBM MQ resource adapter in Configuring Messaging for JBoss EAP.

You can find the instructions for configuring the generic Jakarta Messaging resource adapter in Configuring Messaging for JBoss EAP.