The configuration file approach involves creating an XML file with your authentication configuration, authentication context, and match rules.

<configuration>
    <authentication-client xmlns="urn:elytron:1.0.1">
        <authentication-rules>
            <rule use-configuration="monitor">
                <match-host name="127.0.0.1" />
            </rule>
            <rule use-configuration="administrator">
                <match-host name="localhost" />
            </rule>
        </authentication-rules>
        <authentication-configurations>
            <configuration name="monitor">
                <sasl-mechanism-selector selector="DIGEST-MD5" />
                <providers>
                  <use-service-loader />
                </providers>
                <set-user-name name="monitor" />
                <credentials>
                    <clear-password password="password1!" />
                </credentials>
                <set-mechanism-realm name="ManagementRealm" />
             </configuration>

             <configuration name="administrator">
                <sasl-mechanism-selector selector="DIGEST-MD5" />
                <providers>
                  <use-service-loader />
                </providers>
                <set-user-name name="administrator" />
                <credentials>
                    <clear-password password="password1!" />
                </credentials>
                <set-mechanism-realm name="ManagementRealm" />
             </configuration>
        </authentication-configurations>
    </authentication-client>
</configuration>

You can then reference that file in your client’s code by setting a system property when running your client.

$ java -Dwildfly.config.url=/path/to/custom-config.xml ...

When creating rules, you can look for matches on various parameters, such as hostname, port, protocol, or user-name. A full list of options for MatchRule are available in the Javadocs. Rules are evaluated in the order in which they are configured.

When no match settings are included in a rule, then the whole rule matches and the authentication configuration is chosen. If more than one match setting is included in a rule, then all must match for the authentication configuration to be chosen.

An example wildfly-config.xml file can be found in Example wildfly-config.xml. For more information about how to configure the wildfly-config.xml file, see Client Configuration Using the wildfly-config.xml File in the Development Guide for JBoss EAP.

The programmatic approach configures all Elytron Client configuration in the client’s code:

//create your authentication configuration
AuthenticationConfiguration adminConfig =
    AuthenticationConfiguration.empty()
      .useProviders(() -> new Provider[] { new WildFlyElytronProvider() })
      .setSaslMechanismSelector(SaslMechanismSelector.NONE.addMechanism("DIGEST-MD5"))
      .useRealm("ManagementRealm")
      .useName("administrator")
      .usePassword("password1!");

//create your authentication context
AuthenticationContext context = AuthenticationContext.empty();
context = context.with(MatchRule.ALL.matchHost("127.0.0.1"), adminConfig);


//create your runnable for establishing a connection
Runnable runnable =
    new Runnable() {
      public void run() {
        try {
           //Establish your connection and do some work
        } catch (Exception e) {
          e.printStackTrace();
        }
      }
    };

//use your authentication context to run your client
context.run(runnable);

When adding configuration details to AuthenticationConfiguration and AuthenticationContext, each method call returns a new instance of that object. For example, if you wanted separate configurations when connecting over different hostnames, you could do the following:

//create your authentication configuration
AuthenticationConfiguration commonConfig =
    AuthenticationConfiguration.empty()
      .useProviders(() -> new Provider[] { new WildFlyElytronProvider() })
      .setSaslMechanismSelector(SaslMechanismSelector.NONE.addMechanism("DIGEST-MD5"))
      .useRealm("ManagementRealm");

AuthenticationConfiguration administrator =
    commonConfig
      .useName("administrator")
      .usePassword("password1!");


AuthenticationConfiguration monitor =
    commonConfig
      .useName("monitor")
      .usePassword("password1!");


//create your authentication context
AuthenticationContext context = AuthenticationContext.empty();
context = context.with(MatchRule.ALL.matchHost("127.0.0.1"), administrator);
context = context.with(MatchRule.ALL.matchHost("localhost"), monitor);

Also, instead of starting with an empty authentication configuration, you can start with the currently configured one by using captureCurrent().

//create your authentication configuration
AuthenticationConfiguration commonConfig = AuthenticationConfiguration.captureCurrent();

Using captureCurrent() will capture any previously established authentication context and use it as your new base configuration. An authentication context is established once it has been activated by calling run(). If captureCurrent() is called and no context is currently active, it will try and use the default authentication if available. You can find more details about this in the following sections:

