WildFly Elytron Credential Store APIs

WildFly Elytron contains a CredentialStore API/SPI along with a default implementation that allows for the secure storage of various credential types.  This blog post is to introduce some of the APIs available to make use of the credential store from directly within your code.

The full example is available at elytron-examples/credential-store but this blog post will highlight the different steps in the code.

Before the credential store is accesses a ProtectionParameter is needed for the store, the following two lines: -

Password storePassword = ClearPassword.createRaw(
    ClearPassword.ALGORITHM_CLEAR, 
    "StorePassword".toCharArray());
ProtectionParameter protectionParameter = new CredentialSourceProtectionParameter(
    IdentityCredentials.NONE.withCredential(
    new PasswordCredential(storePassword)));

Credential store implementations can be registered using java.security.Provider instances and follow a similar pattern used elsewhere: -

• getInstance
• initialise
• use

An instance of the credential store we want to use can be obtained from: -

CredentialStore credentialStore = CredentialStore.getInstance(

    "KeyStoreCredentialStore", CREDENTIAL_STORE_PROVIDER);

In this example an instance of java.security.Provider has been passed in, if this parameter was omitted the registered providers would be used instead.

The credential store implementation provided with WildFly Elytron is "KeyStoreCredentialStore" which is a credential store implementation which makes use of a KeyStore for persistence.

The credential store instance is now initialised using a Map and the previously created ProtectionParameter.  The values supported in the Map are specific to the credential store implementation.

Map<String, String> configuration = new HashMap<>();
configuration.put("location", "mystore.cs");
configuration.put("create", "true");

credentialStore.initialize(configuration, protectionParameter);

The "location" value is used to specify the full path to the file which represents the credential store.  The second option "create" specifies that the credential store should be created if it does not already exist, whilst tooling can be used to create and populate a store in advance this does mean that a store can be created entirely within the application that is using it.

With those few lines we now have a credential store ready for use.  The first thing to do is to add some entries to this store.  Within the application server we do presently predominantly use this for storing passwords, however many alternative credential types can be stored using the credential store so here are a few examples of the types that can be stored.

Storage of a clear text password: -

Password clearPassword = ClearPassword.createRaw(
    ClearPassword.ALGORITHM_CLEAR, "ExamplePassword".toCharArray());
credentialStore.store("clearPassword", 
    new PasswordCredential(clearPassword));

Generation and storage of a SecretKey: -

KeyGenerator keyGenerator = KeyGenerator.getInstance("AES");
keyGenerator.init(256);
SecretKey secretKey = keyGenerator.generateKey();
credentialStore.store("secretKey", 
    new SecretKeyCredential(secretKey));

Generation and storage of a KeyPair: -

KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance("RSA");
keyPairGenerator.initialize(2048, SecureRandom.getInstanceStrong());
KeyPair keyPair = keyPairGenerator.generateKeyPair();
credentialStore.store("keyPair", new KeyPairCredential(keyPair));

Storage of just the public key from the KeyPair: -

credentialStore.store("publicKey", 
    new PublicKeyCredential(keyPair.getPublic()));

Various credential types are supported within WildFly Elytron and can be seen here: -

http://wildfly-security.github.io/wildfly-elytron/1.9.x/api-javadoc/org/wildfly/security/credential/package-summary.html

For custom credential store implementation different credential types may be supported including custom ones not listed here.

Once we have a populated credential store it is possible to list the aliases similar to how you would for a KeyStore: -

System.out.println("************************************");
System.out.println("Current Aliases: -");
for (String alias : credentialStore.getAliases()) {
    System.out.print(" - ");
    System.out.println(alias);
}
System.out.println("************************************");

Finally the purpose of storing credentials in a credential store is so that they can subsequently be retrieved, the following shows how each of the credentials added above can be retrieved: -

Password password = credentialStore.retrieve(
    "clearPassword", PasswordCredential.class).getPassword();
SecretKey secretKey = credentialStore.retrieve(
    "secretKey", SecretKeyCredential.class).getSecretKey();
KeyPair keyPair = credentialStore.retrieve(
    "keyPair", KeyPairCredential.class).getKeyPair();
