WildFly Elytron Security - Latest WildFly Documentation

About

The WildFly Elytron project is a new security framework brought to WildFly to provide a single unified security framework across the whole of the application server. As a single framework it will be usable both for configuring management access to the server and for applications deployed to the server, it will also be usable across all process types so there will be no need to learn a different security framework for host controllers in a domain compared to configuring a standalone server.

The project covers these main areas: -

Authentication
Authorization
SSL / TLS
Secure Credential Storage

Authentication

One of the fundamental objectives of the project was to ensure that we can use stronger authentication mechanisms for both HTTP and SASL based authentication, in both cases the new framework also makes it possible to bring in new implementations opening up various integration opportunities with external solutions.

Authorization

The architecture of the project makes a very clear distinction between the raw representation of the identity as returned by a SecurityRealm from the repository of identities and the final representation as a SecurityIdentity after roles have been decoded and mapped and permissions have been mapped.

Custom implementations of the components to perform role decoding and mapping, and permission mapping can be provided allowing for further flexibility beyond the default set of components provided by the project.

SSL / TLS

The project becomes the centralised point within the application server for configuring SSL related resources meaning they can be configured in a central location and referenced by resources across the application server. The centralised configuration also covers advanced options such as configuration of enabled cipher suites and protocols without this information needing to be distributed across the management model.

The SSL / TLS implementation also includes an optimisation where it can be closely tied to authentication allowing for permissions checks to be performed on establishment of a connection before the first request is received and the eager construction of a SecurityIdentity eliminating the need for it to be constructed on a per-request basis.

Secure Credential Storage

The previous vault used for plain text String encryption is replaced with a newly designed credential store. in addition to the protection it offers for the credentials stored within it, the store currently supports storage of clear text credentials.

General Elytron Architecture

The overall architecture for WildFly Elytron is building up a full security policy from assembling smaller components together, by default we include various implementations of the components - in addition to this, custom implementations of many components can be provided in order to provide more specialised implementations.

Within WildFly the different Elytron components are handled as capabilities meaning that different implementations can be mixed and matched, however the different implementations are modelled using distinct resources. This section contains a number of diagrams to show the general relationships between different components to provide a high level view, however the different resource definitions may use different dependencies depending on their purpose.

Security Domains

Within WildFly Elytron a SecurityDomain can be considered as a security policy backed by one or more SecurityRealm instances. Resources that make authorization decisions will be associated with a SecurityDomain, from the SecurityDomain a SecurityIdentity can be obtained which is a representation of the current identity, from this the identities roles and permissions can be checked to make the authorization decision for the resource.

SecurityDomain

The SecurityDomain is the general wrapper around the policy describing a resulting SecurityIdentity and makes use of the following components to define this policy.

NameRewriter

NameRewriters are used in multiple places within the Elytron configuration, as their name implies, their purpose is to take a name and map it to another representation of the name or perform some normalisation or clean up of the name.

RealmMapper

As a SecurityDomain is able to reference multiple SecurityRealms the RealmMapper is responsible for identifying which SecurityRealm to use based on the supplied name for authentication.

SecurityRealm

One more more named SecurityRealms are associated with a SecurityDomain, the SecurityRealms are the access to the underlying repository of identities and are used for obtaining credentials to allow authentication mechanisms to perform verification, for validation of Evidence and for obtaining the raw AuthorizationIdentity performing the authentication.

Some SecurityRealm implementations are also modifiable so expose an API that allows for updates to be made to the repository containing the identities.

RoleDecoder

Along with the SecurityRealm association is also a reference to a RoleDecoder, the RoleDecoder takes the raw AuthorizationIdentity returned from the SecurityRealm and converts it's attributes into roles.

RoleMapper

After the roles have been decoded for an identity further mapping can be applied, this could be as simple at normalising the format of the names through to adding or removing specific role names. If a RoleMapper is referenced by the SecurityRealm association that RoleMapper is applied first before applying the RoleMapper associated with the SecurityDomain.

PrincipalDecoder

A PrincipalDecoder converts from a Principal to a String representation of a name, one example for this is we have an X500PrincipalDecoder which is able to extract an attribute from a distinguished name.

PermissionMapper

In addition to having roles a SecurityIdentity can also have a set of permissions, the PermissionMapper assigns those permissions to the identity.

Different secured resources can be associated with different SecurityDomains for their authorization decisions, within WildFly Elytron we have the ability to configure inflow between different SecurityDomains. The inflow process means that a SecurityIdentity inflowed into a second SecurityDomain has the mappings of the new SecurityDomain applied to it so although a common identity may be calling different resources each of those resources could have a very different view.

SASL Authentication

The SaslAuthenticationFactory is an authentication policy for authentication using SASL authentication mechanisms, in addition to being a policy it is also a factory for configured authentication mechanisms backed by a SecurityDomain.

SaslAuthenticationFactory

The SaslAuthenticationFactory references the following: -

SecurityDomain

This is the security domain that any mechanism authentication will be performed against.

SaslServerFactory

This is the general factory for server side SASL authentication mechanisms.

MechanismConfigurationSelector

Additional configuration can be supplied for the authentication mechanisms, the configuration will be described in more detail later but the purpose of the MechanismConfigurationSelector is to obtain configuration specific to the mechanism selected. This can include information about realm names a mechanism should present to a remote client plus additional NameRewriters and RealmMappers to use during the authentication process.

The reason some of the components referenced by the SecurityDomain are duplicated is so that mechanism specific mappings can be applied.

HTTP Authentication

The HttpAuthenticationFactory is an authentication policy for authentication using HTTP authentication mechanisms, in addition to being a policy it is also a factory for configured authentication mechanisms backed by a SecurityDomain.

HttpAuthenticationFactory

The HttpAuthenticationFactory references the following: -

SecurityDomain

This is the security domain that any mechanism authentication will be performed against.

HttpServerAuthenticationMechanismFactory

This is the general factory for server side HTTP authentication mechanisms.

MechanismConfigurationSelector

The reason some of the components referenced by the SecurityDomain are duplicated is so that mechanism specific mappings can be applied.

SSL / TLS

The SSLContext defined within Elytron is a javax.net.ssl.SSLContext meaning it can be used by anything that uses an SSLContext directly.

SSLContext

In addition to the usual configuration for an SSLContext it is possible to configure additional items such as cipher suites and protocols and the SSLContext returned will wrap any engines created to set these values.

The SSLContext within Elytron can also reference the following: -

KeyManagers

An array of KeyManager instances to be used by the SSLContext, this in turn can reference a KeyStore to load the keys.

TrustManagers

An array of TrustManager instances to be used by the SSLContext, this in turn can also reference a KeyStore to load the certificates.

SecurityDomain

This is optional, however if an SSLContext is configured to reference a SecurityDomain then verification of a clients certificate can be performed as an authentication ensuring the appropriate permissions to Logon are assigned before even allowing the connection to be fully opened, additionally the SecurityIdentity can be established at the time the connection is opened and used for any invocations over the connection.

Elytron Subsystem

WildFly Elytron is a security framework used to unify security across the entire application server. The elytron subsystem enables a single point of configuration for securing both applications and the management interfaces. WildFly Elytron also provides a set of APIs and SPIs for providing custom implementations of functionality and integrating with the elytron subsystem.

In addition, there are several other important features of the WildFly Elytron:

Stronger authentication mechanisms for HTTP and SASL authentication.
Improved architecture that allows for SecurityIdentities to be propagated across security domains and transparently transformed ready to be used for authorization. This transformation takes place using configurable role decoders, role mappers, and permission mappers.
Centralized point for SSL/TLS configuration including cipher suites and protocols.
SSL/TLS optimizations such as eager SecureIdentity construction and closely tying authorization to establishing an SSL/TLS connection. Eager SecureIdentity construction eliminates the need for a SecureIdentity to be constructed on a per-request basis. Closely tying authentication to establishing an SSL/TLS connection enables permission checks to happen BEFORE the first request is received.
A secure credential store that replaces the previous vault implementation to store clear text credentials.

The new elytron subsystem exists in parallel to the legacy security subsystem and legacy core management authentication. Both the legacy and Elytron methods may be used for securing the management interfaces as well as providing security for applications.

Get Started using the Elytron Subsystem

To get started using Elytron, refer to these topics:

Use the default Elytron components for application and management authentication
Secure an application with a new identity store stored in a filesystem or database.
Set up one-way SSL/TLS for applications or the management interfaces.
Set up two-way SSL/TLS for applications or the management interfaces.
Create a credential store and use it with your SSL/TLS configuration.
Use certificate-based authentication with applications.
Override an application's authentication configuration with Elytron authentication.
Configure Kerberos authentication for applications.
Secure applications and the management interfaces with an LDAP-based identity store.

Provided components

Wildfly Elytron provides a default set of implementations in the elytron subsystem.

Factories

Component	Description
aggregate-http-server-mechanism-factory	An HTTP server factory definition where the HTTP server factory is an aggregation of other HTTP server factories.
aggregate-sasl-server-factory	A SASL server factory definition where the SASL server factory is an aggregation of other SASL server factories.
configurable-http-server-mechanism-factory	A SASL server factory definition where the SASL server factory is an aggregation of other SASL server factories.
configurable-sasl-server-factory	A SASL server factory definition where the SASL server factory is an aggregation of other SASL server factories.
custom-credential-security-factory	A custom credential SecurityFactory definition.
http-authentication-factory	Resource containing the association of a security domain with a HttpServerAuthenticationMechanismFactory.
kerberos-security-factory	A security factory for obtaining a GSSCredential for use during authentication.
mechanism-provider-filtering-sasl-server-factory	A SASL server factory definition that enables filtering by provider where the factory was loaded using a provider.
provider-http-server-mechanism-factory	An HTTP server factory definition where the HTTP server factory is an aggregation of factories from the provider list.
provider-sasl-server-factory	A SASL server factory definition where the SASL server factory is an aggregation of factories from the provider list.
sasl-authentication-factory	Resource containing the association of a security domain with a SaslServerFactory.
service-loader-http-server-mechanism-factory	An HTTP server factory definition where the HTTP server factory is an aggregation of factories identified using a ServiceLoader
service-loader-sasl-server-factory	A SASL server factory definition where the SASL server factory is an aggregation of factories identified using a ServiceLoader

