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	An HTTP server factory definition where the HTTP server factory is an aggregation of other HTTP 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.
case-principal-transformer	A principal transformer definition where the principal is adjusted to upper or lower case.
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.

Evidence Decoders

Component	Description
x509-subject-alt-name-evidence-decoder	An evidence decoder that derives the principal associated with a certificate chain from an X.509 subject alternative name from the first certificate in the given chain.
x500-subject-evidence-decoder	An evidence decoder that derives the principal associated with a certificate chain from the subject from the first certificate in the given chain.
custom-evidence-decoder	Definition of a custom evidence decoder.
aggregate-evidence-decoder	An evidence decoder that is an aggregation of other evidence decoders. Given evidence, these evidence decoders will be attempted in order until one returns a non-null principal or until there are no more evidence decoders left to try.

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 or more realms, one for the authentication steps and one or more for loading the identity for the authorization steps and aggregating the resulting attributes.
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.
distributed-realm	A security realm definition for authentication and authorization identities distributed between multiple security realms.
failover-realm	A realm definition that is an aggregation of two realms, one for default behaviour and second for cases when first realm is unavailable.
jaas-realm	A security realm definition that uses JAAS configuration file to initialize LoginContext that is used to obtain identities.

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.
source-address-role-decoder	Definition of a RoleDecoder that maps roles based on the IP address of the remote client.
aggregate-role-decoder	A role decoder that is an aggregation of other role decoders. An aggregate role decoder combines the roles obtained using each role decoder.

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
mapped-role-mapper	A role mapper definition for a role mapper that uses configured mapping of role names to map role names.
regex-role-mapper	A role mapper definition for a role mapper that performs a regex matching and maps matching roles with provided pattern. Regex can capture groups that replacement pattern can make use of.

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-manager	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.
trust-manager	A trust manager definition for creating the TrustManager list as used to create an SSL context.
certificate-authority-account	A certificate authority account which can be used to obtain and revoke signed certificates.

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 simple permission mapper that uses the default-permissions permission set to assign the full set of permissions that an identity would require to access any services on the server. For example, the default-permission-mapper mapper uses org.wildfly.extension.batch.jberet.deployment.BatchPermission specified by the default-permissions permission set to assign permission for batch jobs. The batch permissions are start, stop, restart, abandon, and read which aligns with jakarta.batch.operations.JobOperator. The default-permission-mapper mapper also uses org.wildfly.security.auth.permission.LoginPermission specified by the the login-permission permission set to assign the login permission.
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.
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.
applicationSSC	The `applicationSSC` server SSL context can be used to automatically generate a self-signed certificate the first time the HTTPS interface is accessed. This server SSL context should only be used for testing purposes. It should never be used in a production environment.
combined-providers	Is an aggregate provider that aggregates 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,
        "disallowed-providers" => ["OracleUcrypto"],
        "final-providers" => "combined-providers",
        "initial-providers" => undefined,
        "security-properties" => undefined,
        "add-prefix-role-mapper" => undefined,
        "add-suffix-role-mapper" => undefined,
        "aggregate-evidence-decoder" => 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-decoder" => undefined,
        "aggregate-role-mapper" => undefined,
        "aggregate-sasl-server-factory" => undefined,
        "aggregate-security-event-listener" => undefined,
        "authentication-configuration" => undefined,
        "authentication-context" => undefined,
        "caching-realm" => undefined,
        "case-principal-transformer" => undefined,
        "certificate-authority-account" => 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" => undefined,
            "properties" => {"wildfly.sasl.local-user.default-user" => "$local"},
            "protocol" => undefined,
            "sasl-server-factory" => "elytron",
            "server-name" => undefined
        }},
        "constant-permission-mapper" => undefined,
        "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-evidence-decoder" => 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,
        "custom-security-event-listener" => undefined,
        "dir-context" => undefined,
        "file-audit-log" => {"local-audit" => {
            "format" => "JSON",
            "path" => "audit.log",
            "relative-to" => "jboss.server.log.dir",
            "synchronized" => true
        }},
        "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"
            }
        },
        "identity-realm" => {"local" => {
            "attribute-name" => undefined,
            "attribute-values" => undefined,
            "identity" => "$local"
        }},
        "jdbc-realm" => undefined,
        "kerberos-security-factory" => undefined,
        "key-manager" => {
            "applicationKM" => {
                "algorithm" => undefined,
                "alias-filter" => undefined,
                "credential-reference" => {"clear-text" => "password"},
                "generate-self-signed-certificate-host" => "localhost",
                "key-store" => "applicationKS",
                "provider-name" => undefined,
                "providers" => undefined
            }
        }
        "key-store" => {
            "applicationKS" => {
                "alias-filter" => undefined,
                "credential-reference" => {"clear-text" => "password"},
                "path" => "application.keystore",
                "relative-to" => "jboss.server.config.dir",
                "required" => false,
                "provider-name" => undefined,
                "providers" => undefined,
                "type" => "JKS"
            }
        },
        "key-store-realm" => undefined,
        "ldap-key-store" => undefined,
        "ldap-realm" => undefined,
        "logical-permission-mapper" => undefined,
        "logical-role-mapper" => undefined,
        "mapped-regex-realm-mapper" => undefined,
        "mapped-role-mapper" => undefined,
        "mechanism-provider-filtering-sasl-server-factory" => {"elytron" => {
            "enabling" => true,
            "filters" => [{"provider-name" => "WildFlyElytron"}],
            "sasl-server-factory" => "global"
        }},
        "periodic-rotating-file-audit-log" => undefined,
        "permission-set" => {
            "login-permission" => {"permissions" => [{"class-name" => "org.wildfly.security.auth.permission.LoginPermission"}]},
            "default-permissions" => {"permissions" => [
                {
                    "class-name" => "org.wildfly.extension.batch.jberet.deployment.BatchPermission",
                    "module" => "org.wildfly.extension.batch.jberet",
                    "target-name" => "*"
                },
                {
                    "class-name" => "org.wildfly.transaction.client.RemoteTransactionPermission",
                    "module" => "org.wildfly.transaction.client"
                },
                {
                    "class-name" => "org.jboss.ejb.client.RemoteEJBPermission",
                    "module" => "org.jboss.ejb-client"
                }
            ]}
        },
        "policy" => undefined,
        "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" => {
                "argument" => undefined,
                "class-names" => undefined,
                "configuration" => undefined,
                "module" => "org.wildfly.security.elytron",
                "path" => undefined,
                "relative-to" => undefined
            },
            "openssl" => {
                "argument" => undefined,
                "class-names" => undefined,
                "configuration" => undefined,
                "module" => "org.wildfly.openssl",
                "path" => undefined,
                "relative-to" => undefined
            }
        },
        "provider-sasl-server-factory" => {"global" => {"providers" => undefined}},
        "regex-role-mapper" => undefined,
        "regex-principal-transformer" => undefined,
        "regex-validating-principal-transformer" => undefined,
        "sasl-authentication-factory" => {
            "application-sasl-authentication" => {
                "mechanism-configurations" => [
                    {
                        "mechanism-name" => "JBOSS-LOCAL-USER",
                        "realm-mapper" => "local"
                    },
                    {
                        "mechanism-name" => "DIGEST-MD5",
                        "mechanism-realm-configurations" => [{"realm-name" => "ApplicationRealm"}]
                    }
                ],
                "sasl-server-factory" => "configured",
                "security-domain" => "ApplicationDomain"
            },
            "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"
            }
        },
        "security-domain" => {
            "ApplicationDomain" => {
                "default-realm" => "ApplicationRealm",
                "outflow-anonymous" => false,
                "outflow-security-domains" => undefined,
                "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"
                    },
                    {"realm" => "local"}
                ],
                "role-mapper" => undefined,
                "security-event-listener" => undefined,
                "trusted-security-domains" => undefined
            },
            "ManagementDomain" => {
                "default-realm" => "ManagementRealm",
                "outflow-anonymous" => false,
                "outflow-security-domains" => undefined,
                "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,
                "security-event-listener" => undefined,
                "trusted-security-domains" => undefined
            }
        },
        "server-ssl-context" => {
            "applicationSSC" => {
                "authentication-optional" => false,
                "cipher-suite-filter" => "DEFAULT",
                "cipher-suite-names" => undefined,
                "final-principal-transformer" => undefined,
                "key-manager" => "applicationKM",
                "maximum-session-cache-size" => -1,
                "need-client-auth" => false,
                "post-realm-principal-transformer" => undefined,
                "pre-realm-principal-transformer" => undefined,
                "protocols" => undefined,
                "provider-name" => undefined,
                "providers" => undefined,
                "realm-mapper" => undefined,
                "security-domain" => undefined,
                "session-timeout" => -1,
                "trust-manager" => undefined,
                "use-cipher-suites-order" => true,
                "want-client-auth" => false,
                "wrap" => false,
                "ssl-session" => undefined
            }
        },
        "service-loader-http-server-mechanism-factory" => undefined,
        "service-loader-sasl-server-factory" => undefined,
        "simple-permission-mapper" => {"default-permission-mapper" => {
            "mapping-mode" => "first",
            "permission-mappings" => [
                {
                    "principals" => ["anonymous"],
                    "permission-sets" => [{"permission-set" => "default-permissions"}]
                },
                {
                    "match-all" => true,
                    "permission-sets" => [
                        {"permission-set" => "login-permission"},
                        {"permission-set" => "default-permissions"}
                    ]
                }
            ]
        }},
        "simple-regex-realm-mapper" => undefined,
        "simple-role-decoder" => {"groups-to-roles" => {"attribute" => "groups"}},
        "size-rotating-file-audit-log" => undefined,
        "source-address-role-decoder" => undefined,
        "syslog-audit-log" => undefined,
        "token-realm" => undefined,
        "trust-manager" => undefined,
        "x500-attribute-principal-decoder" => undefined,
        "x500-subject-evidence-decoder" => undefined,
        "x509-subject-alt-name-evidence-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=example-http-auth)