PublicKey publicKey = credentialStore.retrieve(
    "publicKey", PublicKeyCredential.class).getPublicKey();

In the above command the expected credential type is passed into the retrieve method, using the credential store APIs it is possible for multiple credentials to be stored under the same alias.  This could be useful in situations where a single alias can represent say a password AND a secret key.

Security Feature Development for WildFly 17

At the beginning of development for WildFly 17 I published the following blog post identifying the features we were planning to work on during the feature development phase: -

https://darranl.blogspot.com/2019/03/security-features-for-wildfly-17.html

Now that WildFly 17 is complete this blog post is to provide some further information on the progress of these features.

Reviewing release notes provides a very coarse list of the changes that were actually merged during the development of Wildfly 17 this blog post provides further information in relation to the progress of features actively being developed.

JDBC Security Realm - Hex and Modular Crypt Encoding.

One of the planned features was to add support for hex encoding of passwords and support for modular crypt with the JDBC security realm, this feature has been merged and is available from WildFly 17 Final.

WFCORE-3832 Support hex encoding in jdbc-realm for elytron.

A blog post is available here showing some examples using this feature: -

https://developer.jboss.org/people/aabdelsa/blog/2019/06/11/configuring-a-jdbc-security-realm-with-bcrypt-and-modular-crypt-password-mappers

Additionally additional documentation has been published describing both the PasswordFactory APIs and the JDBC security realm.

https://docs.wildfly.org/17/WildFly_Elytron_Security.html#Passwords
https://docs.wildfly.org/17/WildFly_Elytron_Security.html#jdbc-security-realm

TLS 1.3

WFCORE-4172 Add support for TLS 1.3

Support for TLS 1.3 was developed during the development of WildFly 17, the changes were not quite ready during before the feature freeze however we hope these can be merged soon for WildFly 18.  In the meantime some further background to the changes can be found here: -

https://developer.jboss.org/people/fjuma/blog/2019/06/11/upcoming-support-for-tls-13-with-wildfly

X509Certification Mapping

WFCORE-4361 Enhanced mapping of X509Certificate to the underlying identity.

This feature is also close to be ready to be merged with information available at: -

https://developer.jboss.org/people/fjuma/blog/2019/06/11/mapping-an-x509-cert-to-an-identity-using-a-subject-alt-name

Audit Logging RFC Support and Performance Enhancements

More information can be found in the following blog post on enhancements presently being prepared in relation to enhanced RFC support and performance enhancements for audit logging: -

https://justinwildfly.blogspot.com/2019/06/enhanced-audit-logging-in-wildfly.html

Web Services and RESTEasy Client Integration

This is a pair of tasks involving collaboration between the WildFly Elytron engineering team and the respective engineers working on these projects.

WFLY-11697 WS integration with WildFly Elytron - AuthenticationClient for Authentication / SSL

The following blog contains information on the progress so far: -

https://dvilkola.wordpress.com/2019/06/11/web-services-client-and-resteasy-client-integration-with-wildfly-elytron/

Identity Attribute Aggregation

The aggregation of an identity's attributes from multiple security realms is being handled under WFCORE-4447, more information on the progress of this feature can be seen under the following blog post: -

https://darranl.blogspot.com/2019/06/wildfly-elytron-aggregation-of.html

Certificate Authority Account Configuration

Previous work has added support for LetsEncrypt within the application server WFCORE-4362 is a follow on task to make it possible to configure alternative certificate authority accounts enabling support for alternative certificate authorities which support the ACME protocol.

More information about this development can be found in the following blog post: -

https://dvilkola.wordpress.com/2019/06/11/obtain-and-manage-certificates-from-any-server-instance-that-implements-acme-specification-using-the-wildfly-cli/

OCSP

Finally development has been progressing WFCORE-3947 and we are hoping this one will be merged shortly, more information on this development can be seen in the proposal: -

https://github.com/wildfly/wildfly-proposals/pull/188

WildFly Elytron Aggregation of Attributes

One of the features developed during the development phase of Wildfly 17 was the addition of support for aggregating security realms to allow an identity's attributes to be aggregated from multiple realms.

