<commit_before>[[Elytron_Subsystem]]
= 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]]
== Get Started using the Elytron Subsystem

To get started using Elytron, refer to these topics:

* Use the default Elytron components for
<<default-application-authentication-configuration,application>>
and
<<default-management-authentication-configuration,management>>
authentication
* Secure an application with a new identity store stored in a
<<configure-authentication-with-a-filesystem-based-identity-store,filesystem>>
or
<<configure-authentication-with-a-database-identity-store,database>>.
* Set up one-way SSL/TLS for
<<enable-one-way-ssltls-for-applications,applications>>
or the
<<enable-one-way-ssltls-for-the-management-interfaces,management interfaces>>.
* Set up two-way SSL/TLS for
<<enable-two-way-ssltls-in-wildfly-for-applications,applications>>
or the
<<enable-two-way-ssltls-for-the-management-interfaces,management interfaces>>.
* <<create-and-use-a-credential-store,Create a credential store and use it with your SSL/TLS configuration>>.
* <<configure-authentication-with-certificates,Use certificate-based authentication with applications>>.
* <<override-an-applications-authentication-configuration,Override an application's authentication configuration>>
with Elytron authentication.
* <<configure-authentication-with-a-kerberos-based-identity-store, Configure Kerberos authentication for applications>>.
* Secure
<<configure-authentication-with-an-ldap-based-identity-store,applications>>
and the
<<secure-the-management-interfaces-with-a-new-identity-store,management interfaces>> with an LDAP-based identity store.

[[provided-components]]
== Provided components

WildFly Elytron provides a default set of implementations in the
_elytron_ subsystem.

[[factories]]
=== Factories

[cols=",",options="header"]
|=======================================================================
|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]]
=== Principal Transformers

[cols=",",options="header"]
|=======================================================================
|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]]
=== Principal Decoders

[cols=",",options="header"]
|=======================================================================
|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]]
=== Evidence Decoders

[cols=",",options="header"]
|=======================================================================
|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]]
=== Realm Mappers

[cols=",",options="header"]
|=======================================================================
|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]]
=== Realms

[cols=",",options="header"]
|=======================================================================
|Component |Description

|<<aggregate-security-realm, 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-security-realm, 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-security-realm, 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.
|=======================================================================

[[permission-mappers]]
=== Permission Mappers

[cols=",",options="header"]
|=======================================================================
|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]]
=== Role Decoders

[cols=",",options="header"]
|=======================================================================
|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]]
=== Role Mappers

[cols=",",options="header"]
|=======================================================================
|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.
|=======================================================================

[[ssl-components]]
=== SSL Components

[cols=",",options="header"]
|=======================================================================
|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]]
=== Other

[cols=",",options="header"]
|=======================================================================
|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]]
== 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,Using the Elytron
Subsystem>> section.

[cols=",",options="header"]
|=======================================================================
|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 javax.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.

|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*

[source,java,options="nowrap"]
----
/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-mapper" => undefined,
        "aggregate-sasl-server-factory" => undefined,
        "aggregate-security-event-listener" => undefined,
        "authentication-configuration" => undefined,
        "authentication-context" => undefined,
        "caching-realm" => 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" => 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,
        "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-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"
            }<commit_msg>[WFLY-12810] Documentation for Using regex for role in Elytron<commit_after>[[Elytron_Subsystem]]
= 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]]
== Get Started using the Elytron Subsystem

To get started using Elytron, refer to these topics:

* Use the default Elytron components for
<<default-application-authentication-configuration,application>>
and
<<default-management-authentication-configuration,management>>
authentication
* Secure an application with a new identity store stored in a
<<configure-authentication-with-a-filesystem-based-identity-store,filesystem>>
or
<<configure-authentication-with-a-database-identity-store,database>>.
* Set up one-way SSL/TLS for
<<enable-one-way-ssltls-for-applications,applications>>
or the
<<enable-one-way-ssltls-for-the-management-interfaces,management interfaces>>.
* Set up two-way SSL/TLS for
<<enable-two-way-ssltls-in-wildfly-for-applications,applications>>
or the
<<enable-two-way-ssltls-for-the-management-interfaces,management interfaces>>.
* <<create-and-use-a-credential-store,Create a credential store and use it with your SSL/TLS configuration>>.
* <<configure-authentication-with-certificates,Use certificate-based authentication with applications>>.
* <<override-an-applications-authentication-configuration,Override an application's authentication configuration>>
with Elytron authentication.
* <<configure-authentication-with-a-kerberos-based-identity-store, Configure Kerberos authentication for applications>>.
* Secure
<<configure-authentication-with-an-ldap-based-identity-store,applications>>
and the
<<secure-the-management-interfaces-with-a-new-identity-store,management interfaces>> with an LDAP-based identity store.

[[provided-components]]
== Provided components

WildFly Elytron provides a default set of implementations in the
_elytron_ subsystem.

[[factories]]
=== Factories

[cols=",",options="header"]
|=======================================================================
|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]]
=== Principal Transformers

[cols=",",options="header"]
|=======================================================================
|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]]
=== Principal Decoders

[cols=",",options="header"]
|=======================================================================
|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]]
=== Evidence Decoders

[cols=",",options="header"]
|=======================================================================
|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]]
=== Realm Mappers

[cols=",",options="header"]
|=======================================================================
|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]]
=== Realms

[cols=",",options="header"]
|=======================================================================
|Component |Description

|<<aggregate-security-realm, 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-security-realm, 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-security-realm, 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.
|=======================================================================

[[permission-mappers]]
=== Permission Mappers

[cols=",",options="header"]
|=======================================================================
|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]]
=== Role Decoders

[cols=",",options="header"]
|=======================================================================
|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]]
=== Role Mappers

[cols=",",options="header"]
|=======================================================================
|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]]
=== SSL Components

[cols=",",options="header"]
|=======================================================================
|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]]
=== Other

[cols=",",options="header"]
|=======================================================================
|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]]
== 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,Using the Elytron
Subsystem>> section.

[cols=",",options="header"]
|=======================================================================
|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 javax.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.

|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*

[source,java,options="nowrap"]
----
/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-mapper" => undefined,
        "aggregate-sasl-server-factory" => undefined,
        "aggregate-security-event-listener" => undefined,
        "authentication-configuration" => undefined,
        "authentication-context" => undefined,
        "caching-realm" => 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" => 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,
        "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"
            }
{'fraction_non_alphanumeric': 0.14293004899292325, 'fraction_numerical': 0.0007314915623298857, 'mean_word_length': 3.768413367942894, 'pattern_counts': {'":': 0, '<': 75, '<?xml version=': 0, '>': 420, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6983055', 'n_tokens_mistral': 15122, 'n_tokens_neox': 14239, 'n_words': 4990}