New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add a use case driven guide for creating a credential store using elytron-tool for wildfly client configuration #2068
base: develop
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,155 @@ | ||
--- | ||
layout: post | ||
title: 'Using Credential Stores on for WildFly Client' | ||
date: 2023-03-19 | ||
tags: credential-store elytron-tool wildfly-config ejb | ||
synopsis: How to set up a credential store using the elytron-tool and use it for the client configuration on an application deployed to WildFly. | ||
author: prarthonapaul | ||
--- | ||
|
||
:toc: macro | ||
:toc-title: | ||
|
||
WildFly allows the use of credential stores to keep alias 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. | ||
|
||
toc::[] | ||
|
||
== Prerequisite | ||
To follow along with this guide you will need: | ||
|
||
* about 10 minutes | ||
* WildFly with credential-store support | ||
* Elytron-tool for WIldFly server | ||
|
||
== 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: | ||
|
||
``` | ||
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 og 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 secure the application. This can be done using a file named wildfly-config.xml located inside the `src/main/resources` folder of the application. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Just a minor, set og/set of There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Just a minor, should this sentence be: 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. ? Since we are not securing the application with this client config file, but we are supplying the required client authentication that should be used to authenticate the client to the secured app |
||
|
||
== 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: | ||
``` | ||
$ 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: | ||
``` | ||
# 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: | ||
``` | ||
/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: | ||
``` | ||
/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: | ||
``` | ||
$ 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: | ||
``` | ||
$ 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: | ||
``` | ||
<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: | ||
``` | ||
<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: | ||
``` | ||
$ 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. We can access the application by running the client using the command below: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. hm just a total minor suggestion that you can ignore, but since we are not mentioning other applications in this blog, and there are many kinds of applications other than web applications, and we can access This will not be a web application, so we won't use a browser to access it, but instead we will use the terminal. |
||
``` | ||
$ mvn exec:exec | ||
``` | ||
You can see the following output on your terminal: | ||
``` | ||
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * | ||
|
||
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 add identity specification 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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @PrarthonaPaul Maybe this should be: s/ |
||
|
||
== Resources | ||
* https://docs.wildfly.org/30/WildFly_Elytron_Security.html#filesystem-security-realm[Filesystem] | ||
* https://docs.wildfly.org/30/WildFly_Elytron_Security.html#CredentialStore[Credential-Stores] | ||
* https://docs.wildfly.org/30/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`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
typo in title
on for