Skip to end of metadata
Go to start of metadata

Authentication Configuration

Properties Based Authentication / Authorization

PicketBox Based Configuration

This migration example assumes a deployed web application is configured to require authentication using FORM based authentication and is referencing a PicketBox based security domain using the UsersRolesLoginModule to load user information from a pair or properties files.

Original Configuration

A security domain can be defined in the legacy security subsystem using the following management operations: -

This would result in a security domain definition: -

Intermediate Configuration

It is possible to take a previously defined PicketBox security domain and expose it as an Elytron security realm so it can be wired into a complete Elytron based configuration, if only properties based authentication was to be migrated it would be recommended to jump to the fully migration configuration and avoid the unnecessary dependency on the legacy security subsystem but for situations where that is not immediately possible these commands illustrate an intermediate solution.

These steps assume the original configuration is already in place.

The first step is to add a mapping to an Elytron security realm within the legacy security subsystem.

This results in the following configuration.

Within the Elytron subsystem a security domain can be defined which references the exported security realm and also a http authentication factory which supports FORM based authentication.

And the resulting configuration: -

Finally configuration needs to be added to the Undertow subsystem to map the security domain referenced by the deployment to the newly defined http authentication factory.

Which results in: -

Note: If the deployment was already deployed at this point the application server should be reloaded or the deployment redeployed for the application security domain mapping to take effect.

The following command can then be used to verify the mapping was applied to the deployment.

The deployment being tested here is 'HelloWorld.war' and the output from the previous command shows this deployment is referencing the mapping.

At this stage the previously defined security domain is used for it's LoginModule configuration but this is wrapped by Elytron components which take over authentication.

Fully Migrated Configuration

Alternatively the configuration can be completely defined within the Elytron subsystem, in this case it is assumed none of the previous commands have been executed and this is started from a clean configuration - however if the security domain definition does exist in the legacy security subsystem that will remain completely independent.

First a new security realm can be defined within the Elytron subsystem referencing the files referenced previously: -

As before a security domain and http authentication factory can be defined.

This results in the following overall configuration.

As before the application-security-domain mapping should be added to the Undertow subsystem and the server reloaded or the deployment redeployed as required.

Which results in: -

At this stage the authentication is the equivalent of the original configuration however now Elytron components are used exclusively.

Legacy Security Realm

Original Configuration

A legacy security realm can be defined using the following commands to load users passwords and group information from properties files.

This results in the following realm definition.

A legacy security realm would typically be used to secure either the management interfaces or remoting connectors.

Migrated Configuration

One of the motivations for adding the Elytron based security to the application server is to allow a consistent security solution to be used across the server, to replace the security realm the same steps as described in the previous 'Fully Migrated' section can be followed again up until the http-authentication-factory is defined.

A legacy security realm can also be used for SASL based authentication so a sasl-authentication-factory should also be defined.

This can be associated with a Remoting connector to use for authentication and the existing security realm reference cleared.

If this new configuration was to be used to secure the management interfaces more suitable names should be chosen but the following commands illustrate how to set the two authentication factories and clear the existing security realm reference.

LDAP Authentication Migration

The section describing how to migrate from properties based authentication using either PicketBox or legacy security realms to Elytron also contained a lot of additional information regarding defining security domains, authentication factories, and how these are mapped to be used for authentication. This section will illustrate some equivalent LDAP configuration using legacy security realms and PicketBox security domains and show the equivalent configuration using Elytron but will not repeat the steps to wire it all together covered in the previous section.

These configuration examples are developed against a test LDAP sever with user entries like: -

The group entries then look like: -

For authentication purposes the username will be matched against the 'uid' attribute, also the resulting group name will be taken from the 'uid' attribute of the group entry.

Legacy Security Realm

A connection to the LDAP server and related security realm can be created with the following commands: -

This results in the following configuration.

PicketBox LdapExtLoginModule

The following commands can create a PicketBox security domain configured to use the LdapExtLoginModule to verify a username and password.

This results in the following configuration.

