Merge pull request #643 from PrarthonaPaul/cred-store-client-config

Add a guide for Using Credential Stores for WildFly Client

_data/guides.yaml

@@ -43,6 +43,9 @@ categories:
       - title: Using Credential Stores to Replace Clear Text Passwords with WildFly
         url: /guides/security-credential-store-for-passwords
         description: How to use credential stores to specify passwords for resources.
+      - title: Using Credential Stores for WildFly Client
+        url: /guides/security-credential-store-client-config
+        description: How to set up a credential store using the elytron-tool and use it to configure WildFly clients.
       - title: Using Credential Stores With Encrypted Expressions with WildFly
         url: /guides/security-credential-store-enc-exp
         description: How to set up encrypted expressions and use it to replace clear-text sensitive information.

guides/security-credential-store-client-config.adoc

@@ -0,0 +1,168 @@
+= Using Credential Stores for WildFly Client
+:summary: How to set up a credential store using the elytron-tool and use it for the client configuration on an application deployed to WildFly.
+:includedir: _includes
+include::{includedir}/_attributes.adoc[]
+:prerequisites-time: 10
+
+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. However, there are additional uses for credential store as well. This guides explains how to create credential stores using the elytron-tool and use it for an application deployed to WildFly. 
+
+include::{includedir}/_prerequisites.adoc[]
+* Elytron-tool (provided with WildFly)
+
+== Access the Example Application
+For this guide we will be using the `ejb-security` example application. Let us first clone the project and navigate to it: 
+
+[source,bash]
+----
+git clone https://github.com/wildfly-security-incubator/elytron-examples
+cd ejb-security
+----
+
+== About WildFly Client Configuration
+EJBs, also known as Enterprise JavaBeans are a collection of specifications that are used for building java applications and offer a set of APIs for developing and running secured applications. When invoking EJBs using the WildFly server, we need to configure the WildFly client to specify relevant information about authentication to the secured the application. This can be done using a file named wildfly-config.xml located inside the `src/main/resources` folder of the application. 
+
+== Configure the Server
+For this guide, we will be securing an EJB using a filesystem realm and invoking them from a remote client using a credential store.  This guide will dive deeper into the credential-store configuration of it. https://wildfly-security.github.io/wildfly-elytron/blog/advanced-ejb-security/[This blog post] contains more details about the steps we are taking for configuring the server and what they do.
+
+=== Configure the FileSystem Realm
+First run the server and in another terminal, connect to the management cli: 
+[source,bash]
+----
+    $ WILDFLY_HOME/bin/jboss-cli.sh --connect
+----
+
+Now we can create the filesystem realm and create an identity called quickStartUser, which we will be using to access the application: 
+[source,bash]
+----
+# Create a filesystem realm called fs-realm-users in the server configuration directory
+/subsystem=elytron/filesystem-realm=fsRealm:add(path=fs-realm-users, relative-to=jboss.server.config.dir)
+
+# Add an identity called quickStartUser, which we will be using to access the application
+/subsystem=elytron/filesystem-realm=fsRealm:add-identity(identity=quickstartUser)
+
+# Set a password for the identity
+/subsystem=elytron/filesystem-realm=fsRealm:set-password(clear={password=quickstartPwd1!}, identity=quickstartUser)
+
+# Assign the appropriate roles needed to access the application 
+/subsystem=elytron/filesystem-realm=fsRealm:add-identity-attribute(identity=quickstartUser, name=Roles, value=[guest])
+
+# Add a role decoder which can convert atteibutes from the identity into roles
+/subsystem=elytron/simple-role-decoder=from-roles-attribute:add(attribute=Roles)
+----
+
+Note that the password can also be specified using an encrypted expression instead of clear text. You can refer to https://wildfly-security.github.io/wildfly-elytron/blog/encrypted-expression-on-wildfly/[this guide] for more details about using credential stores and encrypted expressions. 
+
+=== Configure the Security Domain
+Let's create a security domain and an application security domain to be able to invoke our EJB: 
+[source,bash]
+----
+/subsystem=elytron/security-domain=fsSD:add(realms=[{realm=fsRealm, role-decoder=from-roles-attribute}], default-realm=fsRealm,permission-mapper=default-permission-mapper)
+/subsystem=ejb3/application-security-domain=other:add(security-domain=fsSD)
+----
+
+Note that creating an additional security domain (fsSD in this case) is not necessary. We could alternatively take the default ApplicationDomain and add the FileSystem realm, role-decoder and permission-mapper to it.
+
+=== Create an Authentication Factory 
+We now need to create a sasl-authentication-factory and connect our security domain to it and specify a mechanism for the authentication:
+[source,bash]
+----
+/subsystem=elytron/sasl-authentication-factory=application-sasl-authentication:write-attribute(name=security-domain, value=fsSD)
+/subsystem=elytron/sasl-authentication-factory=application-sasl-authentication:list-add(name=mechanism-configurations, value={mechanism-name=SCRAM-SHA-512})
+/subsystem=remoting/http-connector=http-remoting-connector:write-attribute(name=sasl-authentication-factory,value=application-sasl-authentication).
+----
+
+== Configure the WildFly Client
+Now that the server is configured, we can move onto configuring our WildFly client. The first step is to create a credential-store so we can add the quickStartUser identity and its password to it. Using a credential-store helps us avoid specifying the credentials for our identity using plaintext. Previous guides demonstrated how to create a credential store using the elytron subsystem. However, we can also do it using the elytron-tool, which the WildFly server comes with. The elytron tool can be accessed using the elytron-tool.sh(.bat for windows) script and offers many functionalities that the elytron subsystem has.  
+
+=== Create the Credential Store
+We can use the elytron-tool to securely create a credential-store as follows: 
+[source,bash]
+----
+ $ WILDFLY_HOME/bin/elytron-tool.sh credential-store --create --location "/PATH/TO/mycredstore.cs" --password StorePassword
+----
+
+Now let's store the login information for our `quickStartUser` identity into the credential-store: 
+[source,bash]
+----
+ $ WILDFLY_HOME/bin/elytron-tool.sh credential-store --location "/PATH/TO/mycredstore.cs" --password StorePassword --add quickstartUser --secret quickstartPwd1!
+----
+
+Our WildFly client will be able to access this credential-store to access the login information for the identity. Here the quickstartUser is an alias that the password is being stored under and it does not have to match the identity name we specified earlier.
+
+== Configure wildfly-config.xml
+Now that we have our credential-store set up, we need to let our WildFly Client know where to find it and how to access it. We will be making use of a file called `wildfly-config.xml` to communicate that. This file can be found inside the `src/main/resources` folder. 
+
+We can specify the location and the type and password for the credential-store as follows: 
+[source,xml]
+----
+<credential-stores>
+    <credential-store name="mycredstore">
+        <attributes>
+            <attribute name="keyStoreType" value="JCEKS"/>
+            <attribute name="location" value="PATH/TO/mycredstore.cs"></attribute>
+        </attributes>
+            <protection-parameter-credentials>
+                <clear-password password="StorePassword"/>
+        </protection-parameter-credentials>
+    </credential-store>
+</credential-stores>
+----
+
+This should be added into the xml file already, but you may need to update the paths with the actual paths for the credential store. Note you would need to replace "PATH/TO/mycredstore.cs" with the actual path to your credential store.
+
+Now we need to specify which identity to extract from our credential-store. A `credential-store` can hold multiple credentials that are used for various purposes. We can specify which one to use by identifying it with the unique alias we declared earlier. We will also be specifying the authentication mechanism here to match what we specified for the server: 
+
+[source,xml]
+----
+<authentication-configurations>
+    <configuration name="default-config">
+        <set-user-name name="quickstartUser"/>
+        <credentials>
+            <credential-store-reference store="mycredstore" alias="quickstartUser"/>
+        </credentials>
+        <sasl-mechanism-selector selector="SCRAM-SHA-512"/>
+        <providers>
+            <use-service-loader />
+        </providers>
+    </configuration>
+</authentication-configurations>
+----
+
+== Build and Deploy the application
+Now we can use maven to build and deploy the application using the commands below: 
+[source,bash]
+----
+    $ mvn clean install wildfly:deploy
+----
+
+Unlike other applications, this will not be a web application, rather something we can run on the terminal. If you examine the server logs, you will notice that instead of a `.war` deployment, we will be producing a `.jar` deployment file. This will not be a web application, so we won't use a browser to access it, but instead we will use the terminal as follows:
+[source,bash]
+----
+    $ mvn exec:exec
+----
+
+You can see the following output on your terminal:  
+[source,bash]
+----
+* * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+
+Successfully called secured bean, caller principal quickstartUser
+
+Principal has admin permission: false
+
+* * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+----
+
+As you can see, it mentions that the secured bean has been accessed by our identity, quickstartUser and it does not have admin permissions, since we only assigned the `guest` role to it. 
+
+== Summary
+This guide demonstrates how a `credential-store` can be used to specify identity credentials when configuring a WildFly client. This guide also demonstrates how the `elytron-tool` can be used to generate the credential store and add aliases to it. 
+
+[[references]]
+== References
+
+* https://docs.wildfly.org/33/WildFly_Elytron_Security.html#filesystem-security-realm[Filesystem]
+* https://docs.wildfly.org/33/WildFly_Elytron_Security.html#CredentialStore[Credential-Stores]
+* https://docs.wildfly.org/33/WildFly_Elytron_Security.html#credential-store-creation[Creating credential-stores using the Elytron-tool]
+* To learn more about the functions of elytron-tool, you can use the `./bin/elytron-tool.sh -h` command from `WILDFLY_HOME`. 
+