Principal Transformers

Component	Description
aggregate-principal-transformer	A principal transformer definition where the principal transformer is an aggregation of other principal transformers.
chained-principal-transformer	A principal transformer definition where the principal transformer is a chaining of other principal transformers.
constant-principal-transformer	A principal transformer definition where the principal transformer always returns the same constant.
custom-principal-transformer	A custom principal transformer definition.
regex-principal-transformer	A regular expression based principal transformer
regex-validating-principal-transformer	A regular expression based principal transformer which uses the regular expression to validate the name.

Principal Decoders

Component	Description
aggregate-principal-decoder	A principal decoder definition where the principal decoder is an aggregation of other principal decoders.
concatenating-principal-decoder	A principal decoder definition where the principal decoder is a concatenation of other principal decoders.
constant-principal-decoder	Definition of a principal decoder that always returns the same constant.
custom-principal-decoder	Definition of a custom principal decoder.
x500-attribute-principal-decoder	Definition of a X500 attribute based principal decoder.

Realm Mappers

Component	Description
constant-realm-mapper	Definition of a constant realm mapper that always returns the same value.
custom-realm-mapper	Definition of a custom realm mapper
mapped-regex-realm-mapper	Definition of a realm mapper implementation that first uses a regular expression to extract the realm name, this is then converted using the configured mapping of realm names.
simple-regex-realm-mapper	Definition of a simple realm mapper that attempts to extract the realm name using the capture group from the regular expression, if that does not provide a match then the delegate realm mapper is used instead.

Realms

Component	Description
aggregate-realm	A realm definition that is an aggregation of two realms, one for the authentication steps and one for loading the identity for the authorization steps.
caching-realm	A realm definition that enables caching to another security realm. Caching strategy is Least Recently Used where least accessed entries are discarded when maximum number of entries is reached.
custom-modifiable-realm	Custom realm configured as being modifiable will be expected to implement the ModifiableSecurityRealm interface. By configuring a realm as being modifiable management operations will be made available to manipulate the realm.
custom-realm	A custom realm definitions can implement either the s SecurityRealm interface or the ModifiableSecurityRealm interface. Regardless of which interface is implemented management operations will not be exposed to manage the realm. However other services that depend on the realm will still be able to perform a type check and cast to gain access to the modification API.
filesystem-realm	A simple security realm definition backed by the filesystem.
identity-realm	A security realm definition where identities are represented in the management model.
jdbc-realm	A security realm definition backed by database using JDBC.
key-store-realm	A security realm definition backed by a keystore.
ldap-realm	A security realm definition backed by LDAP.
properties-realm	A security realm definition backed by properties files.
token-realm	A security realm definition capable of validating and extracting identities from security tokens.
trust-managers	A trust manager definition for creating the TrustManager list as used to create an SSL context.

Permission Mappers

Component	Description
custom-permission-mapper	Definition of a custom permission mapper.
logical-permission-mapper	Definition of a logical permission mapper.
simple-permission-mapper	Definition of a simple configured permission mapper.
constant-permission-mapper	Definition of a permission mapper that always returns the same constant.

Role Decoders

Component	Description
custom-role-decoder	Definition of a custom RoleDecoder
simple-role-decoder	Definition of a simple RoleDecoder that takes a single attribute and maps it directly to roles.

Role Mappers

Component	Description
add-prefix-role-mapper	A role mapper definition for a role mapper that adds a prefix to each provided.
add-suffix-role-mapper	A role mapper definition for a role mapper that adds a suffix to each provided.
constant-role-mapper	A role mapper definition where a constant set of roles is always returned.
aggregate-role-mapper	A role mapper definition where the role mapper is an aggregation of other role mappers.
logical-role-mapper	A role mapper definition for a role mapper that performs a logical operation using two referenced role mappers.
custom-role-mapper	Definition of a custom role mapper

SSL Components

Component	Description
client-ssl-context	An SSLContext for use on the client side of a connection.
filtering-key-store	A filtering keystore definition, which provides a keystore by filtering a key-store.
key-managers	A key manager definition for creating the key manager list as used to create an SSL context.
key-store	A keystore definition.
ldap-key-store	An LDAP keystore definition, which loads a keystore from an LDAP server.
server-ssl-context	An SSL context for use on the server side of a connection.

Other

Component	Description
aggregate-providers	An aggregation of two or more Provider[] resources.
authentication-configuration	An individual authentication configuration definition, which is used by clients deployed to Wildfly and other resources for authenticating when making a remote connection.
authentication-context	An individual authentication context definition, which is used to supply an ssl-context and authentication-configuration when clients deployed to Wildfly and other resources make a remoting connection.
credential-store	Credential store to keep alias for sensitive information such as passwords for external services.
dir-context	The configuration to connect to a directory (LDAP) server.
provider-loader	A definition for a provider loader.
security-domain	A security domain definition.
security-property	A definition of a security property to be set.

Out of the Box Configuration

WildFly provides a set of components configured by default. While these components are ready to use, the legacy security subsystem and legacy core management authentication is still used by default. To configure WildFly to use the these configured components as well as create new ones, see the Using the Elytron Subsystem section.

Default Component	Description
ApplicationDomain	The ApplicationDomain security domain uses ApplicationRealm and groups-to-roles for authentication. It also uses default-permission-mapper to assign the login permission.
ManagementDomain	The ManagementDomain security domain uses two security realms for authentication: ManagementRealm with groups-to-roles and local with super-user-mapper. It also uses default-permission-mapper to assign the login permission.
local (security realm)	The local security realm does no authentication and sets the identity of principals to $local
ApplicationRealm	The ApplicationRealm security realm is a properties realm that authenticates principals using application-users.properties and assigns roles using application-roles.properties. These files are located under jboss.server.config.dir, which by default, maps to EAP_HOME/standalone/configuration. They are also the same files used by the legacy security default configuration.
ManagementRealm	The ManagementRealm security realm is a properties realm that authenticates principals using mgmt-users.properties and assigns roles using mgmt-groups.properties. These files are located under jboss.server.config.dir, which by default, maps to EAP_HOME/standalone/configuration. They are also the same files used by the legacy security default configuration.
default-permission-mapper	The default-permission-mapper mapper is a constant permission mapper that uses org.wildfly.security.auth.permission.LoginPermission to assign the login permission and org.wildfly.extension.batch.jberet.deployment.BatchPermission to assign permission for batch jobs. The batch permissions are start, stop, restart, abandon, and read which aligns with javax.batch.operations.JobOperator.
local (mapper)	The local mapper is a constant role mapper that maps to the local security realm. This is used to map authentication to the local security realm.
groups-to-roles	The groups-to-roles mapper is a simple-role-decoder that will decode the groups information of a principal and use it for the role information.
super-user-mapper	The super-user-mapper mapper is a constant role mapper that maps the SuperUser role to a principal.
management-http-authentication	The management-http-authentication http-authentication-factory can be used for doing authentication over http. It uses the global provider-http-server-mechanism-factory to filter authentication mechanism and uses ManagementDomain for authenticating principals. It accepts the DIGEST authentication mechanisms and exposes it as ManagementRealm to applications.
application-http-authentication	The application-http-authentication http-authentication-factory can be used for doing authentication over http. It uses the global provider-http-server-mechanism-factory to filter authentication mechanism and uses ApplicationDomain for authenticating principals. It accepts BASIC and FORM authentication mechanisms and exposes BASIC as Application Realm to applications.
global (provider-http-server-mechanism-factory)	This is the HTTP server factory mechanism definition used to list the provided authentication mechanisms when creating an http authentication factory.
management-sasl-authentication	The management-sasl-authentication sasl-authentication-factory can be used for authentication using SASL. It uses the configured sasl-server-factory to filter authentication mechanisms, which also uses the global provider-sasl-server-factory to filter by provider names. management-sasl-authentication uses the ManagementDomain security domain for authentication of principals. It also maps authentication using JBOSS-LOCAL-USER mechanisms using the local realm mapper and authentication using DIGEST-MD5 to ManagementRealm.
application-sasl-authentication	The application-sasl-authentication sasl-authentication-factory can be used for authentication using SASL. It uses the configured sasl-server-factory to filter authentication mechanisms, which also uses the global provider-sasl-server-factory to filter by provider names. application-sasl-authentication uses the ApplicationDomain security domain for authentication of principals.
global (provider-sasl-server-factory)	This is the SASL server factory definition used to create SASL authentication factories.
elytron (mechanism-provider-filtering-sasl-server-factor)	This is used to filter which sasl-authentication-factory is used based on the provider. In this case, elytron will match on the WildFlyElytron provider name.
configured (configurable-sasl-server-factory)	This is used to filter sasl-authentication-factory is used based on the mechanism name. In this case, configured will match on JBOSS-LOCAL-USER and DIGEST-MD5. It also sets the wildfly.sasl.local-user.default-user to $local.
combined-providers	Is an aggregate provider that aggreates the elytron and openssl provider loaders.
elytron	A provider loader
openssl	A provider loader

Default WildFly Configuration