https://issues.jboss.org/browse/WFCORE-4447

This feature was not quite ready as the code freeze for WildFly 17 arrived however the feature is now complete and is planned to be merged into WildFly 18 so will be available for use as soon as Wildfly 18 is released.

This enhancement has made use of the existing aggregate-security-realm resource, presently this resource supports two different attributes: -

• authentication-realm - The realm to load credentials from and perform evidence verification against.
• authorization-realm - The realm to use to load the identities attributes from for authorization decisions.

This enhancement is adding a new attribute authorization-realms to the resource which allows for multiple realms to be referenced.

A realm can then be defined with a CLI command: -

/subsystem=elytron/aggregate-realm=example:add(
    authentication-realm=ApplicationRealm, 
    authorization-realms=[RealmA, RealmB])

Attributes are aggregated on a 'first defined wins' basis, so as an example say an identity was assigned the following attributes from RealmA: -

• groups = User, Supervisor
• city = London

And from RealmB the following attributes were assigned: -

• groups = Manager
• telephone = 0000 0000 0000

After aggregation the identity would have the following attributes: -

• groups = User, Supervisor
• city = London
• telephone = 0000 0000 0000

Security Features for WildFly 17

The development for WildFly 17 has now commenced, here are some of the features we are planning to be looking into developing for WildFly 17.

WFCORE-4360 Support encrypted expression resolution using a CredentialStore

The previous Vault implementation was effectively a repository of encrypted clear text strings that could be referenced using expressions in the management model, the new CredentialStore is a repository of credentials.  WFCORE-4360 is to look into how the CredentialStore could be used to support encrypted values within the overall model.

WFCORE-3947 Support SSL Certificate revocation using OCSP

ELY-1712 Enhanced Audit Logging

As the WildFly Elytron project was integrated with WildFly 11 an initial set of events were made available with a couple of options for logging these events, this feature request is to look into how we can enhance this further.

WFCORE-4361 Enhanced mapping of X509Certificate to the underlying identity.

Presently WildFly Elytron provides a variety of options to configure certificate based authentication, this feature request is to enhance how the certificate is mapped to the underlying identity.

WFLY-11697 Web Services Integration with WildFly Elytron

The WildFly Elytron integration added a new API and configuration file to configure the client side security for outgoing calls, this feature request is to increase the integration for web services clients.

WFCORE-4172 Add support for TLS 1.3

WFCORE-4362 Make the certificate authority used by a certificate-authority-account configurable.

At the moment integration with Lets Encrypt is supported, once the certificate authority account is configurable it will be possible to use this integration with other certificate authorities that implement the ACME protocol.

WFCORE-3832 Support hex encoding in jdbc-realm for elytron.

Using multiple security realms.
WildFly Elytron already supports the use of multiple security realms where a realm can be selected either from the authentication mechanism in use or by some recognisable pattern in the username. 

Where LoginModules were used in the previous PicketBox solution it was possible to stack the LoginModules for a few additional scenarios: -

• Failover in the event of unavailability.
• Aggregation of multiple identity stores into one.
• Allowing identities to be located in different stores.
• Allowing attributes to be loaded from multiple locations.

Issues will be created as needed to track these different scenarios but the aim is during WildFly 17 to begin to address these as they have been identified as making it difficult to migrate from PicketBox.


Also in preparation to develop WildFly Elytron 1.9 the project has been broken up into smaller modules to allow dependencies to be defined on specific modules without depending on the whole project - WildFly 17 will be switching to use the new modules.

Please keep in mind this blog post is a summary of our general plans and not a guarantee that all will be merged but it should give an indication as to the teams current priorities.  If any of these features are a priority to you please let us know, also let us know if there are missing security features you would like prioritising - we can take this into account for future releases.

Using WildFly Elytron with the Netty HttpServerCodec

The WildFly Elytron project was developed to meet the needs if the WildFly application server, however the APIs and SPIs within this project also allow us to use the project in other environments.