Migrated

Within the Elytron subsystem a directory context can be defined for the connection to LDAP: -

Then a security realm can be created to search LDAP and verify the supplied password: -

In the prior two examples information is loaded from LDAP to use directly as groups or roles, in the Elytron case information can be loaded from LDAP to associate with the identity as attributes - these can subsequently be mapped to roles but attributes can be loaded for other purposes as well.

By default, if no role-decoder is defined for given security-domain, identity attribute "Roles" is mapped to the identity roles.

This leads to the following configuration.

Composite Stores Migration

When using either PicketBox or the legacy security realms it is possible to define a configuration where authentication is performed against one identity store whilst the information used for authorization is loaded from a different store, when using WildFly Elytron this can be achieved by using an aggregate security realm.

The example here makes use of a properties file for authentication and then searches LDAP to load group / role information. Both of these are based on the previous examples within this document so the environmental information is not repeated here.

PicketBox Based Configuration

A PicketBox based security domain can be created by using the following CLI commands: -

This results in the following domain definition: -

During an authentication attempt the 'UsersRoles' login module will first be called to perform authentication based on the supplied credential, then the 'LdapExtLoginModule' will be called which will proceed to query LDAP to load the roles for the identity.

Legacy Security Realm Configuration

An equivalent configuration can also be created using the legacy security realms with the following commands: -

This results in the following realm definition: -

As with the PicketBox example, authentication is first performed using the properties file - then group searching is performed against LDAP.

Migrated WildFly Elytron Configuration

The equivalent WildFly Elytron configuration can be defined with the following commands: -

This results in the following definitions: -

Within the WildFly Elytron example a new security realm 'aggregate-realm' has been defined, this definition specifies which of the defined security realms should be used for the authentication step and which of the security realms should be used for the loading of the identity used for subsequent authorization decisions.

Database Authentication

The section describing how to migrate from database accessible via JDBC datasource based authentication using PicketBox to Elytron. This section will illustrate some equivalent configuration using PicketBox security domains and show the equivalent configuration using Elytron but will not repeat the steps to wire it all together covered in the previous sections.

These configuration examples are developed against a test database with users table like:

For authentication purposes the username will be matched against the 'username' column, password will be expected in hex-encoded MD5 hash in 'password' column. User role for authorization purposes will be taken from 'role' column.

PicketBox Database LoginModule

The following commands can create a PicketBox security domain configured to use database accessible via JDBC datasource to verify a username and password and to assign roles.

This results in the following configuration.

Migrated

Within the Elytron subsystem to use database accesible via JDBC you need to define jdbc-realm:

This results in the following overall configuration:

In comparison with PicketBox solution, Elytron jdbc-realm use one SQL query to obtain all user attributes and credentials. Their extraction from SQL result specifies mappers.

N-M relation beetween user and roles

When using a n:m-relation beetween user and roles (which means: the user has multiple roles), the previous configuration does not work.

The database:

Here you need two configure two principal queries:

The second query needs an attribute mapping to decode the selected rolename column (index 1):

The role decoder is referenced by the security domain:

Kerberos Authentication Migration

When working with Kerberos configuration it is possible for the application server to rely on configuration from the environment or the key configuration can be specified using system properties, for the purpose of these examples I define system properties - these properties are applicable to both the legacy configuration and the migrated Elytron configuration.

The first line makes debugging easier but the last two lines specify the Kerberos realm in use and the address of the KDC.

HTTP Authentication

Legacy Security Realm

A legacy security realm can be define so that SPNEGO authentication can be enabled for the HTTP management interface.

This results in the following configuration: -

Application SPNEGO

Alternatively deployed applications would make use of a pair of security domains.

This results in: -

An application can now be deployed referencing the SPNEGO security domain and secured with SPNEGO mechanism.

Migrated SPNEGO

The equivalent configuration can be achieved with WildFly Elytron by first defining a security realm which will be used to load identity information.

Next a Kerberos security factory is defined which allows the server to load it's own Kerberos identity.