/subsystem=elytron:read-resource(recursive=true)
{
    "outcome" => "success",
    "result" => {
        "default-authentication-context" => undefined,
        "final-providers" => undefined,
        "initial-providers" => "combined-providers",
        "add-prefix-role-mapper" => undefined,
        "add-suffix-role-mapper" => undefined,
        "aggregate-http-server-mechanism-factory" => undefined,
        "aggregate-principal-decoder" => undefined,
        "aggregate-principal-transformer" => undefined,
        "aggregate-providers" => {"combined-providers" => {"providers" => [
            "elytron",
            "openssl"
        ]}},
        "aggregate-realm" => undefined,
        "aggregate-role-mapper" => undefined,
        "aggregate-sasl-server-factory" => undefined,
        "authentication-configuration" => undefined,
        "authentication-context" => undefined,
        "caching-realm" => undefined,
        "chained-principal-transformer" => undefined,
        "client-ssl-context" => undefined,
        "concatenating-principal-decoder" => undefined,
        "configurable-http-server-mechanism-factory" => undefined,
        "configurable-sasl-server-factory" => {"configured" => {
            "filters" => [
                {"pattern-filter" => "JBOSS-LOCAL-USER"},
                {"pattern-filter" => "DIGEST-MD5"}
            ],
            "properties" => {"wildfly.sasl.local-user.default-user" => "$local"},
            "protocol" => undefined,
            "sasl-server-factory" => "elytron",
            "server-name" => undefined
        }},
        "constant-permission-mapper" => {"default-permission-mapper" => {"permissions" => [
            {"class-name" => "org.wildfly.security.auth.permission.LoginPermission"},
            {
                "class-name" => "org.wildfly.extension.batch.jberet.deployment.BatchPermission",
                "module" => "org.wildfly.extension.batch.jberet",
                "target-name" => "*"
            }
        ]}},
        "constant-principal-decoder" => undefined,
        "constant-principal-transformer" => undefined,
        "constant-realm-mapper" => {"local" => {"realm-name" => "local"}},
        "constant-role-mapper" => {"super-user-mapper" => {"roles" => ["SuperUser"]}},
        "credential-store" => undefined,
        "custom-credential-security-factory" => undefined,
        "custom-modifiable-realm" => undefined,
        "custom-permission-mapper" => undefined,
        "custom-principal-decoder" => undefined,
        "custom-principal-transformer" => undefined,
        "custom-realm" => undefined,
        "custom-realm-mapper" => undefined,
        "custom-role-decoder" => undefined,
        "custom-role-mapper" => undefined,
        "dir-context" => undefined,
        "filesystem-realm" => undefined,
        "filtering-key-store" => undefined,
        "http-authentication-factory" => {
            "management-http-authentication" => {
                "http-server-mechanism-factory" => "global",
                "mechanism-configurations" => [{
                    "mechanism-name" => "DIGEST",
                    "mechanism-realm-configurations" => [{"realm-name" => "ManagementRealm"}]
                }],
                "security-domain" => "ManagementDomain"
            },
            "application-http-authentication" => {
                "http-server-mechanism-factory" => "global",
                "mechanism-configurations" => [
                    {
                        "mechanism-name" => "BASIC",
                        "mechanism-realm-configurations" => [{"realm-name" => "Application Realm"}]
                    },
                    {"mechanism-name" => "FORM"}
                ],
                "security-domain" => "ApplicationDomain"
            }
        },
        "identity-realm" => {"local" => {
            "attribute-name" => undefined,
            "attribute-values" => undefined,
            "identity" => "$local"
        }},
        "jdbc-realm" => undefined,
        "kerberos-security-factory" => undefined,
        "key-managers" => undefined,
        "key-store" => undefined,
        "key-store-realm" => undefined,
        "ldap-key-store" => undefined,
        "ldap-realm" => undefined,
        "logical-permission-mapper" => undefined,
        "logical-role-mapper" => undefined,
        "mapped-regex-realm-mapper" => undefined,
        "mechanism-provider-filtering-sasl-server-factory" => {"elytron" => {
            "enabling" => true,
            "filters" => [{"provider-name" => "WildFlyElytron"}],
            "sasl-server-factory" => "global"
        }},
        "properties-realm" => {
            "ApplicationRealm" => {
                "groups-attribute" => "groups",
                "groups-properties" => {
                    "path" => "application-roles.properties",
                    "relative-to" => "jboss.server.config.dir"
                },
                "users-properties" => {
                    "path" => "application-users.properties",
                    "relative-to" => "jboss.server.config.dir",
                    "digest-realm-name" => "ApplicationRealm"
                }
            },
            "ManagementRealm" => {
                "groups-attribute" => "groups",
                "groups-properties" => {
                    "path" => "mgmt-groups.properties",
                    "relative-to" => "jboss.server.config.dir"
                },
                "users-properties" => {
                    "path" => "mgmt-users.properties",
                    "relative-to" => "jboss.server.config.dir",
                    "digest-realm-name" => "ManagementRealm"
                }
            }
        },
        "provider-http-server-mechanism-factory" => {"global" => {"providers" => undefined}},
        "provider-loader" => {
            "elytron" => {
                "class-names" => undefined,
                "configuration" => undefined,
                "module" => "org.wildfly.security.elytron",
                "path" => undefined,
                "relative-to" => undefined
            },
            "openssl" => {
                "class-names" => undefined,
                "configuration" => undefined,
                "module" => "org.wildfly.openssl",
                "path" => undefined,
                "relative-to" => undefined
            }
        },
        "provider-sasl-server-factory" => {"global" => {"providers" => undefined}},
        "regex-principal-transformer" => undefined,
        "regex-validating-principal-transformer" => undefined,
        "sasl-authentication-factory" => {
            "management-sasl-authentication" => {
                "mechanism-configurations" => [
                    {
                        "mechanism-name" => "JBOSS-LOCAL-USER",
                        "realm-mapper" => "local"
                    },
                    {
                        "mechanism-name" => "DIGEST-MD5",
                        "mechanism-realm-configurations" => [{"realm-name" => "ManagementRealm"}]
                    }
                ],
                "sasl-server-factory" => "configured",
                "security-domain" => "ManagementDomain"
            },
            "application-sasl-authentication" => {
                "mechanism-configurations" => undefined,
                "sasl-server-factory" => "configured",
                "security-domain" => "ApplicationDomain"
            }
        },
        "security-domain" => {
            "ApplicationDomain" => {
                "default-realm" => "ApplicationRealm",
                "permission-mapper" => "default-permission-mapper",
                "post-realm-principal-transformer" => undefined,
                "pre-realm-principal-transformer" => undefined,
                "principal-decoder" => undefined,
                "realm-mapper" => undefined,
                "realms" => [{
                    "realm" => "ApplicationRealm",
                    "role-decoder" => "groups-to-roles"
                }],
                "role-mapper" => undefined,
                "trusted-security-domains" => undefined
            },
            "ManagementDomain" => {
                "default-realm" => "ManagementRealm",
                "permission-mapper" => "default-permission-mapper",
                "post-realm-principal-transformer" => undefined,
                "pre-realm-principal-transformer" => undefined,
                "principal-decoder" => undefined,
                "realm-mapper" => undefined,
                "realms" => [
                    {
                        "realm" => "ManagementRealm",
                        "role-decoder" => "groups-to-roles"
                    },
                    {
                        "realm" => "local",
                        "role-mapper" => "super-user-mapper"
                    }
                ],
                "role-mapper" => undefined,
                "trusted-security-domains" => undefined
            }
        },
        "security-property" => undefined,
        "server-ssl-context" => undefined,
        "service-loader-http-server-mechanism-factory" => undefined,
        "service-loader-sasl-server-factory" => undefined,
        "simple-permission-mapper" => undefined,
        "simple-regex-realm-mapper" => undefined,
        "simple-role-decoder" => {"groups-to-roles" => {"attribute" => "groups"}},
        "token-realm" => undefined,
        "trust-managers" => undefined,
        "x500-attribute-principal-decoder" => undefined
    }
}

Default Application Authentication Configuration

By default, applications are secured using legacy security domains. Applications must specify a security domain in their web.xml as well as the authentication method. If no security domain is specified by the application, WildFly will use the provided other legacy security domain.

Update WildFly to Use the Default Elytron Components for Application Authentication

/subsystem=undertow/application-security-domain=exampleApplicationDomain:add(http-authentication-factory=application-http-authentication)

Default Elytron Application HTTP Authentication Configuration

By default, the application-http-authentication http-authentication-factory is provided for application http authentication.

/subsystem=elytron/http-authentication-factory=application-http-authentication:read-resource()
{
    "outcome" => "success",
    "result" => {
        "http-server-mechanism-factory" => "global",
        "mechanism-configurations" => [
            {
                "mechanism-name" => "BASIC",
                "mechanism-realm-configurations" => [{"realm-name" => "Application Realm"}]
            },
            {"mechanism-name" => "FORM"}
        ],
        "security-domain" => "ApplicationDomain"
    }
}

The application-http-authentication http-authentication-factory is configured to use the ApplicationDomain security domain.

/subsystem=elytron/security-domain=ApplicationDomain:read-resource()
{
    "outcome" => "success",
    "result" => {
        "default-realm" => "ApplicationRealm",
        "permission-mapper" => "default-permission-mapper",
        "post-realm-principal-transformer" => undefined,
        "pre-realm-principal-transformer" => undefined,
        "principal-decoder" => undefined,
        "realm-mapper" => undefined,
        "realms" => [{
            "realm" => "ApplicationRealm",
            "role-decoder" => "groups-to-roles"
        }],
        "role-mapper" => undefined,
        "trusted-security-domains" => undefined
    }
}