AuthenticationConfiguration.empty() should only be used as a base to build a configuration on top of, and should not be used on its own. It provides a configuration that uses the JVM-wide registered providers and enables anonymous authentication.

When specifying the providers on top of the AuthenticationConfiguration.empty() configuration, you can specify a custom list, but most users should use WildFlyElytronProvider() providers.

When creating an authentication context, using the context.with(…​) will create a new context that merges the rules and authentication configuration from the current context with the provided rule and authentication configuration. The provided rule and authentication configuration will appear after the ones in the current context.

The default configuration approach relies completely on the configuration provided by Elytron Client:

//create your runnable for establishing a connection
Runnable runnable =
    new Runnable() {
      public void run() {
        try {
           //Establish your connection and do some work
        } catch (Exception e) {
          e.printStackTrace();
        }
      }
    };

// run runnable directly
runnable.run();

To provide a default configuration, Elytron Client tries to auto-discover a wildfly-config.xml file on the filesystem. It looks in the following locations:

You can use the following example as the basic configuration for your client wildfly-config.xml file.

<configuration>
  <authentication-client xmlns="urn:elytron:1.0.1">
    <authentication-rules>
      <rule use-configuration="default" />
    </authentication-rules>
    <authentication-configurations>
      <configuration name="default">
        <sasl-mechanism-selector selector="#ALL" />
        <set-mechanism-properties>
          <property key="wildfly.sasl.local-user.quiet-auth" value="true" />
        </set-mechanism-properties>
        <providers>
          <use-service-loader/>
        </providers>
      </configuration>
    </authentication-configurations>
  </authentication-client>
</configuration>

Clients deployed to JBoss EAP can also make use of Elytron Client. The AuthenticationContext is automatically parsed and created from the default-authentication-context setting in the JBoss EAP configuration. If the default-authentication-context is not configured, but you have a wildfly-config.xml file included with your deployment or set using the wildfly.config.url system property, the AuthenticationContext is automatically parsed and created from that file.

/subsystem=elytron/authentication-context=AUTH_CONTEXT:add
/subsystem=elytron:write-attribute(name=default-authentication-context,value=AUTH_CONTEXT)

To load a configuration file outside of the deployment, you can use the parseAuthenticationClientConfiguration(URI) method. This method returns an AuthenticationContext that you can then use in your client code using the programmatic approach.

Additionally, clients will also automatically parse and create an AuthenticationContext from the client configuration provided by the elytron subsystem. The client configuration in the elytron subsystem can also take advantage of other components defined in the elytron subsystem, such as credential stores. If the client configuration is provided by both the deployment and the elytron subsystem, the elytron subsystem’s configuration is used.

Starting in JBoss EAP 7.1, JMX clients, including JConsole, can be configured using the wildfly-config.xml file. You specify the file path to the configuration file using the -Dwildfly.config.url system property when starting the JMX client.

-Dwildfly.config.url=path/to/wildfly-config.xml

-J-Dwildfly.config.url=path/to/wildfly-config.xml

For more information, see Client Configuration Using the wildfly-config.xml File in the JBoss EAP Development Guide.

JBoss EAP 7.1 introduced the ElytronAuthenticator class, which uses the current security context to perform the authentication. The org.wildfly.security.auth.util.ElytronAuthenticator class is an implementation of java.net.Authenticator.

The following is an example of client code that creates and uses the ElytronAuthenticator class to propagate an identity to the server.

// Create the authentication configuration
AuthenticationConfiguration httpConfig = AuthenticationConfiguration.empty().useName("bob");

// Create the authentication context
AuthenticationContext context = AuthenticationContext.captureCurrent().with(MatchRule.ALL, httpConfig.usePassword(createPassword(httpConfig, "secret")));

String response = context.run((PrivilegedExceptionAction<String>) () -> {
    Authenticator.setDefault(new ElytronAuthenticator());
    HttpURLConnection connection = HttpURLConnection.class.cast(new URL("http://localhost:" + SERVER_PORT).openConnection());
    try (InputStream inputStream = connection.getInputStream()) {
        return new BufferedReader(new InputStreamReader(inputStream)).lines().findFirst().orElse(null);
    }
});