As with the previous examples we define a security realm to pull together the policy as well as a HTTP authentication factory for the authentication policy.

Overall this results in the following configuration: -

Now, to enable SPNEGO authentication for the HTTP management interface, update this interface to reference the http-authentication-factory defined above, as described in the properties authentication section.

Alternatively, to secure an application using SPNEGO authentication, an application security domain can be defined in the Undertow subsystem to map security domains to the http-authentication-factory defined above, as described in the properties authentication section.

Remoting / SASL Authentication

Legacy Security Realm

It is also possible to define a legacy security realm for Kerberos / GSSAPI SASL authenticatio for Remoting authentication such as the native management interface.

Migrated GSSAPI

The steps to define the equivalent Elytron configuration are very similar to the HTTP example.

First define the security realm to load the identity from: -

Then define the Kerberos security factory for the server's identity.

Finally define the security domain and this time a SASL authentication factory.

This results in the following subsystem configuration: -

The management interface or Remoting connectors can now be updated to reference the SASL authentication factory.

The two Elytron examples defined here could also be combined into one to use a shared security domain and security realm and just use protocol specific authentication factories each referencing their own Kerberos security factory.

Caching Migration

Where a PicketBox based security domain is defined it is possible to enable caching for that security domain, this enables subsequent hits to the identity store to be avoided as an in memory cache can be used instead, this example demonstrates how caching can be used with a WildFly Elytron based configuration.

The purpose of this chapter is to highlight the migration of a configuration with caching enabled, this example is based in the previous LDAP example but with caching enabled.

PicketBox Example

A PicketBox based security domain can be defined with the following commands.

Resulting in the following security domain definition: -

The key difference to the raw LDAP example is that a cache-type of 'default' has been specified on the security domain. The default cache-type is an in memory cache, when using PicketBox it is also possible to specify a cache-type of 'infinispan' although this is not supported with WildFly Elytron as various aspects of a SecurityIdentity are not suitable for replication.

Migrated Example

When using WildFly Elytron where caching is required the individual security realm is wrapped using a cache, a migrated configuration can be defined with the following commands: -

These can then be used in a security domain and subsequently an authentication factory.

In this final step it is very important that the caching-realm is referenced rather than the original realm otherwise caching will be bypassed.

This results in the following definitions: -

Clients

Application Client Migration

Naming Client

This migration example assumes a client application performs a remote JNDI lookup using an InitialContext backed by the org.jboss.naming.remote.client.InitialContextFactory class.

Original Configuration

An InitialContext backed by the org.jboss.naming.remote.client.InitialContextFactory class can be created by specifying properties that contain the URL of the naming provider to connect to along with appropriate user credentials:

Migrated Configuration

An InitialContext backed by the org.wildfly.naming.client.WildFlyInitialContextFactory class can be created by specifying a property that contains the URL of the naming provider to connect to. The user credentials can be specified using a WildFly client configuration file or programmatically.

Configuration File Approach

A wildfly-config.xml file that contains the user credentials to use when establishing a connection to the naming provider can be added to the client application's META-INF directory:

wildfly-config.xml

An InitialContext can then be created as follows:

Programmatic Approach

The user credentials to use when establishing a connection to the naming provider can be specified directly in the client application’s code:

EJB Client

This migration example assumes a client application is configured to invoke an EJB deployed on a remote server using a jboss-ejb-client.properties file.

Original Configuration

A jboss-ejb-client.properties file that contains the information needed to connect to the remote server can be specified in a client application’s META-INF directory:

jboss-ejb-client.properties

An EJB can then be looked up and a method can be invoked on it as follows:

Migrated Configuration

The information needed to connect to the remote server can be specified using a WildFly client configuration file or programmatically.

Configuration File Approach

A wildfly-config.xml file that contains the information needed to connect to the remote server can be added to the client application's META-INF directory:

wildfly-config.xml

An EJB can then be looked up and a method can be invoked on it as follows:

Programmatic Approach