The ApplicationDomain security domain is backed by the ApplicationRealm Elytron security realm, which is a properties-based realm.

/subsystem=elytron/properties-realm=ApplicationRealm:read-resource()
{
    "outcome" => "success",
    "result" => {
        "groups-attribute" => "groups",
        "groups-properties" => {
            "path" => "application-roles.properties",
            "relative-to" => "jboss.server.config.dir"
        },
        "users-properties" => {
            "path" => "application-users.properties",
            "relative-to" => "jboss.server.config.dir",
            "digest-realm-name" => "ApplicationRealm"
        }
    }
}

Default Management Authentication Configuration

By default, the WildFly management interfaces are secured by the legacy core management authentication.

Default Configuration

/core-service=management/management-interface=http-interface:read-resource()
{
    "outcome" => "success",
    "result" => {
        "allowed-origins" => undefined,
        "console-enabled" => true,
        "http-authentication-factory" => undefined,
        "http-upgrade" => {"enabled" => true},
        "http-upgrade-enabled" => true,
        "sasl-protocol" => "remote",
        "secure-socket-binding" => undefined,
        "security-realm" => "ManagementRealm",
        "server-name" => undefined,
        "socket-binding" => "management-http",
        "ssl-context" => undefined
    }

WildFly does provide management-http-authentication and management-sasl-authentication in the elytron subsystem for securing the management interfaces as well.

Update WildFly to Use the Default Elytron Components for Management Authentication

Set http-authentication-factory to use management-http-authentication

/core-service=management/management-interface=http-interface:write-attribute( \
  name=http-authentication-factory, \
  value=management-http-authentication \
)

Set sasl-authentication-factory to use management-sasl-authentication

/core-service=management/management-interface=http-interface:write-attribute( \
  name=http-upgrade.sasl-authentication-factory, \
  value=management-sasl-authentication \
)

Undefine security-realm

/core-service=management/management-interface=http-interface:undefine-attribute(name=security-realm)

Reload WildFly for the changes to take affect.

reload

The management interfaces are now secured using the default components provided by the 'elytron' subsystem.

Default Elytron Management HTTP Authentication Configuration

When you access the management interface over HTTP, for example when using the web-based management console, WildFly will use the management-http-authentication http-authentication-factory.

/subsystem=elytron/http-authentication-factory=management-http-authentication:read-resource()
{
    "outcome" => "success",
    "result" => {
        "http-server-mechanism-factory" => "global",
        "mechanism-configurations" => [{
            "mechanism-name" => "DIGEST",
            "mechanism-realm-configurations" => [{"realm-name" => "ManagementRealm"}]
        }],
        "security-domain" => "ManagementDomain"
    }
}

The management-http-authentication http-authentication-factory, is configured to use the ManagementDomain security domain.

/subsystem=elytron/security-domain=ManagementDomain:read-resource()
{
    "outcome" => "success",
    "result" => {
        "default-realm" => "ManagementRealm",
        "permission-mapper" => "default-permission-mapper",
        "post-realm-principal-transformer" => undefined,
        "pre-realm-principal-transformer" => undefined,
        "principal-decoder" => undefined,
        "realm-mapper" => undefined,
        "realms" => [
            {
                "realm" => "ManagementRealm",
                "role-decoder" => "groups-to-roles"
            },
            {
                "realm" => "local",
                "role-mapper" => "super-user-mapper"
            }
        ],
        "role-mapper" => undefined,
        "trusted-security-domains" => undefined
    }
}

The ManagementDomain security domain is backed by the ManagementRealm Elytron security realm, which is a properties-based realm.

/subsystem=elytron/properties-realm=ManagementRealm:read-resource()
{
    "outcome" => "success",
    "result" => {
        "groups-attribute" => "groups",
        "groups-properties" => {
            "path" => "mgmt-groups.properties",
            "relative-to" => "jboss.server.config.dir"
        },
        "plain-text" => false,
        "users-properties" => {
            "path" => "mgmt-users.properties",
            "relative-to" => "jboss.server.config.dir"
        }
    }
}

Default Elytron Management CLI Authentication

By default, the management CLI (jboss-cli.sh) is configured to connect over remotehttp.

Default jboss-cli.xml

<jboss-cli xmlns="urn:jboss:cli:3.1">

    <default-protocol use-legacy-override="true">remotehttp</default-protocol>

    <!-- The default controller to connect to when 'connect' command is executed w/o arguments -->
    <default-controller>
        <protocol>remotehttp</protocol>
        <host>localhost</host>
        <port>9990</port>
    </default-controller>

This will establish a connection over HTTP and use HTTP upgrade to change the communication protocol to native. The HTTP upgrade connection is secured in the http-upgrade section of the http-interface using a sasl-authentication-factory.

Example Configuration with Default Components

/core-service=management/management-interface=http-interface:read-resource()
{
    "outcome" => "success",
    "result" => {
        "allowed-origins" => undefined,
        "console-enabled" => true,
        "http-authentication-factory" => "management-http-authentication",
        "http-upgrade" => {
            "enabled" => true,
            "sasl-authentication-factory" => "management-sasl-authentication"
        },
        "http-upgrade-enabled" => true,
        "sasl-protocol" => "remote",
        "secure-socket-binding" => undefined,
        "security-realm" => undefined,
        "server-name" => undefined,
        "socket-binding" => "management-http",
        "ssl-context" => undefined
    }
}

The default sasl-authentication-factory is management-sasl-authentication.

/subsystem=elytron/sasl-authentication-factory=management-sasl-authentication:read-resource()
{
    "outcome" => "success",
    "result" => {
        "mechanism-configurations" => [
            {
                "mechanism-name" => "JBOSS-LOCAL-USER",
                "realm-mapper" => "local"
            },
            {
                "mechanism-name" => "DIGEST-MD5",
                "mechanism-realm-configurations" => [{"realm-name" => "ManagementRealm"}]
            }
        ],
        "sasl-server-factory" => "configured",
        "security-domain" => "ManagementDomain"
    }
}

The management-sasl-authentication sasl-authentication-factory specifies JBOSS-LOCAL-USER and DIGEST-MD5 mechanisms.

JBOSS-LOCAL-USER Realm

/subsystem=elytron/identity-realm=local:read-resource()
{
    "outcome" => "success",
    "result" => {
        "attribute-name" => undefined,
        "attribute-values" => undefined,
        "identity" => "$local"
    }
}

The local Elytron security realm is for handling silent authentication for local users.

The ManagementRealm Elytron security realm is the same realm used in the management-http-authentication http-authentication-factory.

Comparing Legacy Approaches to Elytron Approaches

Legacy Approach	Elytron Approach
UsersRoles Login Module	Configure Authentication with a Properties File-Based Identity Store
Database Login Module	Configure Authentication with a Database Identity Store
Ldap, LdapExtended, AdvancedLdap, AdvancedADLdap Login Modules	Configure Authentication with an LDAP-Based Identity Store
Certificate, Certificate Roles Login Module	Configure Authentication with Certificates
Kerberos, SPNEGO Login Modules	Configure Authentication with a Kerberos-Based Identity Store
Kerberos, SPNEGO Login Modules with Fallback	Configure Authentication with a Form as a Fallback for Kerberos
Vault	Create and Use a Credential Store
Legacy Security Realms	Secure the Management Interfaces with a New Identity Store, Silent Authentication
RBAC	Using RBAC with Elytron
Legacy Security Realms for One-way and Two-way SSL/TLS for Applications	Enable One-way SSL/TLS for Applications, Enable Two-way SSL/TLS in WildFly for Applications
Legacy Security Realms for One-way and Two-way SSL/TLS for Management Interfaces	Enable One-way for the Management Interfaces Using the Elytron Subsystem, Enable Two-way SSL/TLS for the Management Interfaces using the Elytron Subsystem

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

#$REALM_NAME=examplePropRealm$
user1=password123
user2=password123

Example user to roles file: example-roles.properties

user1=Admin
user2=Guest

Configure a properties-realm in WildFly:

/subsystem=elytron/properties-realm=examplePropRealm:add(groups-attribute=groups,groups-properties={path=example-roles.properties,relative-to=jboss.server.config.dir},users-properties={path=example-users.properties,relative-to=jboss.server.config.dir,plain-text=true})

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 :

/subsystem=elytron/security-domain=exampleSD:add(realms=[{realm=examplePropRealm,role-decoder=groups-to-roles}],default-realm=examplePropRealm,permission-mapper=default-permission-mapper)

Configure an http-authentication-factory :

/subsystem=elytron/http-authentication-factory=example-http-auth:add(http-server-mechanism-factory=global,security-domain=exampleSD,mechanism-configurations=[{mechanism-name=BASIC,mechanism-realm-configurations=[{realm-name=exampleApplicationDomain}]}])

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:

/subsystem=undertow/application-security-domain=exampleApplicationDomain:add(http-authentication-factory=example-http-auth)

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:

/subsystem=elytron/filesystem-realm=exampleFsRealm:add(path=fs-realm-users,relative-to=jboss.server.config.dir)

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.

/subsystem=elytron/filesystem-realm=exampleFsRealm/identity=user1:add()
/subsystem=elytron/filesystem-realm=exampleFsRealm/identity=user1:set-password( clear={password="password123"})
/subsystem=elytron/filesystem-realm=exampleFsRealm/identity=user1:add-attribute(name=Roles, value=["Admin","Guest"])

Add a simple-role-decoder :

/subsystem=elytron/simple-role-decoder=from-roles-attribute:add(attribute=Roles)

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 :

/subsystem=elytron/security-domain=exampleFsSD:add(realms=[{realm=exampleFsRealm,role-decoder=from-roles-attribute}],default-realm=exampleFsRealm,permission-mapper=default-permission-mapper)

Configure an http-authentication-factory :

/subsystem=elytron/http-authentication-factory=example-fs-http-auth:add(http-server-mechanism-factory=global,security-domain=exampleFsSD,mechanism-configurations=[{mechanism-name=BASIC,mechanism-realm-configurations=[{realm-name=exampleApplicationDomain}]}])

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:

/subsystem=undertow/application-security-domain=exampleApplicationDomain:add(http-authentication-factory=example-fs-http-auth)

Configure your application's web.xml and jboss-web.xml .

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:

deploy /path/to/postgresql-9.4.1210.jar

data-source add --name=examplePostgresDS --jndi-name=java:jboss/examplePostgresDS --driver-name=postgresql-9.4.1210.jar  --connection-url=jdbc:postgresql://localhost:5432/postgresdb --user-name=postgresAdmin --password=mysecretpassword

Configure a jdbc-realm in WildFly:

/subsystem=elytron/jdbc-realm=exampleDbRealm:add(principal-query=[{sql="SELECT password,roles FROM wildfly_users WHERE username=?",data-source=examplePostgresDS,clear-password-mapper={password-index=1},attribute-mapping=[{index=2,to=groups}]}])

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 :

/subsystem=elytron/security-domain=exampleDbSD:add(realms=[{realm=exampleDbRealm,role-decoder=groups-to-roles}],default-realm=exampleDbRealm,permission-mapper=default-permission-mapper)

Configure an http-authentication-factory :

/subsystem=elytron/http-authentication-factory=example-db-http-auth:add(http-server-mechanism-factory=global,security-domain=exampleDbSD,mechanism-configurations=[{mechanism-name=BASIC,mechanism-realm-configurations=[{realm-name=exampleDbSD}]}])

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:

/subsystem=undertow/application-security-domain=exampleApplicationDomain:add(http-authentication-factory=example-db-http-auth)

Configure your application's web.xml and jboss-web.xml .

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:

dn: dc=wildfly,dc=org
dc: wildfly
objectClass: top
objectClass: domain

dn: ou=Users,dc=wildfly,dc=org
objectClass: organizationalUnit
objectClass: top
ou: Users

dn: uid=jsmith,ou=Users,dc=wildfly,dc=org
objectClass: top
objectClass: person
objectClass: inetOrgPerson
cn: John Smith
sn: smith
uid: jsmith
userPassword: password123

dn: ou=Roles,dc=wildfly,dc=org
objectclass: top
objectclass: organizationalUnit
ou: Roles

dn: cn=Admin,ou=Roles,dc=wildfly,dc=org
objectClass: top
objectClass: groupOfNames
cn: Admin
member: uid=jsmith,ou=Users,dc=wildfly,dc=org

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.

/subsystem=elytron/dir-context=exampleDC:add(url="ldap://127.0.0.1:10389",principal="uid=admin,ou=system",credential-reference={clear-text="secret"})

Configure an ldap-realm in WildFly:

/subsystem=elytron/ldap-realm=exampleLR:add(dir-context=exampleDC,identity-mapping={search-base-dn="ou=Users,dc=wildfly,dc=org",rdn-identifier="uid",user-password-mapper={from="userPassword"},attribute-mapping=[{filter-base-dn="ou=Roles,dc=wildfly,dc=org",filter="(&(objectClass=groupOfNames)(member={1}))",from="cn",to="Roles"}]})

Add a simple-role-decoder :

/subsystem=elytron/simple-role-decoder=from-roles-attribute:add(attribute=Roles)

Configure a security-domain :

/subsystem=elytron/security-domain=exampleLdapSD:add(realms=[{realm=exampleLR,role-decoder=from-roles-attribute}],default-realm=exampleLR,permission-mapper=default-permission-mapper)

Configure an http-authentication-factory :

/subsystem=elytron/http-authentication-factory=example-ldap-http-auth:add(http-server-mechanism-factory=global,security-domain=exampleLdapSD,mechanism-configurations=[{mechanism-name=BASIC,mechanism-realm-configurations=[{realm-name=exampleApplicationDomain}]}])

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:

/subsystem=undertow/application-security-domain=exampleApplicationDomain:add(http-authentication-factory=example-ldap-http-auth)

Configure your application's web.xml and jboss-web.xml .

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 .

/subsystem=elytron/key-store-realm=ksRealm:add(key-store=twoWayTS)

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.

/subsystem=elytron/x500-attribute-principal-decoder=CNDecoder:add(oid="2.5.4.3",maximum-segments=1)

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.

/subsystem=elytron/constant-role-mapper=constantClientCertRole:add(roles=[Admin,Guest])

Configure a security-domain .

/subsystem=elytron/security-domain=exampleCertSD:add(realms=[{realm=ksRealm}],default-realm=ksRealm,permission-mapper=default-permission-mapper,principal-decoder=CNDecoder,role-mapper=constantClientCertRole)

Configure an http-authentication-factory .

/subsystem=elytron/http-authentication-factory=exampleCertHttpAuth:add(http-server-mechanism-factory=global,security-domain=exampleCertSD,mechanism-configurations=[{mechanism-name=CLIENT_CERT,mechanism-realm-configurations=[{realm-name=exampleApplicationDomain}]}])

Configure an application-security-domain in the Undertow subsystem.

/subsystem=undertow/application-security-domain=exampleApplicationDomain:add(http-authentication-factory=exampleCertHttpAuth)

Update server-ssl-context .

/subsystem=elytron/server-ssl-context=twoWaySSC:write-attribute(name=security-domain,value=exampleCertSD)
/subsystem=elytron/server-ssl-context=twoWaySSC:write-attribute(name=authentication-optional, value=true)

Configure your application's web.xml and jboss-web.xml .

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

<login-config>
  <auth-method>CLIENT-CERT</auth-method>
  <realm-name>exampleApplicationDomain</realm-name>
</login-config>

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 .

/subsystem=elytron/kerberos-security-factory=krbSF:add(principal="HTTP/host@REALM",path="/path/to/http.keytab",mechanism-oids=[1.2.840.113554.1.2.2,1.3.6.1.5.5.2])

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:

/system-property=java.security.krb5.conf:add(value="/path/to/krb5.conf")

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.

/subsystem=elytron/filesystem-realm=exampleFsRealm:add(path=fs-realm-users,relative-to=jboss.server.config.dir)
/subsystem=elytron/filesystem-realm=exampleFsRealm/identity=user1@REALM:add()
/subsystem=elytron/filesystem-realm=exampleFsRealm/identity=user1@REALM:add-attribute(name=Roles, value=["Admin","Guest"])

Add a simple-role-decoder .

/subsystem=elytron/simple-role-decoder=from-roles-attribute:add(attribute=Roles)

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 .

/subsystem=elytron/security-domain=exampleFsSD:add(realms=[{realm=exampleFsRealm,role-decoder=from-roles-attribute}],default-realm=exampleFsRealm,permission-mapper=default-permission-mapper)

Configure an http-authentication-factory that uses the kerberos-security-factory .

/subsystem=elytron/http-authentication-factory=example-krb-http-auth:add(http-server-mechanism-factory=global,security-domain=exampleFsSD,mechanism-configurations=[{mechanism-name=SPNEGO,mechanism-realm-configurations=[{realm-name=exampleFsSD}],credential-security-factory=krbSF}])

Configure an application-security-domain in the Undertow subsystem:

/subsystem=undertow/application-security-domain=exampleApplicationDomain:add(http-authentication-factory=example-krb-http-auth)

Configure your application's web.xml , jboss-web.xml and jboss-deployment-structure.xml .

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

<login-config>
  <auth-method>SPNEGO</auth-method>
  <realm-name>exampleApplicationDomain</realm-name>
</login-config>

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.

/subsystem=elytron/http-authentication-factory=example-krb-http-auth:list-add(name=mechanism-configurations, value={mechanism-name=FORM})

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:

/subsystem=elytron/filesystem-realm=exampleFsRealm/identity=fallbackUser1:add()
/subsystem=elytron/filesystem-realm=exampleFsRealm/identity=fallbackUser1:set-password(clear={password="password123"})
/subsystem=elytron/filesystem-realm=exampleFsRealm/identity=fallbackUser1:add-attribute(name=Roles, value=["Admin","Guest"])

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.

<login-config>
  <auth-method>SPNEGO,FORM</auth-method>
  <realm-name>exampleApplicationDomain</realm-name>
  <form-login-config>
    <form-login-page>/login.jsp</form-login-page>
    <form-error-page>/error.jsp</form-error-page>
  </form-login-config>
</login-config>

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

<web-app>
  <security-constraint>
    <web-resource-collection>
      <web-resource-name>secure</web-resource-name>
      <url-pattern>/secure/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
      <role-name>Admin</role-name>
    </auth-constraint>
  </security-constraint>
  <security-role>
    <description>The role that is required to log in to /secure/*</description>
    <role-name>Admin</role-name>
  </security-role>
  <login-config>
    <auth-method>BASIC</auth-method>
    <realm-name>exampleApplicationDomain</realm-name>
  </login-config>
</web-app>

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

<jboss-web>
  <security-domain>exampleApplicationDomain</security-domain>
</jboss-web>

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.

/subsystem=undertow:write-attribute(name=default-security-domain, value="exampleApplicationDomain")

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:

/subsystem=undertow/application-security-domain=exampleApplicationDomain:write-attribute(name=override-deployment-config,value=true)

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

Example jboss-web.xml

<login-config>
  <auth-method>FORM</auth-method>
  <realm-name>exampleApplicationDomain</realm-name>
</login-config>

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

/subsystem=elytron/http-authentication-factory=exampleHttpAuth:read-resource()
{
    "outcome" => "success",
    "result" => {
        "http-server-mechanism-factory" => "global",
        "mechanism-configurations" => [{
            "mechanism-name" => "BASIC",
            "mechanism-realm-configurations" => [{"realm-name" => "exampleApplicationDomain"}]
        }],
        "security-domain" => "exampleSD"
    }
}

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.

/subsystem=elytron/credential-store=exampleCS:add(relative-to=jboss.server.data.dir, location=cs.jceks,create=true,credential-reference={clear-text=cs-secret})

Add a credential to a credential store.

/subsystem=elytron/credential-store=exampleCS/alias=keystorepw:add(secret-value="secret")

List all credentials in a credential store.

/subsystem=elytron/credential-store=exampleCS:read-children-names(child-type=alias)
{
    "outcome" => "success",
    "result" => ["keystorepw"]
}

Remove a credential from a credential store.

/subsystem=elytron/credential-store=exampleCS/alias=keystorepw:remove

Use a credential store.

/subsystem=elytron/key-store=twoWayKS:write-attribute(name=credential-reference,value={store=exampleCS,alias=keystorepw})

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

/subsystem=elytron/http-authentication-factory=example-http-auth:add(http-server-mechanism-factory=global,security-domain=exampleSD,mechanism-configurations=[{mechanism-name=DIGEST,mechanism-realm-configurations=[{realm-name=exampleManagementRealm}]}])

Example sasl-authentication-factory

/subsystem=elytron/sasl-authentication-factory=example-sasl-auth:add(sasl-server-factory=configured,security-domain=exampleSD,mechanism-configurations=[{mechanism-name=DIGEST-MD5,mechanism-realm-configurations=[{realm-name=exampleManagementRealm}]}])

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

Example update http-authentication-factory

/core-service=management/management-interface=http-interface:write-attribute(name=http-authentication-factory, value=example-http-auth)
{
   "outcome" => "success",
   "response-headers" => {
       "operation-requires-reload" => true,
       "process-state" => "reload-required"
   }
}

reload

Example update sasl-authentication-factory

/core-service=management/management-interface=http-interface:write-attribute(name=http-upgrade.sasl-authentication-factory, value=example-sasl-auth)
{
   "outcome" => "success",
   "response-headers" => {
       "operation-requires-reload" => true,
       "process-state" => "reload-required"
   }
}

reload

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 .

/subsystem=elytron/sasl-authentication-factory=example-sasl-auth:list-add(name=mechanism-configurations, value={mechanism-name=JBOSS-LOCAL-USER, realm-mapper=local})

reload

Create a new sasl-server-factory with silent authentication.

/subsystem=elytron/sasl-authentication-factory=example-sasl-auth:add(sasl-server-factory=configured,security-domain=exampleSD,mechanism-configurations=[{mechanism-name=DIGEST-MD5,mechanism-realm-configurations=[{realm-name=exampleManagementRealm}]},{mechanism-name=JBOSS-LOCAL-USER, realm-mapper=local}])

reload

Remove silent authentication from an existing sasl-server-factory :

/subsystem=elytron/sasl-authentication-factory=managenet-sasl-authentication:read-resource
{
    "outcome" => "success",
    "result" => {
        "mechanism-configurations" => [
            {
                "mechanism-name" => "JBOSS-LOCAL-USER",
                "realm-mapper" => "local"
            },
            {
                "mechanism-name" => "DIGEST-MD5",
                "mechanism-realm-configurations" => [{"realm-name" => "ManagementRealm"}]
            }
        ],
        "sasl-server-factory" => "configured",
        "security-domain" => "ManagementDomain"
    }
}

/subsystem=elytron/sasl-authentication-factory=temp-sasl-authentication:list-remove(name=mechanism-configurations,index=0)

reload

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:

$ keytool -genkeypair -alias localhost -keyalg RSA -keysize 1024 -validity 365 -keystore /path/to/keystore.jks -dname "CN=localhost" -keypass secret -storepass secret

Configure a key-store in WildFly:

/subsystem=elytron/key-store=httpsKS:add(path=/path/to/keystore.jks,credential-reference={clear-text=secret},type=JKS)

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.

/subsystem=elytron/key-store=httpsKS:add(path=keystore.jks,relative-to=jboss.server.config.dir,credential-reference={clear-text=secret},type=JKS)

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

/subsystem=elytron/key-manager=httpsKM:add(key-store=httpsKS,credential-reference={clear-text=secret})

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

/subsystem=elytron/server-ssl-context=httpsSSC:add(key-manager=httpsKM,protocols=["TLSv1.2"])

IMPORTANT: You need to determine what SSL/TLS protocols you want to support. The example commands above uses TLSv1.2.

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

/subsystem=undertow/server=default-server/https-listener=https:read-attribute(name=security-realm)
{
    "outcome" => "success",
    "result" => "ApplicationRealm"
}

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. Also there has to be always configured either ssl-context or security-realm. Thus when changing between those, you have to use batch operation:

Remove the reference to the legacy security realm and update the https-listener to use the ssl-context from Elytron :

batch
/subsystem=undertow/server=default-server/https-listener=https:undefine-attribute(name=security-realm)
/subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=ssl-context,value=httpsSSC)
run-batch

Reload the server:

reload

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:

$ keytool -genkeypair -alias localhost -keyalg RSA -keysize 1024 -validity 365 -keystore server.keystore.jks -dname "CN=localhost" -keypass secret -storepass secret

$ keytool -genkeypair -alias client -keyalg RSA -keysize 1024 -validity 365 -keystore client.keystore.jks -dname "CN=client" -keypass secret -storepass secret

Export the server and client certificates:

$ keytool -exportcert  -keystore server.keystore.jks -alias localhost -keypass secret -storepass secret -file server.cer

$ keytool -exportcert  -keystore client.keystore.jks -alias client -keypass secret -storepass secret -file client.cer

Import the sever and client certificates into the opposing truststores:

$ keytool -importcert -keystore server.truststore.jks -storepass secret -alias client -trustcacerts -file client.cer

$ keytool -importcert -keystore client.truststore.jks -storepass secret -alias localhost -trustcacerts -file server.cer

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

/subsystem=elytron/key-store=twoWayKS:add(path=/path/to/server.keystore.jks,credential-reference={clear-text=secret},type=JKS)

/subsystem=elytron/key-store=twoWayTS:add(path=/path/to/server.truststore.jks,credential-reference={clear-text=secret},type=JKS)

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.

/subsystem=elytron/key-store=myKS:add(path=keystore.jks,relative-to=jboss.server.config.dir,credential-reference={clear-text=secret},type=JKS)

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

/subsystem=elytron/key-manager=twoWayKM:add(key-store=twoWayKS,credential-reference={clear-text=secret})

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

/subsystem=elytron/trust-manager=twoWayTM:add(key-store=twoWayTS)

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

/subsystem=elytron/server-ssl-context=twoWaySSC:add(key-manager=twoWayKM,protocols=["TLSv1.2"],trust-manager=twoWayTM,need-client-auth=true)

IMPORTANT
You need to determine what SSL/TLS protocols you want to support. The example commands above uses TLSv1.2.

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

/subsystem=undertow/server=default-server/https-listener=https:read-attribute(name=security-realm)
{
    "outcome" => "success",
    "result" => "ApplicationRealm"
}

Remove the reference to the legacy security realm and update the https-listener to use the ssl-context from Elytron:

batch
/subsystem=undertow/server=default-server/https-listener=https:undefine-attribute(name=security-realm)
/subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=ssl-context,value=twoWaySSC)
run-batch

Reload the server

reload

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.

$ keytool -genkeypair -alias localhost -keyalg RSA -keysize 1024 -validity 365 -keystore keystore.jks -dname "CN=localhost" -keypass secret -storepass secret

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

/subsystem=elytron/key-store=httpsKS:add(path=keystore.jks,relative-to=jboss.server.config.dir,credential-reference={clear-text=secret},type=JKS)

/subsystem=elytron/key-manager=httpsKM:add(key-store=httpsKS,credential-reference={clear-text=secret})

/subsystem=elytron/server-ssl-context=httpsSSC:add(key-manager=httpsKM,protocols=["TLSv1.2"])

IMPORTANT: You need to determine what SSL/TLS protocols you want to support. The example commands above uses 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.

/core-service=management/management-interface=http-interface:write-attribute(name=ssl-context, value=httpsSSC)

/core-service=management/management-interface=http-interface:write-attribute(name=secure-socket-binding, value=management-https)

Reload the WildFly instance.

reload

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.

$ keytool -genkeypair -alias localhost -keyalg RSA -keysize 1024 -validity 365 -keystore server.keystore.jks -dname "CN=localhost" -keypass secret -storepass secret

$ keytool -genkeypair -alias client -keyalg RSA -keysize 1024 -validity 365 -keystore client.keystore.jks -dname "CN=client" -keypass secret -storepass secret

Export your server and client certificates.

$ keytool -exportcert  -keystore server.keystore.jks -alias localhost -keypass secret -storepass secret -file server.cer

$ keytool -exportcert  -keystore client.keystore.jks -alias client -keypass secret -storepass secret -file client.cer

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

$ keytool -importcert -keystore server.truststore.jks -storepass secret -alias client -trustcacerts -file client.cer

$ keytool -importcert -keystore client.truststore.jks -storepass secret -alias localhost -trustcacerts -file server.cer

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

/subsystem=elytron/key-store=twoWayKS:add(path=server.keystore.jks,relative-to=jboss.server.config.dir,credential-reference={clear-text=secret},type=JKS)

/subsystem=elytron/key-store=twoWayTS:add(path=server.truststore.jks,relative-to=jboss.server.config.dir,credential-reference={clear-text=secret},type=JKS)

/subsystem=elytron/key-manager=twoWayKM:add(key-store=twoWayKS,credential-reference={clear-text=secret})

/subsystem=elytron/trust-manager=twoWayTM:add(key-store=twoWayTS)

/subsystem=elytron/server-ssl-context=twoWaySSC:add(key-manager=twoWayKM,protocols=["TLSv1.2"],trust-manager=twoWayTM,want-client-auth=true,need-client-auth=true)

IMPORTANT: You need to determine what SSL/TLS protocols you want to support. The example commands above uses 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.

/core-service=management/management-interface=http-interface:write-attribute(name=ssl-context, value=twoWaySSC)

/core-service=management/management-interface=http-interface:write-attribute(name=secure-socket-binding, value=management-https)

Reload the WildFly instance.

reload

Configure your client to use the client certificate.

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

/subsystem=elytron/dir-context=exampleDC:add( \
  url="ldap://127.0.0.1:10389", \
  principal="uid=admin,ou=system", \
  credential-reference={clear-text=secret} \
)

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

/subsystem=elytron/ldap-key-store=ldapKS:add( \
  dir-context=exampleDC, \
  search-path="ou=Keystores,dc=wildfly,dc=org" \
)

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 .

/subsystem=elytron/key-store=myKS:add( \
  path=keystore.jks, \
  relative-to=jboss.server.config.dir, \
  credential-reference={ \
    clear-text=secret \
  }, \
  type=JKS \
)

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.

/subsystem=elytron/filtering-key-store=filterKS:add( \
  key-store=myKS, \
  alias-filter="alias1,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.

/subsystem=elytron/key-store=httpsKS:load

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:

/subsystem=elytron/key-store=httpsKS/alias=localhost:read-attribute(name=certificate-chain)
{
    "outcome" => "success",
    "result" => [{
        "type" => "X.509",
        "algorithm" => "RSA",
        "format" => "X.509",
        "public-key" => "30:81:9f:30:0d:06:09:2a:8......

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-manager
trust-manager
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:

/extension=org.wildfly.extension.elytron:add()

To enable the Elytron subsystem in WildFly:

/subsystem=elytron:add

reload

To disable the Elytron subsystem in WildFly:

/subsystem=elytron:remove

reload

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:

/subsystem=security:remove

reload

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:

/subsystem=security:add

reload

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.

/subsystem=undertow/application-security-domain=exampleApplicationDomain:add(http-authentication-factory=example-http-auth)

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:

/subsystem=undertow/server=default-server/https-listener=https:read-attribute(name=security-realm)
{
    "outcome" => "success",
    "result" => "ApplicationRealm"
}

For enabling HTTPS using elytron, you need to undefine the security-realm attribute and set the ssl-context attribute. As there has to be always configured either ssl-context or security-realm you have to use batch operation when changing between those:

batch
/subsystem=undertow/server=default-server/https-listener=https:undefine-attribute(name=security-realm)
/subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=ssl-context,value=httpsSSC)
run-batch

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:

/subsystem=elytron/type-of-realm=realmName:add(....)

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:

/subsystem=elytron/ROLE-DECODER-TYPE=roleDeoderName:add(....)

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:

/subsystem=elytron/simple-permission-mapper=PermissionMapperName:add(...)

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:

/subsystem=elytron/ROLEM-MAPPER-TYPE=roleMapperName:add(...)

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:

/subsystem=elytron/security-domain=domainName:add(realms=[{realm=realmName,role-decoder=roleDecoderName}],default-realm=realmName,permission-mapper=permissionMapperName,role-mapper=roleMapperName,...)

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:

/subsystem=elytron/AUTH-FACTORY-TYPE=authFactoryName:add(....)

Create an Elytron Policy Provider

Elytron subsystem provides a specific resource definition that can be used to configure a default Java Policy provider. The subsystem allows you to define multiple policy providers but select a single one as the default:

/subsystem=elytron/policy=policy-provider-a:add(custom-policy=\[{name=policy-provider-a, class-name=MyPolicyProviderA, module=x.y.z}\])

Using Elytron within WildFly

Using the Out of the Box Elytron Components

Securing Management Interfaces

You can find more details on the enabling WildFly to use the out of the box Elytron components for securing the management interfaces in the Default Management Authentication Configuration section.

Securing Applications

The elytron subsystem provides application-http-authentication by default which can be used to secure applications. For more details on how application-http-authentication is configured, see the Out of the Box Configuration section.

To configure applications to use application-http-authentication, see Configure Applications to Use Elytron or Legacy Security for Authentication. You can also override the default behavior of all applications using the steps in Override an Application's Authentication Configuration.

Using SSL/TLS

WildFly does provide a default one-way SSL/TLS configuration using the legacy core management authentication but does not provide one in the elytron subsystem. You can find more details on configuring SSL/TLS using the elytron subsystem for both the management interfaces as well as for applications in Configure SSL/TLS

Using Elytron with Other Subsystems

In addition to securing applications and management interfaces, Elytron also integrates with other subsystems in WildFly.

Subsystem	Details
batch-jberet	You can configure the batch-jberet to run batch jobs using an Elytron security domain.
datasources	You can use a credential store or an Elytron security domain to provide authentication information in a datasource definition.
messaging-activemq	You can secure remote connections to the remote connections used by the messaging-activemq subsystem.
iiop-openjdk	You can use the elytron subsystem to configure SSL/TLS between clients and servers using the iiop-openjdk subsystem.
mail	You can use a credential store to provide authentication information in a server definition in the mail subsystem.
undertow	You can use the elytron subsystem to configure both SSL/TLS and application authentication.

Undertow Subsystem

EJB Subsystem

Configuration can be added to the EJB subsystem to map a security domain name referenced in a deployment to an Elytron security domain:

/subsystem=ejb3/application-security-domain=MyAppSecurity:add(security-domain=ApplicationDomain)

Which results in:

<subsystem xmlns="urn:jboss:domain:ejb3:5.0">
...
    <application-security-domains>
        <application-security-domain name="MyAppSecurity" security-domain="ApplicationDomain"/>
    </application-security-domains>
...
</subsystem>

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.

An application-security-domain has two main attributes:

name - the name of the security domain as specified in a deployment
security-domain - a reference to the Elytron security domain that should be used

When an application security domain mapping is configured for a bean in a deployment, this indicates that security should be handled by Elytron.

WebServices Subsystem

There is adapter in webservices subsystem to make authentication works for elytron security domain automatically. Like configure with legacy security domain, you can configure elytron security domain in deployment descriptor or annotation to secure webservice endpoint.

Legacy Security Subsystem

As previously described, Elytron based security is configured by chaining together different capability references to form a complete security policy. To allow an incremental migration from the legacy Security subsystem some of the major components of this subsystem can be mapped to Elytron capabilities and used within an Elytron based set up.

Client Authentication with Elytron Client

WildFly Elytron uses the Elytron Client project to enable remote clients to authenticate using Elytron. Elytron Client has the following components:

Component	Description
Authentication Configuration	Contains authentication information such as usernames, passwords, allowed SASL mechanisms, and the security realm to use during digest authentication.
MatchRule	Rule used for deciding which authentication configuration to use.
Authentication Context	Set of rules and authentication configurations to use with a client for establishing a connection.

When a connection is established, the client makes use of an authentication context, which gives rules that match which authentication configuration is used with an outbound connection. For example, you could have a rules that use one authentication configuration when connecting to server1 and another authentication configuration when connecting with server2. The authentication context is comprised of a set of authentication configurations and a set of rules that define how they are selected when establishing a connection. An authentication context can also reference ssl-context and can be matched with rules.

To create a client that uses security information when establishing a connection:

Create one or more authentication configurations.
Create an authentication context by creating rule and authentication configuration pairs.
Create a runnable for establishing your connection.
Use your authentication context to run your runnable.

When you establish your connection, Elytron Client will use the set of rules provided by the authentication context to match the correct authentication configuration to use during authentication.

You can use one of the following approaches to use security information when establishing a client connection.

IMPORTANT: When using Elytron Client to make EJB calls, any hard-coded programatic authentication information, such as setting Context.SECURITY_PRINCIPAL in the javax.naming.InitialContext, will override the Elytron Client configuration.

The Configuration File Approach

The configuration file approach involves creating an XML file with your authentication configuration, authentication context, and match rules.

custom-config.xml

<configuration>
    <authentication-client xmlns="urn:elytron:1.0">
        <authentication-rules>
            <rule use-configuration="monitor">
                <match-host name="127.0.0.1" />
            </rule>
            <rule use-configuration="administrator">
                <match-host name="localhost" />
            </rule>
        </authentication-rules>
        <authentication-configurations>
            <configuration name="monitor">
                 <sasl-mechanism-selector selector="DIGEST-MD5"/>
                 <providers>
                     <use-service-loader />
                 </providers>
                 <set-user-name name="monitor" />
                 <credentials>
                     <clear-password password="password1!" />
                 </credentials>
                 <set-mechanism-realm name="ManagementRealm" />
             </configuration>

             <configuration name="administrator">
                 <sasl-mechanism-selector selector="DIGEST-MD5"/>
                 <providers>
                     <use-service-loader />
                 </providers>
                 <set-user-name name="administrator" />
                 <credentials>
                     <clear-password password="password1!" />
                 </credentials>
                 <set-mechanism-realm name="ManagementRealm" />
             </configuration>
        </authentication-configurations>
    </authentication-client>
</configuration>

You can then reference that file in your client's code by setting a system property when running your client.

$ java -Dwildfly.config.url=/path/to/the.xml …..

IMPORTANT: If you use the The Programmatic Approach, it will override any provided configuration files even if the wildfly.config.url system property is set.

When creating rules, you can look for matches on various parameters such as hostname, port, protocol, or username. A full list of options for MatchRule are available in the Javadocs. Rules are evaluated in the order in which they are configured.

Common Rules

Rule	Description
match-domain	Takes a single name attribute specifying the security domain to match against.
match-host	Takes a single name attribute specifying the hostname to match against. For example, the host 127.0.0.1 would match on http://127.0.0.1:9990/my/path.
match-no-userinfo	Matches against URIs with no userinfo.
match-path	Takes a single name attribute specifying the path to match against. For example, the path /my/path/ would match on http://127.0.0.1:9990/my/path.
match-port	Takes a single name attribute specifying the port to match against. For example, the port 9990 would match on http://127.0.0.1:9990/my/path.
match-protocol	Takes a single name attribute specifying the protocol to match against. For example, the protocol http would match on http://127.0.0.1:9990/my/path.
match-purpose	Takes a names attribute specifying the list of purposes to match against.
match-urn	Takes a single name attribute specifying the URN to match against.
match-userinfo	Takes a single name attribute specifying the userinfo to match against.

The Programmatic Approach

The programatic approach configures all the Elytron Client configuration in the client's code:

//create your authentication configuration
AuthenticationConfiguration adminConfig =
    AuthenticationConfiguration.empty()
      .setSaslMechanismSelector(SaslMechanismSelector.NONE.addMechanism("DIGEST-MD5")) 
      .useRealm("ManagementRealm")
      .useName("administrator")
      .usePassword("password1!");

//create your authentication context
AuthenticationContext context = AuthenticationContext.empty();
context = context.with(MatchRule.ALL.matchHost("127.0.0.1"), adminConfig);


//create your runnable for establishing a connection
Runnable runnable =
    new Runnable() {
      public void run() {
        try {
           //Establish your connection and do some work
        } catch (Exception e) {
          e.printStackTrace();
        }
      }
    };

//use your authentication context to run your client
context.run(runnable);

When adding configuration details to AuthenticationConfiguration and AuthenticationContext, each method call returns a new instance of that object. For example, if you wanted separate configurations when connecting over different hostnames, you could do the following:

//create your authentication configuration
AuthenticationConfiguration commonConfig =
    AuthenticationConfiguration.empty()
      .setSaslMechanismSelector(SaslMechanismSelector.NONE.addMechanism("DIGEST-MD5")) 
      .useRealm("ManagementRealm");

AuthenticationConfiguration administrator =
    commonConfig
      .useName("administrator")
      .usePassword("password1!");


AuthenticationConfiguration monitor =
    commonConfig
      .useName("monitor")
      .usePassword("password1!");


//create your authentication context
AuthenticationContext context = AuthenticationContext.empty();
context = context.with(MatchRule.ALL.matchHost("127.0.0.1"), administrator);
context = context.with(MatchRule.ALL.matchHost("localhost"), monitor);

Common Rules

Rule	Description
matchLocalSecurityDomain(String name)	This is the same as match-domain in the configuration file approach.
matchNoUser()	This is the same as match-no-user in the configuration file approach.
matchPath(String pathSpec)	This is the same as match-path in the configuration file approach.
matchPort(int port)	This is the same as match-port in the configuration file approach.
matchProtocol(String protoName)	This is the same as match-port in the configuration file approach.
matchPurpose(String purpose)	Create a new rule which is the same as this rule, but also matches the given purpose name.
matchPurposes(String... purposes)	This is the same as match-purpose in the configuration file approach.
matchUrnName(String name)	This is the same as match-urn in the configuration file approach.
matchUser(String userSpec)	This is the same as match-userinfo in the configuration file approach.

Also, instead of starting with an empty authentication configuration, you can start with the current configured one by using captureCurrent().

//create your authentication configuration
AuthenticationConfiguration commonConfig = AuthenticationConfiguration.captureCurrent();

Using captureCurrent() will capture any previously established authentication context and use it as your new base configuration. A authentication context is established once its been activated by calling run(). If captureCurrent() is called and no context is currently active, it will try and use the default authentication if available. You can find more details about this in The Configuration File Approach, The Default Configuration Approach, and Using Elytron Client with Clients Deployed to WildFly sections.

Using AuthenticationConfiguration.EMPTY should only be used as a base to build a configuration on top of and should not be used on its own. It provides a configuration that uses the JVM-wide registered providers and enables anonymous authentication.

When specifying the providers on top of the AuthenticationConfiguration.EMPTY configuration, you can specify a custom list, but most users should use WildFlyElytronProvider() providers.

When creating an authentication context, using the context.with(...) will create a new context that merges the rules and authentication configuration from the current context with the provided rule and authentication configuration. The provided rule and authentication configuration will appear after the ones in the current context.

The Default Configuration Approach

The default configuration approach relies completely on the configuration provided by Elytron Client:

//create your runnable for establishing a connection
Runnable runnable =
    new Runnable() {
      public void run() {
        try {
           //Establish your connection and do some work
        } catch (Exception e) {
          e.printStackTrace();
        }
      }
    };

// run runnable directly
runnable.run();

To provide a default configuration, Elytron Client tries to auto-discover a wildfly-config.xml file on the filesystem. It looks in the following locations:

Location specified by the wildfly.config.url system property set outside of the client code.
The classpath root directory.
The META-INF directory on the classpath.

If it does not find one, it will try and use the default wildfly-config.xml provided in the $WILDFLY_HOME/bin/client/jboss-client.jar.

default wildfly-config.xml

<configuration>
  <authentication-client xmlns="urn:elytron:1.0">
    <authentication-rules>
      <rule use-configuration="default" />
    </authentication-rules>
    <authentication-configurations>
      <configuration name="default">
        <sasl-mechanism-selector selector="#ALL" />
        <set-mechanism-properties>
          <property key="wildfly.sasl.local-user.quiet-auth" value="true" />
        </set-mechanism-properties>
        <providers>
            <use-service-loader />
        </providers>
      </configuration>
    </authentication-configurations>
  </authentication-client>
</configuration>

Using Elytron Client with Clients Deployed to WildFly

Clients deployed to WildFly can also make use of Elytron Client. In cases where you have included a wildfly-config.xml with your deployment or the system property has been set, an AuthenticationContext is automatically parsed and created from that file.

To load a configuration file outside of the deployment, you can use the parseAuthenticationClientConfiguration(URI) method. This method will return an AuthentcationContext which you can then use in your client’s code using the The Programmatic Approach.

Additionally, clients will also automatically parse and create an AuthenticationContext from the client configuration provided by the elytron subsystem. The client configuration in the elytron subsystem can also take advantage of other components defined in the elytron subsystem such as credential stores. If client configuration is provided by BOTH the deployment and the elytron subsystem, the elytron subsystem’s configuration is used.

Client configuration using wildfly-config.xml

Prior to WildFly 11, many WildFly client libraries used different configuration strategies. WildFly 11 introduces a new wildfly-config.xml file which unifies all client configuration in a single place. In addition to being able to configure authentication using Elytron as described in the previous section, a wildfly-config.xml file can also be used to:

Configure EJB client connections, global interceptors, and invocation timeout

Schema location: https://github.com/wildfly/jboss-ejb-client/blob/4.0.2.Final/src/main/resources/schema/wildfly-client-ejb_3_0.xsd

Example configuration:

wildfly-config.xml

<configuration>
...
    <jboss-ejb-client xmlns="urn:jboss:wildfly-client-ejb:3.0">
        <invocation-timeout seconds="10"/>
        <connections>
            <connection uri="remote+http://10.20.30.40:8080"/>
        </connections>
        <global-interceptors>
            <interceptor class="org.jboss.example.ExampleInterceptor"/>
        </global-interceptors>
    </jboss-ejb-client>
...
</configuration>

Configure HTTP client

Schema location:https://github.com/wildfly/wildfly-http-client/blob/1.0.2.Final/common/src/main/resources/schema/wildfly-http-client_1_0.xsd

Example configuration:

wildfly-config.xml

<configuration>
...
    <http-client xmlns="urn:wildfly-http-client:1.0">
        <defaults>
            <eagerly-acquire-session value="true" />
            <buffer-pool buffer-size="2000" max-size="10" direct="true" thread-local-size="1" />
        </defaults>
    </http-client>
...
</configuration>

Configure a remoting endpoint

Schema location:https://github.com/jboss-remoting/jboss-remoting/blob/5.0.1.Final/src/main/resources/schema/jboss-remoting_5_0.xsd

Example configuration:

wildfly-config.xml

<configuration>
...
    <endpoint xmlns="urn:jboss-remoting:5.0">
        <connections>
            <connection destination="remote+http://10.20.30.40:8080" read-timeout="50" write-timeout="50" heartbeat-interval="10000"/>
        </connections>
    </endpoint>
...
</configuration>

Configure the default XNIO worker

Schema location:https://github.com/xnio/xnio/blob/3.5.1.Final/api/src/main/resources/schema/xnio_3_5.xsd

Example configuration:

wildfly-config.xml

<configuration>
...
    <worker xmlns="urn:xnio:3.5">
        <io-threads value="10"/>
        <task-keepalive value="100"/>
        <stack-size value="5000"/>
    </worker>
...
</configuration>

Note that WildFly client libraries do have reasonable default configuration. Thus, adding configuration for these clients to wildfly-config.xml isn’t mandatory.

Couldn't find a page to include called: KeyCloak Integration