A couple of previous blogs from Farah Juma and myself have highlighted a couple of these environments already: -
 Using WildFly Elytron with Undertow Standalone
 Securing an embedded Jetty server using Elytron

Also I have previously published a blog describing how to implement a custom HTTP authentication mechanism using the WildFly Elytron SPIs.
WildFly Elytron - Implementing a Custom HTTP Authentication Mechanism

Being able to take a single security project and use it in multiple environments has numerous benefits, some of which are: -

• Only needing to learn one framework instead of one framework per server type.
• Portability of custom implementation such as authentication mechanisms or security realms which can be used in all environments.
• The ability to combine multiple servers into a single process whilst using common security SPIs.

This blog post is to introduce the integration of WildFly Elytron with the Netty HttpServerCodec for HTTP authentication.

It is worth noting this integration is specifically making use of Netty's HttpServerCodec for integration, if an alternative HTTP server was developed on Netty then an alternative integration with WildFly Elytron would also be required.

The project containing the Netty integration code can be found on GitHub at elytron-web-netty

As an integration project this project only exposes once class as public API 'org.wildfly.elytron.web.netty.server.ElytronHandlers'  - the purpose this class is to take configured WildFly Elytron components and use them to insert a set of handlers into a Netty ChannelPipeline, once inserted they will perform authentication kaing use of Wildfly Elytron.

The example project can be found on GitHub at netty-standalone.

After checking out the example project it can be built using maven: -

    mvn clean instal

And then once build can also be executed using maven: -

    mvn exec:exec

Once running you can navigate to http://localhost:7776/ and access the application using the username 'alice' with the password 'alice123+', if successful you should see the following response: -

Current identity 'alice'

Now that the example project is running we can look into the details as to how WildFly Elytron was activated.

Activation

Within Netty a ChannelInitializer is required to add the handlers to the ChannelPipeline, within the example project this is within the class 'org.wildfly.security.examples.TestInitialiser' and is implemented as: -

protected void initChannel(SocketChannel ch) throws Exception {

    ChannelPipeline pipeline = ch.pipeline();

    pipeline.addLast(new HttpServerCodec());

    pipeline.addLast(new HttpServerExpectContinueHandler());

    securityHandler.apply(pipeline);

    pipeline.addLast(new TestContentHandler());

}

The 'securityHandler' within the example block of code is actually an instance of the ElytronHandlers class, it is worth noting that it can be cached and re-used potentially performing many initialisations concurrently.

As the example projects starts up the ElytronHandlers is initialised as follows: -

ElytronHandlers securityHandlers = ElytronHandlers.newInstance()

        .setSecurityDomain(securityDomain)

        .setFactory(createHttpAuthenticationFactory())

        .setMechanismConfigurationSelector(MechanismConfigurationSelector.constantSelector(

                MechanismConfiguration.builder()

                        .addMechanismRealm(MechanismRealmConfiguration.builder().setRealmName("Elytron Realm").build())

                        .build()));

This initialisation takes a pre-configured SecurityDomain and HttpAuthenticationFactory and adds a MechanismConfigurationSelector, these have been covered on prior blogs so I am not going to cover the details of these again here although they can all be seen within the org.wildfly.security.examples.HelloWorld class to see how these are initialised.

One further method not used in this example is: -

public ElytronHandlers setAuthenticationRequired(final Predicate<HttpRequest> authenticationRequired)

This can be used to add a Predicate to decide on a request by request basis if authentication is required after inspecting the HttpRequest.

Outcome

After the initialisation described above the channel end up with the following handlers defined on it's pipeline: -

For a request after being handled by the HttpServerCodec handler it will pass so the ElytronInboundHandler, this is where the authentication by WildFly Elytron takes place and a SecurityIdentity is established.

If authentication fails the request can be turned around at this stage and sent back to the client.

Our next inbound handler is the ElytronRunAsHandler, this handler is responsible for taking any established SecurityIdentity and ensuring it is associated with the current thread.

In this set up we have one outbound handler which is the ElytronOutboundHandler, this handler is called for all messages being sent back to the client is responsible for setting any security related HTTP headers that need to be set on the respone message.

Contribution

