1. Introduction

As of WildFly 11 a common configuration framework has been introduced for use by the client libraries to define configuration, this allows for the configuration to be shared across multiple clients rather than relying on their own configuration files. As an example the configuration used by a Jakarta Enterprise Beans client can be shared with the JBoss CLI, if both of these required SSL configuration this can now be defined once and re-used.

Programmatic APIs are also available for many of the options however this document is focusing on the configuration available within the common wildfly-config.xml configuration file.

2. wildfly-config.xml Discovery

At the time a client requires access to its configuration, the class path is scanned for a wildfly-config.xml or META-INF/wildfly-config.xml file. Once the file is located the configuration will be parsed to be made available for that client.

Alternatively, the wildfly.config.url system property can also be specified to identify the location of the configuration that should be used.

3. Configuration Sections

3.1. <authentication-client /> - WildFly Elytron

The <authentication-client/> element can be added to the wildfly-config.xml configuration to define configuration in relation to authentication configuration for outbound connections and SSL configuration for outbound connections e.g.

<?xml version="1.0" encoding="UTF-8"?>

<configuration>
    <authentication-client xmlns="urn:elytron:1.0">
       ...
    </authentication-client>
</configuration>

Note: A single wildfly-config.xml could be used by multiple projects using multiple versions of WildFly Elytron, newer versions of WildFly Elytron will introduce new configuration using later namespace versions however they will still continue to support the previously released schemas until advertised otherwise. For the configuration to be compatible with this either use a schema and namespace compatible with all the versions in use, or multiple authentication-client elements can be added, these should be added ordered by namespace youngest to oldest. If a configuration with a later namespace is discovered by a newer WildFly Elytron client it will be used and parsing will not look for an older version as well.

The <authentication-client /> configuration can contain the following sections: -

<credential-stores />

Definitions of credential stores to be referenced from elsewhere in the configuration.

<key-stores />

Definitions of KeyStores to be referenced elsewhere in the configuration.

<authentication-rules />

Rules to be applied for outbound connections to match against an appropriate authentication configuration.

<authentication-configurations />

The individual authentication configurations that will be matched by the authentication rules.

<net-authenticator />