The information needed to connect to the remote server can be specified directly in the client application’s code:

General Utilities

Security Vault Migration

Security Vault is primarily used in legacy configurations, a vault is used to store sensitive strings outside of the configuration files. WildFly server may only contain a single security vault.

Credential Store introduced in WildFly 11 is meant to expand Security Vault in terms of storing different credential types and introduce easy to implemnent SPI which allows to deploy custom implemenations of CredentialStore SPI. Credentials are stored safely encrypted in storage file outside WildFly configuration files. Each WildFly server may contain multiple credential stores.

To easily migrate vault content into credential store we have added "vault" command into WildFly Elytron Tool. The tool could be found at $JBOSS_HOME/bin directory. It has several scripts named "elytron-tool.*" dependent on your platform of choice. One can use also simple form "java -jar $JBOSS_HOME/bin/wildfly-elytron-tool.jar <command> <arguments>" if it better suites ones needs.

Single Security Vault Conversion

To convert single security vault credential store use following example:

- to get sample vault use testing resources of Elytron Tool project from GitHub [1]

Command to run actual conversion:

./bin/elytron-tool.sh vault --enc-dir vault_data/ --keystore vault-jceks.keystore --keystore-password MASK-2hKo56F1a3jYGnJwhPmiF5 --iteration 34 --salt 12345678 --alias test --location cs-v1.store --summary

Output:

Vault (enc-dir="vault_data/";keystore="vault-jceks.keystore") converted to credential store "cs-v1.store"
Vault Conversion summary:
--------------------------------------
Vault Conversion Successful
CLI command to add new credential store:
/subsystem=elytron/credential-store=test:add(relative-to=jboss.server.data.dir,create=true,modifiable=true,location="cs-v1.store",implementation-properties={"keyStoreType"=>"JCEKS"},credential-reference={clear-text="MASK-2hKo56F1a3jYGnJwhPmiF5;12345678;34"})

Use elytron-tool.sh vault --help to get description of all parameters.

Notes:

- Elytron Tool cannot handle very first version of Security Vault data file.
- --keystore-password can come in two forms (1) masked as shown in the example or (2) clear text. Parameter --salt and --iteration are there to supply information to decrypt the masked password or to generate masked password in output. In case --salt and --iteration are omitted default values are used.
- When --summary parameter is specified, one can see nice output with CLI command to be used in WildFly console to add converted credential store to the configuration.

Bulk Security Vault Conversion

There is possibility to convert multiple vaults to credential store using --bulk-convert parameter with description file.
Example of description file from our tests [2]:

# Bulk conversion descriptor
keystore:target/test-classes/vault-v1/vault-jceks.keystore
keystore-password:MASK-2hKo56F1a3jYGnJwhPmiF5
enc-dir:target/test-classes/vault-v1/vault_data/
salt:12345678
iteration:34
location:target/v1-cs-1.store
alias:test

keystore:target/test-classes/vault-v1/vault-jceks.keystore
keystore-password:secretsecret
enc-dir:target/test-classes/vault-v1/vault_data/
location:target/v1-cs-2.store
alias:test

# different vault vault-v1-more
keystore:target/test-classes/vault-v1-more/vault-jceks.keystore
keystore-password:MASK-2hKo56F1a3jYGnJwhPmiF5
enc-dir:target/test-classes/vault-v1-more/vault_data/
salt:12345678
iteration:34
location:target/v1-cs-more.store
alias:test

After each "keystore:" option new conversion starts. All options are mandatory except "salt:", "iteration:" and "properties:"

Execute following command:

./bin/elytron-tool.sh vault --bulk-convert bulk-vault-conversion-desc --summary

Output:

Vault (enc-dir="vault-v1/vault_data/";keystore="vault-v1/vault-jceks.keystore") converted to credential store "v1-cs-1.store"
Vault Conversion summary:
--------------------------------------
Vault Conversion Successful
CLI command to add new credential store:
/subsystem=elytron/credential-store=test:add(relative-to=jboss.server.data.dir,create=true,modifiable=true,location="v1-cs-1.store",implementation-properties={"keyStoreType"=>"JCEKS"},credential-reference={clear-text="MASK-2hKo56F1a3jYGnJwhPmiF5;12345678;34"})
--------------------------------------