The Netty integration project is currently tagged as a Beta as a number of areas still need to be developed, if anyone is interested in contributing their contributions will be welcome.

Completing the implementation of the ElytronHttpExchange class: -

• Support for all Scope types.
• Parsing of request parameters.
• Cookie support.

Request InputStream handling.

Improved response OutputStream handling.

Adding support for authorization, either role based checks or Java permission checks.

Further enhancement of the test cases including adding more mechanisms to be tested.

Outside of the Netty integration there are other projects out there still possible options for integration, some of these are: -

• Tomcat
• Pure servlet integration.
• EE Security integration.

For all integrations some form of common testsuite to verify the full permutation of authentication mechanisms available within WildFly Elytron.

Using WildFly Elytron JASPI with Standalone Undertow

As part of the development efforts for WildFly 15 an implementation of the servlet profile from the JASPI (JSR-196) specification has been added to WildFly Elytron and is in the final stages of being integrated within the application server.

As with many of the features included in WildFly Elytron it is possible to make use of this outside of the application server, this blog post combined with an example project illustrates how the WildFly Elytron JASPI implementation can be used with a standalone Undertow server.

The example project can be found at the following location: -

https://github.com/wildfly-security-incubator/elytron-examples/tree/master/undertow-standalone-jaspi

The project can be built using Apache Maven using the following command: -

mvn clean install

And executed with: -

mvn exec:exec

The remainder of this blog post will describe the remainder of the project and then demonstrate how to make an invocation to the servlet using 'curl'.

Server Auth Module

This project contains a very simple ServerAuthModule 'org.wildfly.security.examples.jaspi.SimpleServerAuthModule', this module expects to receive a username using the 'X-USERNAME' header and expects to receive a password using the 'X-PASSWORD' header.

This module does not perform it's own username and password validation, instead it makes use of a 'PasswordValidationCallback' which is handled by the 'CallbackHandler' passed to the module on initialisation, this means the verification is in turn handled by WildFly Elytron.

Finally this module makes use of a 'GroupPrincipalCallback' which is used to override the groups / role assigned to the resulting identity and in this case assign the identity the 'Users' role.

Although this example demonstrates delegating the verification of the username and password to WildFly Elytron it is also possible to implement a ServerAuthModule which performs it's own validation and instead just describe the resulting identity using the callbacks.

Servlet

To make this demonstration possible the example project contains a servlet 'org.wildfly.security.examples.servlet.SecuredServlet', the purpose of this servlet is to return a HTML page containing the name of the current authenticated identity.

Configuration and Execution

Undertow and WildFly Elytron are programatically configured and started within 'org.wildfly.security.examples.HelloWorld', this class contains some initialisation that has been seen previously and some new configuration to enable JASPI and integrate with Undertow.

createSecurityDomain()

The first step is to create the SecurityDomain backed by a SecurityRealm: -

private static SecurityDomain createSecurityDomain() throws Exception {

    PasswordFactory passwordFactory = PasswordFactory.getInstance(ALGORITHM_CLEAR, elytronProvider);

    Map<String, SimpleRealmEntry> identityMap = new HashMap<>();

    identityMap.put("elytron", new SimpleRealmEntry(Collections.singletonList(

        new PasswordCredential(passwordFactory.generatePassword(new ClearPasswordSpec("Coleoptera".toCharArray()))))));

    SimpleMapBackedSecurityRealm simpleRealm = new SimpleMapBackedSecurityRealm(() -> new Provider[] { elytronProvider });

    simpleRealm.setIdentityMap(identityMap);

    SecurityDomain.Builder builder = SecurityDomain.builder()

            .setDefaultRealmName("TestRealm");

    builder.addRealm("TestRealm", simpleRealm).build();

    builder.setRoleMapper(RoleMapper.constant(Roles.of("Test")));

    builder.setPermissionMapper((principal, roles) -> PermissionVerifier.from(new LoginPermission()));

    return builder.build();

}

Here we have a single identity 'elytron' with the password 'Coleoptera', however any of the other security realms could have been used here allowing for alternative integration options.

configureJaspi()

The next step is the JASPI configuration, at this stage this is still independent of the Undertow initialisation: -