For more information on configuring an http-authentication-factory, see configure an http-authentication-factory

SSL/TLS

Undertow can be configured to make use of the applicationSSC server SSL context for testing purposes, as shown below:

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=applicationSSC)
run-batch
reload

The applicationSSC server SSL context references the applicationKM key manager:

/subsystem=elytron/key-manager=applicationKM:read-resource()
{
    "outcome" => "success",
    "result" => {
        "algorithm" => undefined,
        "alias-filter" => undefined,
        "credential-reference" => {"clear-text" => "password"},
        "generate-self-signed-certificate-host" => "localhost",
        "key-store" => "applicationKS",
        "provider-name" => undefined,
        "providers" => undefined
    }
}

When the applicationSSC server SSL context is used by Undertow, a self-signed certificate will automatically be generated the first time the HTTPS interface is accessed if the file that backs the applicationKS key store doesn’t exist. This self-signed certificate will then be persisted to the file that backs the applicationKS key store. The generate-self-signed-certificate-host value, localhost, will be used as the Common Name (CN) value in the generated self-signed certificate. The following messages will appear in the server log file:

13:21:39,197 WARN  [org.wildfly.extension.elytron] (MSC service thread 1-6) WFLYELY01083: KeyStore /wildfly/standalone/configuration/application.keystore not found, it will be auto generated on first use with a self-signed certificate for host localhost
...
13:39:57,152 WARN  [org.wildfly.extension.elytron] (default task-1) WFLYELY01084: Generated self-signed certificate at /wildfly/dist/target/wildfly-21.0.0.Beta1-SNAPSHOT/standalone/configuration/application.keystore. Please note that self-signed certificates are not secure and should only be used for testing purposes. Do not use this self-signed certificate in production.
SHA-1 fingerprint of the generated key is fc:16:cf:bf:de:3a:6d:d6:fe:ec:f9:cd:9d:22:c9:3d:43:d7:e3:57
SHA-256 fingerprint of the generated key is 38:69:00:4e:39:e2:40:e2:ef:b6:95:58:c6:ba:d0:0f:56:c5:7c:5d:fc:d5:c3:b9:b0:94:80:9c:f5:45:9d:40