Flag to enable integration with the [java.net.Authenticator|https://docs.oracle.com/javase/8/docs/api/java/net/Authenticator.html].

<ssl-context-rules />

Rules to be applied for outbound connections to match against an appropriate SSL context configuration.

<ssl-contexts />

Individual SSL context definitions that will be matched by the ssl context rules.

<providers/>

Definition of how [java.security.Provider|https://docs.oracle.com/javase/8/docs/api/java/security/Provider.html] instances will be discovered.

3.1.1. <credential-stores />

The <credential-stores /> element can be used to define individual named credential stores that can subsequently be used elsewhere in the configuration to reference stored credentials as an alternative to the credentials being embedded in the configuration.

<?xml version="1.0" encoding="UTF-8"?>

<configuration>
    <authentication-client xmlns="urn:elytron:1.0">
        <credential-stores>
            <credential-store name="..." type="..." provider="..." >
                <attributes>
                    <attribute name="..." value="..." />
                </attributes>
                <protection-parameter-credentials>...</protection-parameter-credentials>
            </credential-store>
        </credential-stores>
    </authentication-client>
</configuration>

In addition to the name an individual <credential-store /> definition can contain the following optional attributes: -

type

The type of the credential store, e.g.KeyStoreCredentialStore.

provider

The name of the [java.security.Provider|https://docs.oracle.com/javase/8/docs/api/java/security/Provider.html] to use to load the credential store.

The following child elements can also be added to configure the credential store.

<attributes .>

Definition of configuration attributes used to initialise the credential store.

e.g.

<attributes>
    <attribute name="..." value="..." />
</attributes>

The <attribute/> element can be repeated as many times as is required for the configuration.

<protection-parameter-credentials />

One or more credentials to be assembled into a protection parameter when initialising the credential store.

The <protection-paramter-credentials /> element can contain one more more child elements, which of these are actually supported will depend on the credential store implementation: -

<protection-parameter-credentials>
    <key-store-reference>...</key-store-reference>
    <credential-store-reference store="..." alias="..." clear-text="..." />
    <clear-password password="..." />
    <masked-password algorithm="..." key-material="..." iteration-count="..." salt="..." masked-password="..." initialization-vector="..." />
    <key-pair>
        <public-key-pem>...</public-key-pem>
        <private-key-pem>...</public-key-pem>
        <openssh-private-key pem="...">
            <credential-store-reference store="..." alias="..." clear-text="..." />
            <clear-password password="..." />
            <masked-password algorithm="..." key-material="..." iteration-count="..." salt="..." masked-password="..." initialization-vector="..." />
        </openssh-private-key>
    </key-pair>
    <certificate private-key-pem="..." pem="..." />
    <public-key-pem>...</public-key-pem>
    <bearer-token value="..." />
    <oauth2-bearer-token token-endpoint-uri="...">...</oauth2-bearer-token>
</protection-parameter-credentials>

The potential child elements of <protection-parameter-credentials /> are: -

<key-store-reference>

Defines a reference to an entry within a KeyStore for an entry to use.

The overall structure of this element is: -

<key-store-reference key-store-name="..." alias="...">
   <key-store-clear-password password="..." />
   <key-store-masked-password algorithm="..." key-material="..." iteration-count="..." salt="..." masked-password="..." initialization-vector="..." />
   <credential-store-reference store="..." alias="..." clear-text="..." />
   <key-store-credential>...</key-store-credential>
</key-store-reference>

This structure is identical to the structure use in [<key-store-credential />|#key-store-credential].

<credential-store-reference store="…​" alias="…​" clear-text="…​" />

Reference to a credential stored in a credential store.

<clear-password password="…​" />

A password specified in the clear.

<masked-password algorithm="…​" key-material="…​" iteration-count="…​" salt="…​" masked-password="…​" initialization-vector="…​" />

A masked password.

<key-pair public-key-pem="…​" private-key-pem="…​" />

A public and private key pair.

* <certificate private-key-pem="…​" pem="…​" />

A pem encoded private key and corresponding certificate.

<public-key-pem>…​</public-key-pem>

A pem encoded public key.

* <bearer-token value="…​" />

A bearer token

<oauth2-bearer-token>…​</oauth2-bearer-token>

An oath2 bearer token.

The full structure of this element is: -

<oauth2-bearer-token token-endpoint-uri="...">
    <client-credentials client-id="..." client-secret="..." />
    <masked-client-credentials client-id="...">
        <masked-client-secret algorithm="..." key-material="..." iteration-count="..." salt="..." masked-password="..." initialization-vector="..." />
    </masked-client-credentials>
    <resource-owner-credentials name="..." password="..." />
    <masked-resource-owner-credentials name="...">
            <masked-password algorithm="..." key-material="..." iteration-count="..." salt="..." masked-password="..." initialization-vector="..." />
    </masked-resource-owner-credentials >
</oauth2-bearer-token>

3.1.2. <key-stores />

The <key-stores /> element can be used to define individual key-store definitions that can subsequently be referenced from alternative locations within the configuration.

<?xml version="1.0" encoding="UTF-8"?>

<configuration>
    <authentication-client xmlns="urn:elytron:1.0">
        <key-stores>
            <key-store name="...">
               <!-- One of the following to specify where to load the KeyStore from. -->
               <file-name name="..." />
               <load-from uri-"..." />
               <resource name="..." />
               <!-- One of the following to specify the protection parameter to unlock the KeyStore. -->
               <key-store-clear-password password="..." />
               <key-store-masked-password algorithm="..." key-material="..." iteration-count="..." salt="..." masked-password="..." initialization-vector="..." />
               <key-store-credential>...</key-store-credential>
            </key-store>
        </key-stores>
       ...
    </authentication-client>
</configuration>

An individual <key-store /> definition must contain exactly one of the following elements to define where to load the store from.

<file name="…​" />*

Load from file where 'name' is the name of the file.

<load-from uri="…​" />

Load the file from the URI specified.

<resource name="…​" />

Load as a resource from the Thread context classloader where 'name' is the name of the resource to load.

Exactly one of the following elements must also be present to specify the protection parameter for initialisation of the KeyStore.

<key-store-clear-password password="…​" />

A password specified in the clear.

<key-store-masked-password algorithm="…​" key-material="…​" iteration-count="…​" salt="…​" masked-password="…​" initialization-vector="…​" />

A masked password.

<key-store-credential>…​</key-store-credential>

A reference to another KeyStore to obtain an Entry to use as the protection parameter to access this KeyStore.

The structure of the <key-store-credential /> element is:

<key-store-credential key-store-name="..." alias="...">
   <key-store-clear-password password="..." />
   <key-store-masked-password algorithm="..." key-material="..." iteration-count="..." salt="..." masked-password="..." initialization-vector="..." />
   <credential-store-reference store="..." alias="..." clear-text="..." />
   <key-store-credential>...</key-store-credential>
</key-store-credential>

This element contains two attributes: -

key-store-name

(Mandatory) - Name of the KeyStore being referenced to load the entry from.

alias

(Optional) - The alias of the entry to load from the referenced KeyStore, this can only be omitted for KeyStores that contain only a single entry.

Java KeyStores also make use of a protection parameter when accessing a single entry in addition to the protection parameter to load the KeyStore, exactly one of the following elements must be present to specify the protection parameter of the entry being loaded.

<key-store-clear-password password="…​" />

A password specified in the clear.

<key-store-masked-password algorithm="…​" key-material="…​" iteration-count="…​" salt="…​" masked-password="…​" initialization-vector="…​" />

A masked password.

<credential-store-reference store="…​" alias="…​" clear-text="…​" />

Reference to a credential stored in a credential store.

<key-store-credential>…​</key-store-credential>

A reference to another KeyStore to obtain an Entry to use as the protection parameter to access the alias.

The <key-store-credential /> is exactly the same, this means theoretically a chain of references could be used to lead to the unlocking of the required alias.

3.1.3. <authentication-rules /> and <ssl-context-rules />

When either an authentication-configuration or an ssl-context is required the URI of the resources being accessed as well as an optional abstract type and abstract type authority and matched against the rules defined in the configuration to identify which authentication-configuration or ssl-context should be used.

The rules to match <authentication-configuration /> instances are defined within the <authentication-rules /> element.

<?xml version="1.0" encoding="UTF-8"?>

<configuration>
    <authentication-client xmlns="urn:elytron:1.0">
        <authentication-rules>
            <rule use-configuration="...">
                ...
            </rule>
        </authentication-rules>
       ...
    </authentication-client>
</configuration>

The rules to match against the <ssl-context /> definitions are contains within the <ssl-context-rules /> element.

<?xml version="1.0" encoding="UTF-8"?>

<configuration>
    <authentication-client xmlns="urn:elytron:1.0">
        <ssl-context-rules>
            <rule use-ssl-context="...">
                ...
            </rule>
        </ssl-context-rules>
       ...
    </authentication-client>
</configuration>

Overall this means that authentication configuration matching is independent of SSLContext matching. By separating the rules from the configurations is means multiple rules can be defined that match against the same configuration.

The rules applied so first match wins and not most specific match wins, to achieve a most specific match wins configuration place the most specific rules at the beginning leaving the more general matches towards the end.

For both the <authentication-rules /> and the <ssl-context-rules /> the structure of the rules is identical other than one references an authentication configuration and the other references an SSLContext.

<rule use-configuration|use-ssl-context="...">
    <!-- At most one of the following two can be defined. -->
    <match-no-user />
    <match-user name="..." />
    <!-- Each of the following can be defined at most once. -->
    <match-protocol name="..." />
    <match-host name="..." />
    <match-path name="..." />
    <match-port number="..." />
    <match-urn name="..." />
    <match-domain name="..." />
    <match-abstract-type name="..." authority="..." />
</rule>

Where multiple matches are defined within a rule they must all match for the rule to apply. If a rule is defined with no match elements then it becomes a match all rule and will match anything, these can be useful at the end of the configuration to ensure something matches.

The individual match elements are: -

<match-no-user />

user-info can be embedded within a URI, this rule matches when there is no user-info. <match-user name="…​" /> - Matches when the user-info embedded in the URI matches the name specified within this element. <match-protocol name="…​" /> - Matches the protocol within the URI against the name specified in this match element. <match-host-name name="…​" /> - Matches the host name from within the URI against the name specified in this match element. <match-path name="…​" /> - Matches the path from the URI against the name specified in this match element. <match-port number="…​" /> - Matches the port number specified within the URI against the number in this match element. This only matches against the number specified within the URI and not against any default derrived from the protocol. <match-urn name="…​" />" - Matches the scheme specific part of the URI against the name specified within this element.

* <match-domain-name name="…​"/>

Matches where the protocol of the URI is 'domain' and the scheme specific part of the URI is the name specified within this match element.

<match-abstract-type name="…​" authority="…​" />

Matches the abstract type and/or authority against the values specified within this match element.

3.1.4. <authentication-configurations />

The <authentication-configurations /> element contains named configurations that can then be matched from the <authentication-rules />

<?xml version="1.0" encoding="UTF-8"?>

<configuration>
    <authentication-client xmlns="urn:elytron:1.0">
        <authentication-configurations>
            <configuration name="...">
                <!-- Destination Overrides. -->
                <set-host name="..." />
                <set-port number="..." />
                <set-protocol name="..." />
                <!-- At most one of the following two elements. -->
                <set-user-name name="..." />
                <set-anonymous />
                <set-mechanism-realm name="..." />
                <rewrite-user-name-regex pattern="..." replacement="..." />
                <sasl-mechanism-selector selector="..." />
                <set-mechanism-properties>
                   <property key="..." value="..." />
                </set-mechanism-properties>
                <credentials>...</credentials>
                <set-authorization-name name="..." />
                <providers>...</providers>
                <!-- At most one of the following two elements. -->
                <use-provider-sasl-factory />
                <use-service-loader-sasl-factory module-name="..." />
            </configuration>
        </authentication-configurations>
    </authentication-client>
</configuration>

The elements within the <configuration /> element provide the following features: -

The first three elements override the destination.

<set-host-name name="…​" />

Override the host name for the authenticated call.

<set-port-number number="…​" />

Override the port number for the authenticated call.

<set-protocol name="…​"/>

Override the protocol for the authenticated call.

The next two are mutually exclusive and can be used to set the name for authentication or switch to anonymous authentication.

<set-user-name name="…​"/>

Set the user name to use for authentication.

<set-anonymous />

Switch to anonymous authentication.

<set-mechanism-realm-name name="…​" />

Specify the name of the realm that will be selected by the SASL mechanism if required.

<rewrite-user-name-regex pattern="…​" replacement="…​" />

A regular expression pattern and replacement to re-write the user name used for authentication.

<sasl-mechanism-selector selector="…​" />

A SASL mechanism selector using the syntax from [org.wildfly.security.sasl.SaslMechanismSelector,fromString()|https://github.com/wildfly-security/wildfly-elytron/blob/1.1.4.Final/src/main/java/org/wildfly/security/sasl/SaslMechanismSelector.java#L544]

<set-mechanism-properties>…​</set-mechanism-properties>

One or more properties defined as <property key="…​" value="…​" /> to be passed to the authentication mechanisms.

<credentials>…​</credentials>

One or more credentials available for use during authentication.

The content of this element is the same as documented for [<protection-parameter-credentials />|#client-credentials-type]

<credentials>
    <key-store-reference>...</key-store-reference>
    <credential-store-reference store="..." alias="..." clear-text="..." />
    <clear-password password="..." />
    <masked-password algorithm="..." key-material="..." iteration-count="..." salt="..." masked-password="..." initialization-vector="..." />
    <key-pair>
        <public-key-pem>...</public-key-pem>
        <private-key-pem>...</public-key-pem>
        <openssh-private-key pem="...">
            <credential-store-reference store="..." alias="..." clear-text="..." />
            <clear-password password="..." />
            <masked-password algorithm="..." key-material="..." iteration-count="..." salt="..." masked-password="..." initialization-vector="..." />
        </openssh-private-key>
    </key-pair>
    <ssh-credential ssh-directory="..." private-key-file="..." known-hosts-file="...">
        <credential-store-reference store="..." alias="..." clear-text="..." />
        <clear-password password="..." />
        <masked-password algorithm="..." key-material="..." iteration-count="..." salt="..." masked-password="..." initialization-vector="..." />
    </ssh-credential>
    <certificate private-key-pem="..." pem="..." />
    <public-key-pem>...</public-key-pem>
    <bearer-token value="..." />
    <oauth2-bearer-token token-endpoint-uri="...">...</oauth2-bearer-token>
</credentials>
<set-authorization-name name="…​" />

Specify the name that should be used for authorization if different from the authentication identity.

<providers/>

This element is described in more detail within [<providers />|#Providers] and overrides the default or inherited provider discovery with a definition specific to this authentication configuration definition.

The final two elements are mutually exclusive and define how the SASL mechanism factories will be discovered for authentication.

<use-provider-sasl-factory />

The [java.security.Provider|https://docs.oracle.com/javase/8/docs/api/java/security/Provider.html] instances either inherited or defined in this configuration will be used to locate the available SASL client factories.

<use-service-loader-sasl-factory module-name="…​" />

SASL client factories will be discovered using service loader discovery on the specified module or if not specified using the ClassLoader loading the configuration.

3.1.5. <net-authenticator />

This element contains no specific configuration, however if present the [org.wildfly.security.auth.util.ElytronAuthenticator|http://wildfly-security.github.io/wildfly-elytron/1.1.x/org/wildfly/security/auth/util/ElytronAuthenticator.html] will be registered with [java.net.Authenticator.setDefault(Authenticator)|https://docs.oracle.com/javase/8/docs/api/java/net/Authenticator.html#setDefault-java.net.Authenticator-] meaning that the WildFly Elytron authentication client configuration can be used for authentication where the JDK APIs are used for HTTP calls which require authentication.

There are some limitations within this integration as the JDK will cache the authentication JVM wide from the first call so is better used in stand alone processes that don’t require different credentials for different calls to the same URI,

3.1.6. <ssl-contexts />

The <ssl-contexts /> element holds individual names SSLContext definitions that can subsequently be matched by the [<ssl-context-rules />|#Rules].

<?xml version="1.0" encoding="UTF-8"?>

<configuration>
    <authentication-client xmlns="urn:elytron:1.4">
        <ssl-contexts>
            <default-ssl-context name="..."/>
            <ssl-context name="...">
                <key-store-ssl-certificate>...</key-store-ssl-certificate>
                <trust-store key-store-name="..." />
                <cipher-suite selector="..." names="..." />
                <protocol names="... ..." />
                <provider-name name="..." />
                <providers>...</providers>
                <certificate-revocation-list path="..." maximum-cert-path="..." />
            </ssl-context>
        </ssl-contexts>
    </authentication-client>
</configuration>

The element <default-ssl-context name="…​" /> simply takes the SSLContext obtainable from [javax.net.ssl.SSLContext.getDefault()|https://docs.oracle.com/javase/8/docs/api/javax/net/ssl/SSLContext.html#getDefault--] and assigns it a name so it can referenced from the [<ssl-context-rules />|#Rules]. This element can be repeated meaning the default SSLContext can be referenced using different names.

The element <ssl-context /> is used to define a named configured SSLContext, each of the child elements is optional and can be specified at most once to build up the configuration of the SSLContext.

<key-store-ssl-certificate>

Defines a reference to an entry within a KeyStore for the key and certificate to use in this SSLContext.

The overall structure of this element is: -

<key-store-ssl-certificate key-store-name="..." alias="..." provider-name="..." algorithm="...">
   <key-store-clear-password password="..." />
   <key-store-masked-password algorithm="..." key-material="..." iteration-count="..." salt="..." masked-password="..." initialization-vector="..." />
   <credential-store-reference store="..." alias="..." clear-text="..." />
   <key-store-credential>...</key-store-credential>
</key-store-ssl-certificate>

This structure is identical to the structure use in [<key-store-credential />|#key-store-credential], but it is to obtain the entry for the key and certificate. The nested elements however remain the protection parameter to unlock the entry. In comparison with the key-store-credential the key-store-ssl-certificate allows to configure also the TrustManager: -

provider-name

- Name of the provider used to obtain the KeyManagerFactory.

algorithm

- The algorithm name of the KeyManagerFactory to obtain.

<trust-store-key-store-name />

A reference to a KeyStore that will be used to initialise the TrustManager.

<cipher-suite selector="…​" names="…​" />

Configuration to filter the enabled cipher suites. This element must contain at least one of the following two attributes: -

selector

(Optional) Used to configure the enabled cipher suites for TLSv1.2 and below. The format of the selector attribute is described in detail in org.wildfly.security.ssl.CipherSuiteSelector.fromString(selector). The default value is DEFAULT, which corresponds to all known cipher suites that do not have NULL encryption and excludes any cipher suites that have no authentication.

names

(Optional) Used to configure the enabled cipher suites for TLSv1.3. The format of the names attribute is a simple colon (":") separated list of TLSv1.3 cipher suite names (e.g., TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256). This attribute must be specified in order for TLSv1.3 to be enabled.

The following example configuration specifies that the default filtering should be used for TLSv1.2 and below and specifies that the TLS_AES_128_CCM_8_SHA256 and TLS_AES_256_GCM_SHA384 cipher suites should be used for TLSv1.3.

<cipher-suite selector="DEFAULT" names="TLS_AES_128_CCM_8_SHA256:TLS_AES_256_GCM_SHA384"/>
<protocol names="…​"/>

Used to define a space separated list of the protocols to be supported. The default value is TLSv1 TLSv1.1 TLSv1.2 TLSv1.3. Note that the TLSv1.3 protocol will only be usable when running against JDK 11 or higher.

<provider-name />

Once the available providers have been identified only the provider with the name defined on this element will be used.

<providers/>

This element is described in more detail within [<providers />|#Providers] and overrides the default or inherited provider discovery with a definition specific to this SSLContext definition.

<certificate-revocation-list />

The presence of this element enabled checking the peer’s certificate against a certificate revocation list, this element defines both a path to the certificate revocation list and also specifies the maximum number of non-self-issued intermediate certificates that may exist in a certification path

<certificate-revocation-lists />

This element enables checking the peer’s certificate against multiple certificate revocation lists. This element defines a list of certificate revocation list objects which define a path to the certificate revocation list, and also the base path of the certificate revocation list file.

The certificate-revocation-list element can be substituted by a certificate-revocation-lists element which in turn allows the configuration of multiple certificate revocation lists as follows. 
<configuration>
    <authentication-client xmlns="urn:elytron:1.4">
        <ssl-contexts>
            <default-ssl-context name="..."/>
            <ssl-context name="...">
                ...
                <certificate-revocation-lists>
                    <certificate-revocation-list path="..." relative-to="..." />
                    <certificate-revocation-list path="..." relative-to="..." />
                </certificate-revocation-lists>
            </ssl-context>
        </ssl-contexts>
    </authentication-client>
</configuration>
Configuring SSLv2Hello

Older JDK versions use SSLv2Hello during the initial SSL handshake message where the SSL/TLS version that will be used for the rest of the communication is negotiated.

Using SSLv2Hello is discouraged, therefore newer JDK versions disable this protocol on the client by default. However, they do provide the ability to re-enable it if necessary.

SSLv2Hello can be configured as a supported protocol for the SSL context as follows:

<protocol names="SSLv2Hello TLSv1">
WARNING:

  • The use of SSLv2Hello is strongly discouraged.

  • SSLv2Hello cannot be configured by itself, as its purpose is to determine which encryption protocols are supported by the server it connects to. It always needs to be configured along side another encryption protocol.

  • Additionally, IBM JDK does not support specifying SSLv2Hello in its client, although a server side connection always accepts this protocol.

3.1.7. <providers />

The <providers /> element is used to define how [java.security.Provider|https://docs.oracle.com/javase/8/docs/api/java/security/Provider.html] instances are located when required. The other configuration sections of <authentication-client /> are independent of each other, the <providers /> configuration however applies to the current element and it’s children unless overridden, this configuration can be specified in the following locations.

<?xml version="1.0" encoding="UTF-8"?>

<configuration>
    <authentication-client xmlns="urn:elytron:1.0">
        <providers />
        ...
        <credential-stores>
            <credential-store name="..">
                ...
                <providers />
            </credential-store>
        <credential-stores>
        ...
        <authentication-configurations>
            <authentication-configuration name="...">
                ...
                <providers />
            </authentication-configuration>
        </authentication-configurations>
        ...
        <ssl-contexts>
            <ssl-context name="...">
                ...
                <providers />
            </ssl-context>
        </ssl-contexts>
    </authentication-client>
</configuration>

If an individual <credential-store />, <authentication-configuration />, or <ssl-context /> contains a <providers /> definition that that definition will apply specifically to that instance. If a configured item does not contain a <providers /> definition but a top level <providers /> is defined within <authentication-configuration /> then that will be used instead.

The <providers /> element can be defined as: -

<providers>
    <global />
    <use-service-loader module-name="..." />
</providers>

Both the child elements are optional, can appear in any order and can be repeated although repeating <global /> would not really be beneficial.

<global />

The providers from [java.security.Security.getProviders()|https://docs.oracle.com/javase/8/docs/api/java/security/Security.html#getProviders--]

<credential-stores />

Providers loaded using service loader discovery from the module specified, if no module is specified the ClassLoader which loaded the authentication client is used.

Where no <provider /> configuration exists the default behaviour is the equivalent of: -

<providers>
    <use-service-loader />
    <global />
</providers>

This gives the WildFly Elytron Provider priority over any globally registered Providers but also allows for the globally registered providers to be used.

3.1.8. Masked Password Types

The authentication client supports the following masked password types:

<masked-password algorithm="..." key-material="..." iteration-count="..." salt="..." masked-password="..." initialization-vector="..." />
<key-store-masked-password algorithm="..." key-material="..." iteration-count="..." salt="..." masked-password="..." initialization-vector="..." />

<!--In oauth2-bearer-token!-->
<masked-resource-owner-credentials name="...">
        <masked-password algorithm="..." key-material="..." iteration-count="..." salt="..." masked-password="..." initialization-vector="..." />
</masked-resource-owner-credentials >
<masked-client-credentials client-id="...">
    <masked-client-secret algorithm="..." key-material="..." iteration-count="..." salt="..." masked-password="..." initialization-vector="..." />
</masked-client-credentials>

The following attributes are used to define the masked password:

algorithm

The algorithm that was used to encrypt the password. If this attribute is not specified, the default value is "masked-MD5-DES". A list of the supported algorithm types can be found in Masked Password Type

key-material

The initial key material that was used to encrypt the password. If this attribute is not specified, the default value is "somearbitrarycrazystringthatdoesnotmatter".

iteration-count

The iteration count that was used to encrypt the password. This attribute is required.

salt

The salt that was used to encrypt the password. This attribute is required.

masked-password

The base64 encrypted password (without the "MASK-" prefix). This attribute is required.

initialization-vector

The initialization vector that was used to encrypt the password. This attribute is optional.

3.2. jboss-ejb-client

The jboss-ejb-client.xml can be used to conifure EJB client from within a deployment. The file should be located in jar’s META-INF directory.

<jboss-ejb-client xmlns="urn:jboss:ejb-client:1.4">
    <client-context invocation-timeout="1000" deployment-node-selector="org.foo.DeploymentNodeSelector" default-compression="5">
        <ejb-receivers exclude-local-receiver="false" local-receiver-pass-by-value="true">
            <remoting-ejb-receiver outbound-connection-ref="connection" connection-timeout="3000"/>
        </ejb-receivers>
        <http-connections>
            <http-connection uri="http://localhost:8180/wildfly-services"/>
        </http-connections>
        <profile name="test-profile"/>
    </client-context>
</jboss-ejb-client>

3.2.1. <client-context>

Configurations that will be used to setup an EJB client context for the deployment.

  • invocation-timeout A timeout, in milliseconds, that will be used for EJB invocations. A value of zero or a negative value will imply a "wait forever" semantic where the invocation will never timeout and the client will wait for the invocation result indefinitely.

  • deployment-node-selector The fully qualified class name of the class which implements the org.jboss.ejb.client.DeploymentNodeSelector interface. The instance of this class will be used for selecting nodes, from among multiple eligible nodes within an EJB client context, which can handle a particular deployment.

  • default-compression Default compression level (from 0 to 9) of request and response message payload.

<ejb-receivers>

Configures a number of remoting based EJB receivers.

  • exclude-local-receiver Set to true if the local receiver which gets added to the EJB client context by default, has to be excluded from the context.

  • local-receiver-pass-by-value Set to false if the local receiver that’s available in the EJB client context, should use pass-by-reference (instead of pass-by-value) semantics for the EJB invocations.

<remoting-ejb-receiver>

  • outbound-connection-ref Reference to an outbound connection configured in the remoting subsystem.

  • connect-timeout The timeout, in milliseconds, to be used while creating a connection.

<http-connections>

Configures remote http-connection for EJB invocation

<http-connection>

HTTP Connection for EJB invocation.

  • uri Uniform Resource Identifier for the HTTP connection should be defined.

<profile>

References a remoting profile configured in the remoting subsystem.

  • name The name of the profile.

References in this document to Enterprise JavaBeans(EJB) refer to the Jakarta Enterprise Beans unless otherwise noted.

3.3. Remoting Client Configuration

3.3.1. <endpoint /> - Remoting Client

You can use the endpoint element, which is in the urn:jboss-remoting:5.0 namespace, to configure a JBoss Remoting client endpoint using the wildfly-config.xml file. This section describes how to configure a JBoss Remoting client using this element.

<?xml version="1.0" encoding="UTF-8"?>

<configuration>
...
    <endpoint xmlns="urn:jboss-remoting:5.0">
       ...
    </endpoint>
...
</configuration>

This section describes the child elements and attributes that can be configured within this element.

The <endpoint /> element contains the following optional attribute:

Attribute Name Attribute Description

name

The endpoint name. If not given, an endpoint name will be derived from the system’s host name, if possible.

The <endpoint /> element can optionally contain the following two child elements, as described in the next sections:

  • <providers />

  • <connections />

The configured endpoint will use the default XNIO configuration.

<providers />

This optional element specifies transport providers for the remote endpoint. It can contain any number of <provider /> sub-elements.

<provider />

This element defines a remote transport provider provider. It has the following attributes.

Attribute Name Attribute Description

scheme

The primary URI scheme which corresponds to this provider. This attribute is required.

aliases

A space-separated list of other URI scheme names that are also recognized for this provider . This attribute is optional.

module

The name of the module that contains the provider implementation. This attribute is optional; if not given, the class loader of JBoss Remoting itself will be searched for the provider class.

class

The name of the class that implements the transport provider. This attribute is optional; if not given, the Java java.util.ServiceLoader facility will be used to search for the provider class.

This element has no content.

<connections />

This optional element specifies connections for the remote endpoint. It can contain any number of [#connection] elements.

<connection />

This element defines a connection for the remote endpoint. It has the following attributes.

Attribute Name Attribute Description

destination

The destination URI for the connection. This attribute is required.

read-timeout

The timeout, in seconds, for read operations on the corresponding socket. This attribute is optional, however it should only be given if a heartbeat-interval is defined.

write-timeout

The timeout, in seconds, for a write operation. This attribute is optional, however it should only be given if a heartbeat-interval is defined..

ip-traffic-class

Defines the numeric IP traffic class to use for this connection’s traffic. This attribute is optional.

tcp-keepalive

Boolean setting that determines whether to use TCP keepalive. This attribute is optional.

heartbeat-interval

The interval, in milliseconds, to use when checking for a connection heartbeat. This attribute is optional.
Example Remoting Client Configuration in the wildfly-config.xml File
<configuration>
...
    <endpoint xmlns="urn:jboss-remoting:5.0">
        <connections>
            <connection destination="remote+http://10.20.30.40:8080" read-timeout="50" write-timeout="50" heartbeat-interval="10000"/>
        </connections>
    </endpoint>
...
</configuration>

3.4. XNIO Client Configuration

3.4.1. <worker /> - XNIO Client

You can use the worker element, which is in the urn:xnio:3.5 namespace, to configure a default XNIO worker using the wildfly-config.xml file. This section describes how to do this.

<?xml version="1.0" encoding="UTF-8"?>

<configuration>
...
    <worker xmlns="urn:xnio:3.5">
       ...
    </worker>
...
</configuration>

This section describes the child elements that can be configured within this root worker element.

The <worker /> element can optionally contain the following child elements, as described in the next sections:

  • <daemon-threads />

  • <worker-name />

  • <pool-size />

  • <task-keepalive />

  • <io-threads />

  • <stack-size />

  • <outbound-bind-addresses />

<daemon-threads />

This optional element takes a single required attribute:

Attribute Name Attribute Description

value

The value of the setting (required). A value of true indicates that worker and task threads should be daemon threads, and false indicates that they should not be daemon threads. If this element is not given, a value of true is assumed.

This element has no content.

<worker-name />

This element defines the name of the worker. The worker name will appear in thread dumps and in JMX.

Attribute Name Attribute Description

value

The worker’s name (required).

This element has no content.

<pool-size />

This optional element defines the size parameters of the worker’s task thread pool. The following attributes are allowed:

Attribute Name Attribute Description

max-threads

A positive integer which specifies the maximum number of threads that should be created (required).
<task-keepalive />

This optional element establishes the keep-alive time of task threads before they may be expired.

Attribute Name Attribute Description

value

A positive integer which represents the minimum number of seconds to keep idle threads alive (required).
<io-threads />

This optional element determines how many I/O (selector) threads should be maintained. Generally this number should be a small constant multiple of the number of available cores.

Attribute Name Attribute Description

value

A positive integer value for the number of I/O threads (required).
<stack-size />

This optional element establishes the desired minimum thread stack size for worker threads.

Attribute Name Attribute Description

value

A positive integer value which indicates the requested stack size, in bytes (required).
<outbound-bind-addresses />

This optional element specifies bind addresses to use for outbound connections. Each bind address mapping consists of a destination IP address block, and a bind address and optional port number to use for connections to destinations within that block.

<bind-address />

This element defines an individual bind address mapping.

Attribute Name Attribute Description

match

The IP address block in CIDR notation to match (required).

bind-address

The IP address to bind to if the address block matches (required).

bind-port

A specific port number to bind to if the address block matches (optional, defaults to 0 meaning "any port").

3.5. webservices-client

<webservices /> - Webservices Client

The <webservices /> element in a wildfly-config.xml file can be used to specify Web Services Client configuration that will apply during assigning of configurations when building a client. This element is from the “urn:elytron:client:1.5” namespace. Below is the example of use:

<?xml version="1.0" encoding="UTF-8"?>

<configuration>
...
    <webservices>
       ...
    </webservices>
...
</configuration>

The <webservices /> element can optionally contain the following child elements:

  • <set-http-mechanism name="BASIC"/> This element is used to specify an HTTP mechanism that WS client should use to authenticate. Currently only the HTTP Basic authentication is supported and used as default.

  • <set-ws-security-type name="UsernameToken"/> This element is used to specify WS-Security type that WS client will use to authenticate with the server. Currently only Username Token Profile can be configured.

These elements will take effect only if both username and password are configured in Elytron client.