private static String configureJaspi() {

    AuthConfigFactory authConfigFactory = new ElytronAuthConfigFactory();

    AuthConfigFactory.setFactory(authConfigFactory);

    return JaspiConfigurationBuilder.builder(null, null)

            .setDescription("Default Catch All Configuration")

            .addAuthModuleFactory(SimpleServerAuthModule::new)

            .register(authConfigFactory);

}

The first step is to initialise the Elytron implementation of 'AuthConfigFactory' and to register it as the global default implementation.

The JASPI APIs provide a lot of flexibility to allow for programatic registration of configurations, however the APIs do not provide a way to instantiate the implementations of these implementations when in the majority of the cases where dynamic registration is used it is just to register a custom ServerAuthModule.  With the changes added to Wildfly Elytron we have added a new API of our own in a class called 'org.wildfly.security.auth.jaspi.JaspiConfigurationBuilder' - this can be used to register a configuration with the 'AuthConfigFactory'.

Configuring and Starting Undertow

Now that the prior two steps have been completed it is possible to use the Undertow and WildFly Elytron APIs to complete the configuration of a deployment and start the Undertow server with JASPI authentication enabled.

The first step is using the Undertow APIs to define a deployment: -

DeploymentInfo deploymentInfo = Servlets.deployment()

        .setClassLoader(SecuredServlet.class.getClassLoader())

        .setContextPath(PATH)

        .setDeploymentName("helloworld.war")

        .addSecurityConstraint(new SecurityConstraint()

                .addWebResourceCollection(new WebResourceCollection()

                        .addUrlPattern("/secured/*"))

                .addRoleAllowed("Users")

                .setEmptyRoleSemantic(SecurityInfo.EmptyRoleSemantic.DENY))

        .addServlets(Servlets.servlet(SecuredServlet.class)

                .addMapping(SERVLET));

Next we can use the WildFly Elytron APIs to apply Wildfly Elytron backed security to this deployment: -

AuthenticationManager authManager = AuthenticationManager.builder()

        .setSecurityDomain(securityDomain)

        .build();

authManager.configure(deploymentInfo);

It is worth noting this is where the WildFly Elytron SecurityDomain is associated with the deployment, the JASPI configuration performed earlier was independent of the domain.

The final stages are now to complete the deployment before creating and starting the Undertow server: -

DeploymentManager deployManager = Servlets.defaultContainer().addDeployment(deploymentInfo);

deployManager.deploy();

PathHandler path = Handlers.path(Handlers.redirect(PATH))

        .addPrefixPath(PATH, deployManager.start());

Undertow server = Undertow.builder()

        .addHttpListener(PORT, HOST)

        .setHandler(path)

        .build();

server.start();

Invoking the Servlet

Once the server is running it is now time to invoke the servlet using 'curl', other clients could also be used however they would need to support custom headers to work with this mechanism.

Firstly if we call the servlet without any headers we should see the request rejected with a message asking for the headers: -

]$ curl -v http://localhost:28080/helloworld/secured

...

< HTTP/1.1 401 Unauthorized

< Expires: 0

< Connection: keep-alive

< Cache-Control: no-cache, no-store, must-revalidate

< Pragma: no-cache

< X-MESSAGE: Please resubmit the request with a username specified using the X-USERNAME and a password specified using the X-PASSWORD header.

< Content-Type: text/html;charset=UTF-8

< Content-Length: 71

< 

We can now repeat the command and provide a username and password using the appropriate headers: -

]$ curl -v http://localhost:28080/helloworld/secured -H "X-Username:elytron" -H "X-Password:Coleoptera"

...

< HTTP/1.1 200 OK

< Expires: 0

< Connection: keep-alive

< Cache-Control: no-cache, no-store, must-revalidate

< Pragma: no-cache

< Content-Length: 154

< 

<html>

  <head><title>Secured Servlet</title></head>

  <body>

    <h1>Secured Servlet</h1>

    <p>

 Current Principal 'elytron'    </p>

  </body>

</html>

In this case we now see the expected HTML specifying the name of the current identity.

