Skip to end of metadata
Go to start of metadata

Using the Elytron Subsystem

Set Up and Configure Authentication for Applications

Configure Authentication with a Properties File-Based Identity Store

Create properties files:

You need to create two properties files: one that maps user to passwords and another that maps users to roles. Usually these files are located in the jboss.server.config.dir directory and follow the naming convention *-users.properties and *-roles.properties, but other locations and names may be used. The *-users.properties file must also contain a reference to the properties-realm, which you will create in the next step: #$REALM_NAME=YOUR_PROPERTIES_REALM_NAME$

Example user to password file: example-users.properties

Example user to roles file: example-roles.properties

Configure a properties-realm in WildFly:

The name of the properties-realm is examplePropRealm, which is used in the previous step in the example-users.properties file. Also, if your properties files are located outside of jboss.server.config.dir, then you need to change the path and relative-to values appropriately.

Configure a security-domain:
Configure an http-authentication-factory:

This example shows creating an http-authentication-factory using BASIC authentication, but it could be updated to other mechanisms such as FORM.

Configure an application-security-domain in the Undertow subsystem:
Configure your application's web.xml and jboss-web.xml.

Your application's web.xml and jboss-web.xml must be updated to use the application-security-domain you configured in WildFly. An example of this is available in the Configure Applications to Use Elytron or Legacy Security for Authentication section.

Configure Authentication with a Filesystem-Based Identity Store

Chose a directory for users:

You need a directory where your users will be stored. In this example, we are using a directory called fs-realm-users located in jboss.server.config.dir.

Configure a filesystem-realm in WildFly:

If your directory is located outside of jboss.server.config.dir, then you need to change the path and relative-to values appropriately.

Add a user:

When using the filesystem-realm, you can add users using the management CLI.

Add a simple-role-decoder:

This simple-role-decoder decodes a principal's roles from the Roles attribute. You can change this value if your roles are in a different attribute.

Configure a security-domain:
Configure an http-authentication-factory:

This example shows creating an http-authentication-factory using BASIC authentication, but it could be updated to other mechanisms such as FORM.

Configure an application-security-domain in the Undertow subsystem:
Configure your application's web.xml and jboss-web.xml.

Your application's web.xml and jboss-web.xml must be updated to use the application-security-domain you configured in WildFly. An example of this is available in the Configure Applications to Use Elytron or Legacy Security for Authentication section.

Your application is now using a filesystem-based identity store for authentication.

Configure Authentication with a Database Identity Store

Determine your database format for usernames, passwords, and roles:

To set up authentication using a database for an identity store, you need to determine how your usernames, passwords, and roles are stored in that database. In this example, we are using a single table with the following sample data:

username password roles
user1 password123 Admin
user2 password123 Guest
Configure a datasource:

To connect to a database from WildFly, you must have the appropriate database driver deployed as well as a datasource configured. This example shows deploying the driver for postgres and configuring a datasource in WildFly:

Configure a jdbc-realm in WildFly:

NOTE: The above example shows how to obtain passwords and roles from a single principal-query. You can also create additional principal-query with attribute-mapping attributes if you require multiple queries to obtain roles or additional authentication or authorization information.

Configure a security-domain:
Configure an http-authentication-factory:

This example shows creating an http-authentication-factory using BASIC authentication, but it could be updated to other mechanisms such as FORM.

Configure an application-security-domain in the Undertow subsystem:
Configure your application's web.xml and jboss-web.xml.

Your application's web.xml and jboss-web.xml must be updated to use the application-security-domain you configured in WildFly. An example of this is available in the Configure Applications to Use Elytron or Legacy Security for Authentication section.

Configure Authentication with an LDAP-Based Identity Store

Determine your LDAP format for usernames, passwords, and roles:

To set up authentication using an LDAP server for an identity store, you need to determine how your usernames, passwords, and roles are stored. In this example, we are using the following structure:

Configure a dir-context:

To connect to the LDAP server from WildFly, you need to configure a dir-context that provides the URL as well as the principal used to connect to the server.