NOTE To disable the automatic self-signed certificate generation, undefine the generate-self-signed-certificate-host attribute on the applicationKM key manager.

WARNING This self-signed certificate is only intended to be used for testing purposes. This self-signed certificate should never be used in a production environment. For more information on configuring an ssl-context, see Configuring a server SSLContext. For more information on how to easily obtain a signed certificate using the WildFly CLI, see Obtain a signed certificate from Let’s Encrypt.

Default Elytron ApplicationDomain Configuration

The http-authentication-factory can be 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 using WildFly Elytron capabilities.

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",
        "outflow-anonymous" => false,
        "outflow-security-domains" => undefined,
        "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,
        "security-event-listener" => 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",
            "digest-realm-name" => "ManagementRealm"
        }
    }
}

Default Elytron Management CLI Authentication

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

Default jboss-cli.xml

<jboss-cli xmlns="urn:jboss:cli:3.3">
 
    <default-protocol use-legacy-override="true">remote+http</default-protocol>
 
    <!-- The default controller to connect to when 'connect' command is executed w/o arguments -->
    <default-controller>
        <protocol>remote+http</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
RoleMapping Login Module	Configure Authentication with a Mapped Role Mapper
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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Elytron_Subsystem.adoc

Elytron_Subsystem.adoc

Elytron Subsystem

Get Started using the Elytron Subsystem

Provided components

Factories

Principal Transformers

Principal Decoders

Evidence Decoders

Realm Mappers

Realms

Permission Mappers

Role Decoders

Role Mappers

SSL Components

Other

Out of the Box Configuration

Default Application Authentication Configuration

Update WildFly to Use the Default Elytron Components for Application

Default Elytron ApplicationDomain Configuration

Default Management Authentication Configuration

Default Elytron Management HTTP Authentication Configuration

Default Elytron Management CLI Authentication

Comparing Legacy Approaches to Elytron Approaches

Files

Elytron_Subsystem.adoc

Latest commit

History

Elytron_Subsystem.adoc

File metadata and controls

Elytron Subsystem

Get Started using the Elytron Subsystem

Provided components

Factories

Principal Transformers

Principal Decoders

Evidence Decoders

Realm Mappers

Realms

Permission Mappers

Role Decoders

Role Mappers

SSL Components

Other

Out of the Box Configuration

Default Application Authentication Configuration

Update WildFly to Use the Default Elytron Components for Application

Default Elytron ApplicationDomain Configuration

Default Management Authentication Configuration

Default Elytron Management HTTP Authentication Configuration

Default Elytron Management CLI Authentication

Comparing Legacy Approaches to Elytron Approaches