WildFly Elytron - Credential Store - Next Steps

During the development of WildFly 11 where we introduced the WildFly Elytron project to the application server one of the new features we added was the credential store.

https://developers.redhat.com/blog/2017/12/14/new-jboss-eap-7-1-credential-store/

Now that we are planning the next stages of development for WildFly 15 and 16 we are revisiting some of the next steps for the credential store, this blog post explores some of the history of the current decisions made with the credential store and the types of enhancement being requested to develop this further.

Anyone making use of either the CredentialStore or Vault is encouraged to provider your feedback so we can take this into account as the next stages are planned.

Key Differences To Vault

Prior to the credential store the PicketBox vault was the solution used for the encryption of credentials and other fields within the application server's configuration, the credential store approach was dedicated to the secure storage of credentials.

Where the PicketBox vault is used in the application server a single Vault is defined across the whole server and aliases from the vault are referenced via expressions in the server's configuration which allows for the values to be retrieved in clear text.

The credential store on the other hand allows for multiple credential store instances to be defined, resources that make use of the credentials have been updated to a special attribute type where both the name of the credential store can be specified and the alias of the credential within the credential store.

The credential store resources additionally support management operations to allow for entries within the credential store to be manipulated either by adding / removing entries or by updating existing entries.

Uses of the Store

Reviewing where the credential store is used we seem to have two predominant scenarios.

Unlocking Local Resources

In this case a credential is required to unlock a local resource such as a KeyStore, there is no remote authentication to be performed and a credential is generally only required for decrypting the contents of the store.  This is the simplest use of the store and once the resource is unlocked it is not likely to need unlocking again.

Accessing Remote Resources

The second use we see is for services accessing a remote resource, in this case the credentials for the connection are obtained from the credential store.

This scenario has a reasonable amount of history also attached to the current implementation, it tended to be the case that if you were to access a remote resource it would either not be secured or it would be secured and authentication would require a username and password.  Additionally any SSL related configuration would be handled completely independently.

In recent years however there has been a greater demand for alternative authentication mechanisms, there has been a lot of demand for Kerberos both with the server being given it's own account for authentication and also for the propagation of a remote user authenticated against the server using Kerberos.  We haven't seen requests yet for the application server but I suspect OAuth scenarios will be requested soon.

In both of these cases the security has moved from username / password authentication to more advanced scenarios.

In parallel to the credential store WildFly Elytron has also introduced an Authentication Client API, this API can be used for configuring the client side authentication policies for various mechanisms, including scenarios that support propagation of the current identity.  The authentication client configuration also allows SSLContext configurations to be associated with a specific destination.

This now raises the question, should services establishing a remote connection which requires authentication and SSL configuration now reference an authentication client configuration instead of the current assumption that a username and credential reference is sufficient?

This question becomes quite important as it affects the approach we take to a lot of the enhancements requested of us quite significantly.

Next Features

The features currently being requested against the credential store generally cover three broad areas: -

1. Automation of updates to the store.
2. Real time updates.
3. Support for expressions.

Automation of Updates to the Store

The general motivation for this enhancement is to simplify the steps configuring resources which require credentials, using the PicketBox Vault implementation the vault would need to be manipulated offline using a command line tool and then references from the application server configuration.

The CredentialStore has already moved on from this partially as management operations have been exposed to allow the contents of the store to be directly manipulated using management requests so the store can be manipulated directly from the management tools.  However an administrator is still required to operate on the two resources completely independently.

We predominantly have two options to simplify this further.

We could take the decision that further enhancement is now a tooling issue, the admin clients could detect a resource is being added that supports credential store references or the password on an existing resource that supports credential store references is being set and provide guidance / automation to persist the credential in the credential store.

1. Would you like to store this credential in a credential store?
2. Which credential store would you like to use? Or would you like to create a new one?
3. What alias would you like the credential to be stored under?

Alternatively, the credential reference attribute supports specifying a reference to a credential store and an alias in the credential store - this attribute however also supports specifying a clear text password.  We could automate the manipulation in the management tier and if a clear text password is specified on a resource referencing a credential store automatically add it to the credential store and remove it from the model - if no alias is specified automatically generate one.