Configure an ldap-realm in WildFly:
Add a simple-role-decoder:
Configure a security-domain:
Configure an http-authentication-factory:

This example shows creating an http-authentication-factory using BASIC authentication, but it could be updated to other mechanisms such as FORM.

Configure an application-security-domain in the Undertow subsystem:
Configure your application's web.xml and jboss-web.xml.

Your application's web.xml and jboss-web.xml must be updated to use the application-security-domain you configured in WildFly. An example of this is available in the Configure Applications to Use Elytron or Legacy Security for Authentication section.

IMPORTANT: In cases where you configure an LDAP server in the elytron subsystem for authentication and that LDAP server then becomes unreachable, WildFly will return a 500, or internal server error, error code when attempting authentication using that unreachable LDAP server. This behavior differs from the legacy security subsystem, which will return a 401, or unauthorized, error code under the same conditions.

Configure Authentication with Certificates

IMPORTANT: Before you can set up certificate-based authentication, you must have two-way SSL configured.

Configure a key-store-realm.

You must configure this realm with a truststore that contains the client's certificate. The authentication process uses the same certificate presented by the client during the two-way SSL handshake.

Create a Decoder.

You need to create a x500-attribute-principal-decoder to decode the principal you get from your certificate. The below example will decode the principal based on the first CN value.

For example, if the full DN was CN=client,CN=client-certificate,DC=example,DC=jboss,DC=org, CNDecoder would decode the principal as client. This decoded principal is used as the alias value to lookup a certificate in the truststore configured in ksRealm.

IMPORTANT: The decoded principal *MUST* must be the alias value you set in your server's truststore for the client's certificate.

Add a constant-role-mapper for assigning roles.

This is example uses a constant-role-mapper to assign roles to a principal from ksRealm but other approaches may also be used.

Configure a security-domain.
Configure an http-authentication-factory.
Configure an application-security-domain in the Undertow subsystem.
Update server-ssl-context.
Configure your application's web.xml and jboss-web.xml.

Your application's web.xml and jboss-web.xml must be updated to use the application-security-domain you configured in WildFly. An example of this is available in the Configure Applications to Use Elytron or Legacy Security for Authentication section.

In addition, you need to update your web.xml to use CLIENT-CERT as its authentication method.

Configure Authentication with a Kerberos-Based Identity Store

IMPORTANT: The following steps assume you have a working KDC and Kerberos domain as well as your client browsers configured.

Configure a kerberos-security-factory.
Configure the system properties for Kerberos.

Depending on how your environment is configured, you will need to set some of the system properties below.

System Property Description
java.security.krb5.kdc The host name of the KDC.
java.security.krb5.realm The name of the realm.
java.security.krb5.conf The path to the configuration krb5.conf file.
sun.security.krb5.debug If true, debugging mode will be enabled.

To configure a system property in WildFly:

Configure an Eltyron security realm for assigning roles.

The the client's Kerberos token will provide the principal, but you need a way to map that principal to a role for your application. There are several ways to accomplish this, but this example creates a filesystem-realm, adds a user to the realm that matches the principal from the Kerberos token, and assigns roles to that user.

Add a simple-role-decoder.

This simple-role-decoder decodes a principal's roles from the Roles attribute. You can change this value if your roles are in a different attribute.

Configure a security-domain.
Configure an http-authentication-factory that uses the kerberos-security-factory.
Configure an application-security-domain in the Undertow subsystem:
Configure your application's web.xml, jboss-web.xml and jboss-deployment-structure.xml.

Your application's web.xml and jboss-web.xml must be updated to use the application-security-domain you configured in WildFly. An example of this is available in the Configure Applications to Use Elytron or Legacy Security for Authentication section.

In addition, you need to update your web.xml to use SPNEGO as its authentication method.

Configure Authentication with a Form as a Fallback for Kerberos

Configure kerberos-based authentication.

Configuring kerberos-based authentication is covered in a previous section.

Add a mechanism for FORM authentication in the http-authentication-factory.

You can use the existing http-authentication-factory you configured for kerberos-based authentication and and an additional mechanism for FORM authentication.

