[[General_Elytron_Architecture]]
= General Elytron Architecture

ifdef::env-github[]
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]

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

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

[[security-domains]]
== Security Domains

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

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

* NameRewriter

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

* RealmMapper

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

* SecurityRealm

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

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

* RoleDecoder

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

* RoleMapper

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

* PrincipalDecoder

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

* PermissionMapper

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

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

[[sasl-authentication]]
== SASL Authentication

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

The SaslAuthenticationFactory references the following: -

* SecurityDomain

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

* SaslServerFactory

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

* MechanismConfigurationSelector

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

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

[[http-authentication]]
== HTTP Authentication

The HttpAuthenticationFactory is an authentication policy for
authentication using HTTP authentication mechanisms, including the BASIC,
DIGEST, EXTERNAL, FORM, SPNEGO, and CLIENT_CERT mechanisms. In addition to
being a policy, it is also a factory for configured authentication
mechanisms backed by a SecurityDomain.

The HttpAuthenticationFactory references the following:

* SecurityDomain

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

* HttpServerAuthenticationMechanismFactory

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

* MechanismConfigurationSelector

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

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

[[ssl-tls]]
== SSL / TLS

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

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

The SSLContext within Elytron can also reference the following:

* KeyManagers

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

* TrustManagers

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

* SecurityDomain

If an SSLContext is (optionally) configured to reference a
SecurityDomain then verification of a client's certificate can be
performed as an authentication ensuring the appropriate permissions to
Logon are assigned before even allowing the connection to be fully
opened. Additionally, the SecurityIdentity can be established at the time
the connection is opened and used for any invocations over the
connection.

:leveloffset: +1

include::Passwords.adoc[]

:leveloffset: -1