We could also support a combination of the two approaches as in the management tier although we could support the interception of a new clear password if a store needs to be created that would be more involved than we could automate.

Real Time Updates

Where new credentials are added to a credential store using management operations they are already available for use immediately in the application server process without a restart.  However we still have some areas to consider further real time update support: -

1. Updates to the store on the filesystem.
2. Complete replacement of an existing store.
3. Updates to credentials using management operations.

In these three cases the primary interest is credentials which are already in use in the application server, however in the case of #1 and #2 it could relate to the addition of new credentials to be used immediately.

One point to consider is although our default credential store implementation is file based custom implementations could be in use which are not making use of any local files.

At the credential store level we likely should consider various modes to detect changes when emitting notifications: -

1. File system monitoring.
2. Notifications from within the implementation of the store.
3. Administrator triggered reloads of either the full store or individual aliases.

At the service level where a service is making use of a credential it is likely we would want to decide how to handle updates on a service by service basis.  It is unlikely we would want to automatically restart / replace services as for some services which make use of credentials this could cause a cascade of service restarts potentially leading the redeployment of deployments.

I expect some form of notifications will be required, at the coarsest level notifications could be emitted for all services accessing a specific credential store - this however could trigger a significant overhead as a single store could contain a large number of entries used across a large number of resources.  Instead we could emit notifications just to the resources using the affected aliases, this would be more efficient from the perspective of the notifications but the complexity now is where a coarse update has been updates to a store such as the underlying file being replaced or a full store refresh being triggered by an administrator we now need to identify which credentials were really modified.

Support for Expressions

It was a deliberate decision to move away from using expressions, however there are still some demands for expressions that need to be considered.

Overall the design decisions within WildFly Elytron have always considered a desire to move away from clear text passwords being present in the application server process, where expressions are used the only route available is to obtain the clear text representation of a String and pass it around the related services.

One of the enhancements delivered for WildFly 11 was to support multiple credential stores concurrently within the application server, by moving to the complex attribute we were able to make use of capability references to select which credential store to use with a second attribute selecting the alias in the store.

Another consideration was the desire for automatic updates to be applied via the management tier, by moving from expressions to a complex attribute it opens up the options to intercept these values and persist them in the store.

A further (and possibly the greatest) consideration was the desired support for automatic updates to credentials currently in use in the server, by moving to the capability references aided by the complex attribute definition services can now obtain a direct reference to the store instead of having a credential automatically resolved.  By having a reference to a credential store we can potentially add support for direct notifications of updates applied to that store.  Where a credential is updated different services may want to respond in different ways, this is why a reference is needed.  Within the management tier we can not silently automate the updates, if we were to do so it would likely involve the removal and replacement of the service which could have a side effect of restarting many other services including the deployments.

The biggest restriction of not supporting expressions is attributes for anything other than a credential can no longer be loaded from the credential store - but the missing piece of information is how that is really used and why?

As an example usernames could be loaded using expressions, is this because in some environments the username is being considered as sensitive as the credential?  Or is it the case that where a credential is loaded from a store it is easier to load the username from the same store.

If the answer is co-location of the username and password then a more suitable path to look into may be the externalisation of the authentication client configuration allowing the complete client authentication policy to be handled as a single unit.

If we are still left with attributes in the configuration that need to be stored securely the next question is do they strictly need to be removed from the configuration and looked up from the store?  An alternative option we have to consider is supporting the encryption / decryption of Strings inlined in the management model using a credential from the store.

Other Enhancements

Following on from the main enhancements listed above there is also a set of additional enhancements we could consider.

Injection / Credential Store Access for Deployments

Deployments can already access the authentication client configuration, however if access to raw credentials is required it may help to access the store - this could additionally mean a deployment could manipulate the store.

Permission Checks

Once accessed within deployments, making use of the SecurityIdentity permission checks we could perform permission checks for different read / write operations on the credential store.

Auditing

The credential store could be updated to emit security events as it is accessed, by emitting security events these can be output to audit logs or sent to other event analysing frameworks.