WildFly Elytron

WildFly Elytron

Automatic Credential Store Updates

By Farah Juma | June 08, 2020
#credential-store #updates

WildFly 20 adds support for automatic credential store updates. This blog post will give an overview of this new feature.

Credential Stores

Credential stores allow credentials to be stored securely. When adding a credential to a store, it is associated with an alias. This alias is then subsequently used to reference the credential from the store instead of needing to specify the credential directly. As an example, when configuring a key-store in the Elytron subsystem, we need to specify the keystore password. Instead of specifying the password in clear text, we can first add the keystore password to a credential store and then reference the alias that we associated with that password, as shown below.

First, let’s create a credential store:

/subsystem=elytron/credential-store=myCredStore:add(location=mycredstore.cs, relative-to=jboss.server.config.dir, credential-reference={clear-text=StorePassword}, create=true)

Next, we’ll add our keystore password to this store and associate it with the alias example:

/subsystem=elytron/credential-store=myCredStore:add-alias(alias=example, secret-value=mySecretPassword)

Finally, we’ll reference our credential store and alias when configuring our key-store:

/subsystem=elytron/key-store=myKS:add(relative-to=jboss.server.config.dir, path=my.keystore, type=JCEKS, credential-reference={store=myCredStore, alias=example})

The credential-reference attribute above is used to reference a credential from a credential store. Notice that the credential-reference has two attributes, store and alias. The store attribute indicates the credential store. The alias attribute indicates the entry in the credential store that holds our credential. Besides the key-store resource, there are many other resources in the WildFly management model that allow a credential-reference to be specified.

Notice that in the above example, we first had to add our credential to the store before being able to reference it from a credential-reference.

Automatic Credential Store Updates

Instead of needing to first add a credential to a credential store, WildFly 20 adds the ability to automatically add a credential to a previously defined credential store by specifying both the store and clear-text attributes for a credential-reference. In particular, when configuring a new credential-reference with both the store and clear-text attributes specified, the following will happen:

  • If the alias attribute is also specified, one of the following will occur:

    • If the configured credential store does not contain an entry for the given alias, a new entry will be added to the credential store to hold the clear text password that was specified. The clear-text attribute will then be removed from the management model.

    • If the credential store does contain an entry for the given alias, the existing credential will be replaced with the clear text password that was specified. The clear-text attribute will then be removed from the management model.

  • If the alias attribute is not specified, an alias will be generated and a new entry will be added to the credential store to hold the clear text password that was specified. The clear-text attribute will then be removed from the management model.

We’re going to take a look at some examples in the next sections.

Automatically Adding a Credential to a Store

We’re first going to configure another key-store in the Elytron subsystem but this time we’re not going to add the keystore password to the credential store ourselves:

/subsystem=elytron/key-store=newKS1:add(relative-to=jboss.server.config.dir, path=new.keystore, type=JCEKS, credential-reference={store=myCredStore, alias=myNewAlias, clear-text=myNewPassword})
{
    "outcome" => "success",
    "result" => {"credential-store-update" => {
        "status" => "new-entry-added",
        "new-alias" => "myNewAlias"
    }}
}

Notice that the credential-reference attribute for the new key-store we are configuring specifies the store, alias, and clear-text attributes. The store attribute references the credential store that we already created. The alias attribute specified is myNewAlias and the clear-text attribute specified is myNewPassword. Since our credential store does not already contain the specified alias, the above command will result in a new entry being automatically added to our credential store, myCredStore, with alias myNewAlias and credential myNewPassword.

We can check the aliases that are in the credential store to confirm that we see the new alias there:

/subsystem=elytron/credential-store=myCredStore:read-aliases()
{
    "outcome" => "success",
    "result" => [
        "mynewalias",
        "example"
    ],
    "response-headers" => {"process-state" => "reload-required"}
}

If we take a look at our newly configured key-store, we can see that its credential-reference attribute only references the credential store and the alias, it does not reference the clear text password:

/subsystem=elytron/key-store=newKS1:read-attribute(name=credential-reference)
{
    "outcome" => "success",
    "result" => {
        "store" => "myCredStore",
        "alias" => "myNewAlias",
        "clear-text" => undefined
    },
    "response-headers" => {"process-state" => "reload-required"}
}

If we hadn’t specified the alias attribute in our credential-reference when configuring our key-store, a new alias would have been generated automatically for us:

/subsystem=elytron/key-store=newKS2:add(relative-to=jboss.server.config.dir, path=new.keystore, type=JCEKS, credential-reference={store=myCredStore, clear-text=myNewPassword})
{
    "outcome" => "success",
    "result" => {"credential-store-update" => {
        "status" => "new-entry-added",
        "new-alias" => "kgoxia900g"
    }},
    "response-headers" => {"process-state" => "reload-required"}
}

The above command will result in a new entry being automatically added to our credential store, myCredStore, with the generated alias, kgoxia900g, and credential myNewPassword. If we take a look at our newly configured key-store, we can see that its credential-reference attribute references the credential store and the newly generated alias only:

/subsystem=elytron/key-store=newKS2:read-attribute(name=credential-reference)
{
    "outcome" => "success",
    "result" => {
        "store" => "myCredStore",
        "clear-text" => undefined,
        "alias" => "kgoxia900g"
    },
    "response-headers" => {"process-state" => "reload-required"}
}

Automatically Updating an Existing Credential in a Store

If we update an existing credential-reference attribute that contains both the alias and store attributes to also specify the clear-text attribute, the existing credential in the configured credential store will be replaced with the clear text password that was specified. The clear-text attribute will then be removed from the management model. As an example, the following command will result in updating the credential for the myNewAlias entry from our previous example:

/subsystem=elytron/key-store=newKS1:write-attribute(name=credential-reference.clear-text, value=myUpdatedPassword)
{
    "outcome" => "success",
    "result" => {"credential-store-update" => {"status" => "existing-entry-updated"}},
    "response-headers" => {
        "operation-requires-reload" => true,
        "process-state" => "reload-required"
    }
}

Summary

This blog post has given an overview of how credentials can be automatically added to a credential store and how existing credentials in a credential store can be automatically updated. This means that users no longer need to add credentials to a credential store or update existing credentials in a store before being able to reference them from a credential-reference. Take a look at the Elytron documentation for more details.