Add additional fallback principals.

The existing configuration for kerberos-based authentication should already have a security realm configured for mapping principals from kerberos token to roles for the application. You can add additional users for fallback authentication to that realm. For example if you used a filesystem-realm, you can simply create a new user with the appropriate roles:

Update the web.xml for FORM fallback.

You need to update the web.xml to use the value SPNEGO,FORM for the auth-method, which will use FORM as a fallback authentication method if SPNEGO fails. You also need to specify the location of your login and error pages.

Configure Applications to Use Elytron or Legacy Security for Authentication

After you have configured the elytron or legacy security subsystems for authentication, you need to configure your application to use it.

Configure your application's web.xml.

Your application's web.xml needs to be configured to use the appropriate authentication method. When using elytron, this is defined in the http-authentication-factory you created. When using the legacy security subsystem, this depends on your login module and the type of authentication you want to configure.

Example web.xml with BASIC Authentication

Configure your application to use a security domain.

You can configure your application's jboss-web.xml to specify the security domain you want to use for authentication. When using the elytron subsystem, this is defined when you created the application-security-domain. When using the legacy security subsystem, this is the name of the legacy security domain.

Example jboss-web.xml

Using jboss-web.xml allows you to configure the security domain for a single application only. Alternatively, you can specify a default security domain for all applications using the undertow subsystem. This allows you to omit using jboss-web.xml to configure a security domain for an individual application.

IMPORTANT: Setting default-security-domain in the undertow subsystem will apply to ALL applications. If default-security-domain is set and an application specifies a security domain in a jboss-web.xml file, the configuration in jboss-web.xml will override the default-security-domain in the undertow subsystem.

Using Elytron and Legacy Security Subsystems in Parallel

You can define authentication in both the elytron and legacy security subsystems and use them in parallel. If you use both jboss-web.xml and default-security-domain in the undertow subsystem, WildFly will first try to match the configured security domain in the elytron subsystem. If a match is not found, then WildFly will attempt to match the security domain with one configured in the legacy security subsystem. If the elytron and legacy security subsystem each have a security domain with the same name, the elytron security domain is used.

Override an Application's Authentication Configuration

You can override the authentication configuration of an application with one configured in WildFly. To do this, use the override-deployment-configuration property in the application-security-domain section of the undertow subsystem:

For example, an application is configured to use FORM authentication with the exampleApplicationDomain in its jboss-web.xml.

Example jboss-web.xml

By enabling override-deployment-configuration, you can create a new http-authentication-factory that specifies a different authentication mechanism such as BASIC.

Example http-authentication-factory

This will override the authentication mechanism defined in the application's jboss-web.xml and attempt to authenticate a user using BASIC instead of FORM.

Create and Use a Credential Store

Create credential store.
Add a credential to a credential store.
List all credentials in a credential store.
Remove a credential from a credential store.
Use a credential store.

Set up and Configure Authentication for the Management Interfaces

Secure the Management Interfaces with a New Identity Store

Create a security domain and any supporting security realms, decoders, or mappers for your identity store.

This process is covered in a previous section. For example, if you wanted to secure the management interfaces using a filesystem-based identity store, you would follow the steps in Configure Authentication with a Filesystem-Based Identity Store.

Create an http-authentication-factory or sasl-authentication-factory.

Example http-authentication-factory

Example sasl-authentication-factory

Update the management interfaces to use your http-authentication-factory or sasl-authentication-factory.

Example update http-authentication-factory

Example update sasl-authentication-factory

Silent Authentication

By default, WildFly provides an authentication mechanism for local users, also know as silent authentication, through the local security realm.

Silent authentication must be used via a sasl-authentication-factory.

IMPORTANT: When enabling silent authentication, you must ensure the security domain referenced by your sasl-authentication-factory references a security realm that contains the $local user. By default, WildFly provides the local identity realm that provides this user.

Add silent authentication to an existing sasl-authentication-factory.
Create a new sasl-server-factory with silent authentication.
Remove silent authentication from an existing sasl-server-factory:

Using RBAC with Elytron

RBAC can be configured to automatically assign or exclude roles for users that are members of groups. This is configured in the access-control section of the core management. When the management interfaces are secured with the elytron subsystem, and users are assigned groups when they authenticate. You can also configure roles to be assigned to authenticated users in a variety of ways using the elytron subsystem, for example using a role mapper or a role decoder.

Configure SSL/TLS

Enable One-way SSL/TLS for Applications

In WildFly, you can use the Elytron subsystem, along with the Undertow subsystem, to enable HTTPS for deployed applications.

Obtain or generate your key store:

Before enabling HTTPS in WildFly, you must obtain or generate the keystore you plan on using. To generate an example keystore:

Configure a key-store in WildFly:

The previous command uses an absolute path to the keystore. Alternatively you can use the relative-to attribute to specify the base directory variable and path specify a relative path.

Configure a key-manager in that references your key-store:

IMPORTANT: You need to know what key manager algorithms are provided by the JDK you are using. For example, a JDK that uses SunJSSE provides the PKIX and SunX509 algorithms. The example command below uses SunX509 for the key manager algorithm.

Configure a server-ssl-context in that references your key-manager:

IMPORTANT: You need to determine what HTTPS protocols you want to support. The example commands below use TLSv1.2.

Check and see if the https-listener is configured to use a legacy security realm for its SSL configuration:

The above command shows that the https-listener is configured to use the ApplicationRealm legacy security realm for its SSL configuration. Undertow cannot reference both a legacy security realm and an ssl-context in Elytron at the same time so you must remove the reference to the legacy security realm.

If the result is undefined, you can skip the next step.

Remove the reference to the legacy security realm:
Update the https-listener to use the ssl-context from Elytron:
Reload the server:

HTTPS is now enabled for applications.

Enable Two-way SSL/TLS in WildFly for Applications

In WildFly, you can use the Elytron subsystem, along with the Undertow subsystem, to enable two-way SSL/TLS for deployed applications.

Obtain or generate your keystore:

Before enabling HTTPS in WildFly, you must obtain or generate the keystores, truststores and certificates you plan on using.

Create server and client keystores:

Export the server and client certificates:

Import the sever and client certificates into the opposing truststores:

Configure a key-store for server keystore and truststore in WildFly:

NOTE
The previous command uses an absolute path to the keystore. Alternatively you can use the relative-to attribute to specify the base directory variable and path specify a relative path.

Configure a key-manager in that references your key store key-store:

IMPORTANT
You need to know what key manager algorithms are provided by the JDK you are using. For example, a JDK that uses SunJSSE provides the PKIX and SunX509 algorithms.

The example command below uses SunX509 for the key manager algorithm.

Configure a trust-manager in that references your truststore key-store:

IMPORTANT
You need to know what key manager algorithms are provided by the JDK you are using. For example, a JDK that uses SunJSSE provides the PKIX and SunX509 algorithms.

The example command below uses SunX509 for the key manager algorithm.

Configure a server-ssl-context in that references your key-manager, trust-manager, and enables client authentication:

IMPORTANT
You need to determine what HTTPS protocols you want to support. The example commands below use TLSv1.2.

Check and see if the https-listener is configured to use a legacy security realm for its SSL configuration:

The above command shows that the https-listener is configured to use the ApplicationRealm legacy security realm for its SSL configuration. Undertow cannot reference both a legacy security realm and an ssl-context in Elytron at the same time so you must remove the reference to the legacy security realm.

NOTE
If the result is undefined, you can skip the next step.

Remove the reference to the legacy security realm:
Update the https-listener to use the ssl-context from Elytron:
Reload the server
Configure your client to use the client certificate

You need to configure your client to present the trusted client certificate to the server to complete the two-way SSL/TLS authentication. For example, if using a browser, you need to import the trusted certificate into the browser’s truststore.

Two-Way HTTPS is now enabled for applications.

Enable One-way SSL/TLS for the Management Interfaces Using the Elytron Subsystem

Obtain or generate your key store:

Before enabling HTTPS in WildFly, you must obtain or generate the key store you plan on using. To generate an example key store, use the following command.

Create a key-store, key-manager, and server-ssl-context.

IMPORTANT: You need to know what key manager algorithms are provided by the JDK you are using. For example, a JDK that uses SunJSSE provides the PKIX and SunX509 algorithms. You also need to determine what HTTPS protocols you want to support. The example commands above use TLSv1.2.

NOTE: The above command uses relative-to to reference the location of the keystore file. Alternatively, you can specify the full path to the keystore in path and omit relative-to.

Enable HTTPS on the management interface.
Reload the WildFly instance.

HTTPS is now enabled for the management interfaces.

Enable Two-way SSL/TLS for the Management Interfaces using the Elytron Subsystem

Obtain or generate your key store.

Before enabling HTTPS in WildFly, you must obtain or generate the key stores, trust stores and certificates you plan on using. To generate an example set of key stores, trust stores, and certificates use the following commands.

Generate your server and client key stores.

Export your server and client certificates.

Import the sever and client certificates into the opposing trust stores.

Configure key-store, a key-manager, trust-manager, and server-ssl-context for the server key store and trust store.

IMPORTANT: You need to know what key manager algorithms are provided by the JDK you are using. For example, a JDK that uses SunJSSE provides the PKIX and SunX509 algorithms. You also need to determine what HTTPS protocols you want to support. The example commands above use TLSv1.2.

NOTE: The above command uses relative-to to reference the location of the keystore file. Alternatively, you can specify the full path to the keystore in path and omit relative-to.

Enable HTTPS on the management interface.
Reload the WildFly instance.
Configure your client to use the client certificate.

You need to configure your client to present the trusted client certificate to the server to complete the two-way SSL/TLS authentication. For example, if using a browser, you need to import the trusted certificate into the browser’s trust store.

Two-way SSL/TLS is now enabled for the management interfaces.

Using an ldap-key-store

An ldap-key-store allows you to use a keystore stored in an LDAP server. You can use an ldap-key-store in same way you can use a key-store.

To create and use an ldap-key-store:

Configure a dir-context.

To connect to the LDAP server from WildFly, you need to configure a dir-context that provides the URL as well as the principal used to connect to the server.

Example dir-context

Configure an ldap-key-store.

When configure an ldap-key-store, you need to specify both the dir-context used to connect to the LDAP server as well as how to locate the keystore stored in the LDAP server. At a minimum, this requires you specify a search-path.

Example ldap-key-store

Use the ldap-key-store.

Once you have defined your ldap-key-store, you can use it in the same places where a key-store could be used. For example, you could use an ldap-key-store when configuring HTTPS and Two-Way HTTPS for applications.

Using a filtering-key-store

A filtering-key-store allows you to expose a subset of aliases from an existing key-store, and use it in the same places you could use a key-store. For example, if a keystore contained alias1, alias2, and alias3, but you only wanted to expose alias1 and alias3, a filtering-key-store provides you several ways to do that.

To create a filtering-key-store:

Configure a key-store.
Configure a filtering-key-store.

When you configure a filtering-key-store, you specify which key-store you want to filter and the alias-filter for filtering aliases from the key-store. The filter can be specified in one of the following formats:

  • alias1,alias3, which is a comma-delimited list of aliases to expose.
  • ALL:-alias2, which exposes all aliases in the keystore except the ones listed.
  • NONE:+alias1:+alias3, which exposes no aliases in the keystore except the ones listed.

This example uses a comma-delimted list to expose alias1 and alias3.

Use the filtering-key-store.

Once you have defined your filtering-key-store, you can use it in the same places where a key-store could be used. For example, you could use a filtering-key-store when configuring HTTPS and Two-Way HTTPS for applications.

Reload a Keystore

You can reload a keystore configured in WildFly from the management CLI. This is useful in cases where you have made changes to certificates referenced by a keystore.

To reload a keystore.

Check the Content of a Keystore by Alias