Vault (enc-dir="vault-v1/vault_data/";keystore="vault-v1/vault-jceks.keystore") converted to credential store "v1-cs-2.store"
Vault Conversion summary:
--------------------------------------
Vault Conversion Successful
CLI command to add new credential store:
/subsystem=elytron/credential-store=test:add(relative-to=jboss.server.data.dir,create=true,modifiable=true,location="v1-cs-2.store",implementation-properties={"keyStoreType"=>"JCEKS"},credential-reference={clear-text="secretsecret"})
--------------------------------------

Vault (enc-dir="vault-v1-more/vault_data/";keystore="vault-v1-more/vault-jceks.keystore") converted to credential store "v1-cs-more.store"
Vault Conversion summary:
--------------------------------------
Vault Conversion Successful
CLI command to add new credential store:
/subsystem=elytron/credential-store=test:add(relative-to=jboss.server.data.dir,create=true,modifiable=true,location="v1-cs-more.store",implementation-properties={"keyStoreType"=>"JCEKS"},credential-reference={clear-text="MASK-2hKo56F1a3jYGnJwhPmiF5;12345678;34"})
--------------------------------------

The result is conversion of all vaults with proper CLI commands. 

References:

[1] https://github.com/wildfly-security/wildfly-elytron-tool/tree/master/src/test/resources/vault-v1
[2] https://github.com/wildfly-security/wildfly-elytron-tool/blob/master/src/test/java/org/wildfly/security/tool/VaultCommandTest.java

Security Properties

Lets suppose security properties "a" and "c" defined in legacy security:

To define security properties in Elytron subsystem you need to set attribute security-properties of the subsystem:

You can also add or change one another property without modification of others using map operations. Following command will set property "e":

By the same way you can also remove one of properties - in example newly created property "e":

Output XML configuration will be:

SSL Migration

Simple SSL Migration

This section describe securing HTTP connections to the server using SSL using Elytron.
It suppose you have already configured SSL using legacy security-realm, for example by Admin Guide#Enable SSL, and your configuration looks like:

To switch to Elytron you need to:

  1. Create Elytron key-store - specifying where is the keystore file stored and password by which it is encrypted. Default type of keystore generated using keytool is JKS:
  2. Create Elytron key-manager - specifying keystore, alias (using alias-filter) and password of key:
  3. Create Elytron server-ssl-context - specifying only reference to key-manager defined above:
  4. Switch https-listener from legacy security-realm to newly created Elytron ssl-context:
  5. And reload the server:

Output XML configuration of Elytron subsystem should look like:

Output https-listener in Undertow subsystem should be:

Client-Cert SSL Authentication Migration

This suppose you have already configured Client-Cert SSL authentication using truststore in legacy security-realm, for example by Admin Guide#Add Client-Cert to SSL, and your configuration looks like:

Following configuration is sufficient to prevent users without valid certificate and private key to access the server, but it does not provide user identity to the application. That require to define CLIENT_CERT HTTP mechanism / EXTERNAL SASL mechanism, which will be described later.)

At first use steps above to migrate basic part of the configuration. Then continue by following:

  1. Create key-store of truststore - like for keystore above:
  2. Create trust-manager - specifying key-store of trustore, created above:
  3. Modify server-ssl-context to use newly created trustmanager:
  4. Enable client authentication for server-ssl-context:
  5. And reload the server:

Output XML configuration of Elytron subsystem should look like:

SSL with Client Cert Migration

As this documentation is primarily intended for users migrating to WildFly Elytron I am going to jump straight into the configuration required with WildFly Elytron.

This section will cover how to create the various resources required to achieve CLIENT_CERT authentication with fallback to username / password authentication for both HTTP and SASL (i.e. Remoting) - both are being covered at the same time as predominantly they require the same core configuration, it is not until the definition of the authentication factories that the configuration becomes really specific.

