Merge pull request #2177 from PrarthonaPaul/develop

Add a use case driven guide on using Credential-stores to store passwords

_posts/2024-08-14-credential-store-for-passwords.adoc

@@ -0,0 +1,171 @@
+---
+layout: post
+title: 'Using Credential Stores to Replace Clear Text Passwords in WildFly'
+date: 2024-08-14
+tags: credential-store 
+synopsis: How to use credential stores to specify passwords for resources. 
+author: prarthonapaul
+---
+
+:toc: macro
+:toc-title:
+
+WildFly allows the use of credential stores to keep aliases for sensitive information, such as, passwords for external services. Credential stores can be used to store different credentials under aliases and use credential-reference to specify them in server configuration. As a result, the credential is no longer visible in clear text. 
+
+toc::[]
+
+== Prerequisite
+To follow along with this guide you will need:
+
+* about 10 minutes
+* WildFly  
+
+== About Credential Reference
+There are multiple uses for credential stores, but this blog post will dive deeper into using credential-stores to avoid specifying passwords in clear text. Passwords are used for various resources when configuring the WildFly server, such as a `key-store` or a `key-manager`. While it is quick and easy to specify the passwords in clear text, it is not very secure. 
+
+== Creating a Resource with Plaintext Password
+Let us first create a resource with the password specified as plaintext. To do that, let's first start the server: 
+```
+    $ WILDFLY_HOME/bin/standalone.sh 
+```
+Once the server is running, open another terminal and connect to the cli to configure the server: 
+```
+    $ WILDFLY_HOME/bin/jboss-cli.sh --connect
+```
+Now we can create a keystore using a plaintext password: 
+```
+/subsystem=elytron/key-store=serverKS:add(path=server.keystore, relative-to=jboss.server.config.dir, type=PKCS12, credential-reference={clear-text=secret})
+```
+
+When configuring a resource using plaintext password, it is stores in the standalone.xml file as seen below: 
+```
+    <key-store name="serverKS">
+        <credential-reference clear-text="secret"/>
+        <implementation type="PKCS12"/>
+        <file path="server.keystore" relative-to="jboss.server.config.dir"/>
+    </key-store>
+```
+As you can see, the password can easily be obtained from the standalone.xml file or using the read-resource() function on the elytron subsystem: 
+```
+{
+    "outcome" => "success",
+    "result" => {
+        "alias-filter" => undefined,
+        "credential-reference" => {"clear-text" => "secret"},
+        "path" => "server.keystore",
+        "relative-to" => "jboss.server.config.dir",
+        "required" => false,
+        "provider-name" => undefined,
+        "providers" => undefined,
+        "type" => "PKCS12"
+    }
+}
+```
+However, this can be changed using a credential-store and alias to point to the password instead. 
+
+== Create a Credential Store
+A credential store can hold multiple passwords at once, with each password uniquely identified by an alias. When we want to use a password for a resource, we can specify which credential-store it is in and which alias it is under. Let's first 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)
+```
+
+If you navigate to WILDFLY_HOME/standalone/configuration, you will see a new file has been created there named mycredstore.cs. This file is used to store all the credentials in a credential-store. If you try to view the contents of this file using a text editor, you will see that the file is not human readable. It is possible to programmatically read the passwords, which is what WildFly does when dereferencing the credential reference to access a resource. 
+
+== Add an Entry to the Credential-Store
+In order to use the credential-store for our keystore, we need to add the keystore password to it: 
+```
+/subsystem=elytron/credential-store=myCredStore:add-alias(alias=kspass, secret-value=secret)
+```
+Here, `alias` is the unique identifier that is used to refer to this password entry inside the credential store. The `secret-value` refers to the actual value of the password.
+
+=== Disable History for the Management Console
+As you may have noticed, above that we specified the password to be added to the credential store in clear-text. So while it would no longer appear on the standalone.xml file, if someone went through the management CLI history, they can easily find the password. In order to avoid this, we can disable the history using the command below: 
+```
+[standalone@localhost:9999 /] history --disable
+```
+Once you have added your passwords to the credential store, you can enable history again using the command below: 
+```
+[standalone@localhost:9999 /] history --enable
+```
+
+== Update the Keystore Credentials
+Now, we can edit our keystore to use the credential store instead of the clear-text password: 
+```
+/subsystem=elytron/key-store=serverKS:write-attribute(name=credential-reference, value={store=myCredStore, alias=kspass})
+```
+Now if we use the read-resource function, we can no longer see the password: 
+```
+{
+    "outcome" => "success",
+    "result" => {
+        "alias-filter" => undefined,
+        "credential-reference" => {
+            "store" => "myCredStore",
+            "alias" => "kspass"
+        },
+        "path" => "server.keystore",
+        "relative-to" => "jboss.server.config.dir",
+        "required" => false,
+        "provider-name" => undefined,
+        "providers" => undefined,
+        "type" => "PKCS12"
+    },
+    "response-headers" => {"process-state" => "reload-required"}
+}
+```
+
+== Automatic Credential Store Update
+WildFly also allows us to automatically add a new password to a previously created credential-store when specifying the password for a reference. We can automatically add a new password by using the credential-reference attribute for a resource and by specifying the clear-text password there using the following commands: 
+```
+/subsystem=elytron/key-store=serverKS:write-attribute(name=credential-reference, value={store=myCredStore, alias=example, clear-text=secret})
+```
+This will produce the an output like this: 
+```
+{
+    "outcome" => "success",
+    "result" => {"credential-store-update" => {
+        "status" => "new-entry-added",
+        "new-alias" => "example"
+    }},
+    "response-headers" => {
+        "operation-requires-reload" => true,
+        "process-state" => "reload-required"
+    }
+}
+```
+As you can see from the output, the credential-store has been updated to add a new credential and that is being used for the keystore now. If you reload the server and call the read-resource function on the keystore, this will be the output: 
+```
+{
+    "outcome" => "success",
+    "result" => {
+        "alias-filter" => undefined,
+        "credential-reference" => {
+            "store" => "myCredStore",
+            "alias" => "example"
+        },
+        "path" => "server.keystore",
+        "relative-to" => "jboss.server.config.dir",
+        "required" => false,
+        "provider-name" => undefined,
+        "providers" => undefined,
+        "type" => "PKCS12"
+    }
+}
+```
+Notice how even though we specified the clear-text password when updating the credentials, it does not show up here. Instead, we can see the name of the credential-store and the alias listed under credential-reference. 
+
+== Remove Unused Credentials
+If you are no longer using an alias and would like to remove it from the credential store, then you can do that using the following command: 
+```
+/subsystem=elytron/credential-store=myCredStore:remove-alias(alias=myalias)
+```
+However, when deleting an alias, you must be careful. If the alias you are trying to delete is currently in use, it may still be removed successfully, leaving the resource's credential-reference pointing to a non-existent alias. 
+
+== Summary
+This blog post introduces us to credential stores and introduces us to one of the use cases for them. There are other use cases for credential-stores when securing resources in the WildFly server. Future guides will cover other use cases. 
+
+== Resources
+* To learn more about credential stores, please refer to the https://docs.wildfly.org/30/WildFly_Elytron_Security.html#CredentialStore[documentation]
+* To learn more about automatic credential-store updates, visit https://wildfly-security.github.io/wildfly-elytron/blog/automatic-credential-store-updates/[this blog post]
+* You can also use the `read-resource-description` function in command line to learn more about the credential-reference resource.