If you add a keystore to the elytron subsystem using the key-store component, you can check the keystore's contents using the alias child element and reading its attributes.

For example:

The following attributes can be read:

Attribute Description
certificate The certificate associated with the alias. If the alias has a certificate chain this will always be undefined.
certificate-chain The certificate chain associated with the alias.
creation-date The creation date of the entry represented by this alias.
entry-type The type of the entry for this alias. Available types: PasswordEntry, PrivateKeyEntry, SecretKeyEntry, TrustedCertificateEntry, and Other. Unrecognized types will be reported as Other.

Custom Components

When configuring SSL/TLS in the elytron subsystem, you can provide and use custom implementations of the following components:

  • key-store
  • key-managers
  • trust-managers
  • client-ssl-context
  • server-ssl-context

When creating custom implementations of Elytron components, they must present the appropriate capabilities and requirements.

Configuring the Elytron and Security Subsystems

Enable and Disable the Elytron Subsystem

To add the elytron extension required for the elytron subsystem:
To enable the Elytron subsystem in WildFly:
To disable the Elytron subsystem in WildFly:

IMPORTANT: Other subsystems within WildFly may have dependencies on the elytron subsystem. If these dependencies are not resolved before disabling it, you will see errors when starting WildFly.

Enable and Disable the Security Subsystem

To disable the security subsystem in WildFly:

IMPORTANT: Other subsystems within WildFly may have dependencies on the security subsystem. If these dependencies are not resolved before disabling it, you will see errors when starting WildFly.

To enable the security subsystem in WildFly:

Use the Elytron and Security Subsystems in Parallel

By default the elytron and security subsystems will run in parallel if both are enabled. For authentication in applications, you can use the application-security-domain property in the undertow subsystem to configure a security domain in the elytron subsystem.

NOTE: This must match the security-domain configured in the jboss-web.xml of your application.

If the application-security-domain is not set, WildFly will look for a security domain configured in the security subsystem that matches the security-domain configured in the jboss-web.xml of your application.

For enabling HTTPS using a legacy security realm, you can use the security-realm attribute in the https-listener section of the undertow subsystem:

For enabling HTTPS using elytron, you need to undefine the security-realm attribute and set the ssl-context attribute.

Creating Elytron Subsystem Components

Create an Elytron Security Realm

Security realms in the Elytron subsystem, when used in conjunction with security domains, are use for both core management authentication as well as for authentication with applications. Security realms are also specifically typed based on their identity store, for example jdbc-realm, filesystem-realm, properties-realm, etc.

Adding a security realm takes the general form:

Examples of adding specific realms, such as jdbc-realm, filesystem-realm, and properties-realm can be found in previous sections.

Create an Elytron Role Decoder

A role decoder converts attributes from the identity provided by the security realm into roles. Role decoders are also specifically typed based on their functionality, for example empty-role-decoder, simple-role-decoder, and custom-role-decoder.

Adding a role decoder takes the general form:

Create an Elytron Permission Mapper

In addition to roles being assigned to a identity, permissions may also be assigned. A permission mapper assigns permissions to an identity. Permission mappers are also specifically typed based on their functionality, for example logical-permission-mapper, simple-permission-mapper, and custom-permission-mapper.

Adding a permission mapper takes the general form:

Create an Elytron Role Mapper

A role mapper maps roles after they have been decoded to other roles. Examples include normalizing role names or adding and removing specific roles from principals after they have been decoded. Role mappers are also specifically typed based on their functionality, for example add-prefix-role-mapper, add-suffix-role-mapper, and constant-role-mapper.

Adding a role mapper takes the general form:

Create an Elytron Security Domain

Security domains in the Elytron subsystem, when used in conjunction with security realms, are use for both core management authentication as well as for authentication with applications.

Adding a security domain takes the general form:

Create an Elytron Authentication Factory

An authentication factory is an authentication policy used for specific authentication mechanisms. Authenticaion factories are specifically based on the authentication mechanism, for example http-authentication-factory and
sasl-authentication-factory and kerberos-security-factory.

Adding an authentication factory takes the general form:

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.