The WildFly Elytron project already contains a dummy certificate authority set up that we use for testing, the KeyStores within this documentation are from the dummy certificate authority although for anything other than testing these should be replaced with your own.

As a first step we define some paths that point to the wildfly-elytron project so we can use these in the subsequent configuration.

This results in the following configuration.

KeyStores, KeyManagers, and TrustManagers.

The next step is to define the KeyStore resources, for this example three different keystores are used: -

  1. localhost.keystore - Contains the servers key and certificate for 'localhost'.
  2. beetles.keystore - Contains the individual client certificates.
  3. ca.keystore - Contains the certificate of the certificate authority.

When we define the overall configuration we will use the localhost keystore along with the ca keystore for the incoming connections so initially all client certificates signed by the certificate authority will be accepted and subsequently a security realm will check it against the actual certificates within beetles keystore.

This results in the following definitions: -

Next the key and trust manager resources will be defined using these keystores.

Resulting in: -

Realms and Domains

Two security realms are now defined, one of these uses properties files from within the WildFly Elytron project to support username/password authentication and the other using the clients certificates for verification.

Resulting in: -

These security realms can now be referenced from a security domain: -

Resulting in: -

Before moving onto the individual authentication factories a couple of additional utility resources are also required: -

Resulting in: -

HTTP Authentication Factory

For the HTTP connections we now define a HTTP authentication factory using the previously defined resources and it is configured to support CLIENT_CERT and DIGEST authentication.

Resulting in: -

Where DIGEST authentication is used we rely on the default configuration within the security domain to select the 'test-users' realm, however where CLIENT_CERT authentication is in use an alternative realm-mapper is referenced to ensure the 'key-store-realm' is used.

Additionally for CLIENT_CERT authentication a principal-transformer is referenced to extract the CN attribute from the distinguished name of the client certificate and use this when accessing the identity from the security realm.

SASL Authentication Factory

The architecture of the two authentication factories if very similar so a SASL authentication factory can be defined in the same way as the HTTP equivalent.

This results in: -

Realm mappers and principal transformers are defined in the same way as were defined for HTTP.

SSL Context

An SSL context is also defined for use by the server.

Resulting in: -

As we will be supporting fallback to username/password authentication need-client-auth is set to false as well as authentication-optional being set to false, this allows connections to be established but an alternative form of authentication will be required.

Using for Management

At this point the management interfaces can be updated to use the newly defined resources, we need to add references to the two new authentication factories and the SSL context, we can also remove the existing reference to the legacy security realm. As this is modifying existing interfaces a server reload will also be required.

The management interface configuration then becomes: -

Admin Clients

At this stage assuming the same files have been used as in this example it should be possible to connect to the management interface of the server either using a web browser or the JBoss CLI with the username elytron and password passwd12#$

For certificate based authentication the keys and certificates from the WildFly Elytron tests can be used, these are found in JKS keystores under 'src/test/resources/ca/jks', these keystores have a password of Elytron.

Web Browser Configuration

A PKCS#12 file can be created from the test keystores,this can then be imported into the web browser to use when connecting to the server.

CLI Configuration

Since the integration of WildFly Elytron it is possible with the CLI to use a configuration file wildfly-config.xml to define the security settings including the settings for the client side SSL context.

For the purpose of this example copy the ladybird,keystore and ca.truststore from the Wildfly Elytron testsuite to the location the JBoss CLI is being started from, the following wildfly-config.xml can be created in this location as well: -

The CLI can now be started using the following command: -

The :whoami command can be used within the CLI to double check the current identity.

Documentation Still Needed

  • How to migrate application which uses different identity store for authentication and authorization (migration to Elytron aggregate-realm).
  • How migrate to using cache (migration to caching-realm)
  • Limitations for migration from PicketBox/legacy security to Elytron, for example, Infinispan cache cannot be used, any others?
Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.