WildFly Migration Guide

1. Introduction

Since the initial development of JBoss AS7 the features added to WildFly have been continuing to increase, some of the older features are now being removed to make way for new features. This guide contains information about the removed features and their alternatives.

2. PicketBox Vault

WildFly Elytron has made available a new credential store which replaces the PicketBox vault. The credential store can be used for credentials to be directly looked up for use by resources or it can be used to store a SecretKey which can be used by an expression resolver to decrypt previously encrypted expressions in the management model.

2.1. Credential Store Creation

Before credentials can be added a new credential store needs to be created.

2.1.1. From the command line

The first option is to use the Elytron command line utility to create a new store.

bin/elytron-tool.sh credential-store --create \
    --location=standalone/configuration/credentials.store
Credential store password:
Confirm credential store password:
Credential Store has been successfully created

The creation process prompts for a password for the store twice and automatically creates the store.

2.1.2. Defining the credential store in the management model

This newly created credential store can be added to the management model of a running server.

/subsystem=elytron/credential-store=mystore:add( \
    relative-to=jboss.server.config.dir, \
    location=credentials.store, \
    credential-reference={clear-text=cs_password})
{"outcome" => "success"}

Instead of using the clear text password it is also possible to obfuscate the password using the mask command in the command line tool.

bin/elytron-tool.sh mask --secret=cs_password --salt=12345678 --iteration=256
MASK-0BjKFw41KSAGZr/OtiZNI1;12345678;256

The credential store resource can then be defined as.

/subsystem=elytron/credential-store=mystore:add( \
    relative-to=jboss.server.config.dir, \
    location=credentials.store, \
    credential-reference={clear-text=MASK-0BjKFw41KSAGZr/OtiZNI1;12345678;256})
{"outcome" => "success"}

2.1.3. Automatically creating the store

If the credential store file did not already exist, with a small change to the add operation the store will be automatically created for you.

/subsystem=elytron/credential-store=mystore:add( \
    relative-to=jboss.server.config.dir,
    location=credentials.store,
    credential-reference={clear-text=cs_password}, \
    create=true)
{"outcome" => "success"}

2.2. Adding Credentials

However the store was created credentials can be added using either the command line utility or a management operation. If using the command line utility it is recommended that this is performed when no running server is using the store to prevent accidental overwrites.

2.2.1. From the command line

The following command will add a new entry to the store under the alias example.

bin/elytron-tool.sh credential-store --add=example \
    --location=standalone/configuration/credentials.store
Credential store password:
Secret to store:
Confirm secret to store:
Alias "example" has been successfully stored

This command prompts for the credential store password once followed by promting for the secret to store twice.

2.2.2. Using a management operation

The following management operation can add an entry to the credential store:

history --disable
/subsystem=elytron/credential-store=mystore:add-alias(alias=example, \
    secret-value=example_password)
{"outcome" => "success"}
history --enable

In this example the CLI history is temporarily disabled to prevent the password being stored in the history file.

2.3. Listing credential store contents

The command line tool and management operations can both be used to list the contents of the credential store.

2.3.1. From the command line

The aliases in the credential store can be listed with the following command:

bin/elytron-tool.sh credential-store --aliases \
    --location=standalone/configuration/credentials.store
Credential store password:
Credential store contains following aliases: example

2.3.2. Using a management operation

The read-aliases management operation can be used with a credential store to list the aliases it contains.

/subsystem=elytron/credential-store=mystore:read-aliases
{
    "outcome" => "success",
    "result" => ["example"]
}

2.4. Vault Conversion

The WildFly Elytron tool can also be used to convert an existing vault to a credential store.

bin/elytron-tool.sh vault --enc-dir standalone/configuration/vault \
    --keystore standalone/configuration/vault.keystore \
    --location standalone/configuration/converted.store
Vault password:
Confirm vault password:
Vault (enc-dir="standalone/configuration/vault";keystore="standalone/configuration/vault.keystore") \
    converted to credential store "standalone/configuration/converted.store"

This will convert all of the contents of the vault to a new credential store. Vault entries were identified using a BLOCK and a NAME, the resulting alias in the credential store will be in the format BLOCK::NAME.

2.5. Referencing a credential store credential

Resources in the management model which can reference credentials from the credential store use a credential-reference attribute, in defining the credential store previously this was used with a clear-password but it can also be used to reference an alias stored within a credential store.

The following managment operation demonstrates defining a new key-store resource using a credential store entry for the password.

/subsystem=elytron/key-store=test-store:add( \
    relative-to=jboss.server.config.dir, \
    path=test.keystore, required=false, \
    credential-reference={store=mystore, alias=example})
{"outcome" => "success"}

2.6. Encrypted Expressions

In addition to using direct references to credentials it is also possible to use a SecretKey to handle previously encrypted expressions directly within the management model.

2.6.1. Adding a `SecretKey` to a credential store

Before encrypted expressions can be used an AES SecretKey is required. The previous vault password making made use of a well known password for obfuscating, by using a SecretKey instead users can manage their own key.

From the command line

A SecretKey can be added to the credential store with the following command:

bin/elytron-tool.sh credential-store --generate-secret-key=key \
    --location standalone/configuration/credentials.store
Credential store password:
Alias "key" has been successfully stored

Using a management operation

The following management operation can also add a dynamically generated SecretKey:

/subsystem=elytron/credential-store=mystore:generate-secret-key(alias=key)
{"outcome" => "success"}

2.6.2. Using a `secret-key-credential-store`

Alternatively it may be desirable to manage a SecretKey which is not itself password protected. An alternative resource is available for this:

/subsystem=elytron/secret-key-credential-store=secret-key-store:add( \
    relative-to=jboss.server.config.dir, path=secret-key.store)
{"outcome" => "success"}

This command will have also populated the new store with a SecretKey under the alias key.

2.6.3. Adding the expression resolver resource

A new resource can be added to the elytron subsystem which is responsible for handling encrypted expressions.

/subsystem=elytron/expression=encryption:add( \
    resolvers=[{name=default, \
                credential-store=secret-key-store, \
                secret-key=key}], \
    default-resolver=default)
{"outcome" => "success"}

2.6.4. Creating an expression

The easiest way to create an encrupted expression is using a management operation as the result takes into account the configured expression=encryption resource.

history --disable
/subsystem=elytron/expression=encryption:create-expression(clear-text=my_password)
{
    "outcome" => "success",
    "result" => {"expression" => "${ENC::RUxZAUMQ5Z7mXbyrCtv2kZlwHHpyJ//ma49gMAUnbmTfv2pGs30=}"}
}

history --enable

The resulting expression ${ENC::RUxZAUMQ5Z7mXbyrCtv2kZlwHHpyJ//ma49gMAUnbmTfv2pGs30=} can now be used as the value for any other attribute in the management model which supports expressions.

2.7. Further Reading

The WildFly Elytron Security guide contains further information regarding Credential Stores and Encrypted Expressions.