[[Security_Realms_Detailed_Configuration]]
= Detailed Configuration

This section of the documentation describes the various configuration
options when defining realms, plug-ins are a slightly special case so
the configuration options for plug-ins is within it's own section.

Within a security realm definition there are four optional elements
`<plug-ins />`, `<server-identities />`, `<authentication />`, and
`<authorization />`, as mentioned above plug-ins is defined within it's
own section below so we will begin by looking at the
`<server-identities />` element.

[[server-identities]]
== <server-identities />

The server identities section of a realm definition is used to define
how a server appears to the outside world, currently this element can be
used to configure a password to be used when establishing a remote
outbound connection and also how to load a X.509 key which can be used
for both inbound and outbound SSL connections.

[[ssl]]
=== <ssl />

[source,xml,options="nowrap"]
----
<server-identities>
  <ssl protocol="...">
    <engine enabled-protocols="..."/>
    <keystore path="..." relative-to="..." keystore-password="..." alias="..." key-password="..." />
  </ssl>
</server-identities>
----

* *protocol* - By default this is set to TLS and in general does not
need to be set. To make use of OpenSSL, this can be set to `openssl.TLS`.
Other valid values are `openssl.TLSv1.1` and `openssl.TLSv1.2`, which
limit the minimum protocol version to TLSv1.1 and TLSv1.2 respectively.

* *enabled-protocols* - The protocols to enable on the underlying
`SSLEngine`.

*NOTE* When using OpenSSL 1.1.0g or higher, the lowest and highest protocol
versions specified by `enabled-protocols` will be used to set the minimum
and maximum protocol versions on the underlying `SSLEngine`. For example,
if `enabled-protocols` is set to ["TLSv1.0", "TLSv1.2"], the minimum
protocol version will be set to TLSv1.0 and the maximum protocol version
will be set to TLSv1.2.

The SSL element then contains the nested `<keystore />` element, this is
used to define how to load the key from the file based (JKS) keystore.

* *path* (mandatory) - This is the path to the keystore, this can be an
absolute path or relative to the next attribute.
* *relative-to* (optional) - The name of a service representing a path
the keystore is relative to.
* *keystore-password* (mandatory) - The password required to open the
keystore.
* *alias* (optional) - The alias of the entry to use from the keystore -
for a keystore with multiple entries in practice the first usable entry
is used but this should not be relied on and the alias should be set to
guarantee which entry is used.
* *key-password* (optional) - The password to load the key entry, if
omitted the keystore-password will be used instead.
+
[TIP]
====
If you see the error `UnrecoverableKeyException: Cannot recover key` the
most likely cause that you need to specify a `key-password` and possible
even an `alias` as well to ensure only one key is loaded.
====

=== <secret />

[source,xml,options="nowrap"]
----
<server-identities>
  <secret value="..." />
</server-identities>
----

* *value* (mandatory) - The password to use for outbound connections
encoded as Base64, this field also supports a vault expression should
stronger protection be required.

[NOTE]

The username for the outbound connection is specified at the point the
outbound connection is defined.

== <authentication />

The authentication element is predominantly used to configure the
authentication that is performed on an inbound connection, however there
is one exception and that is if a trust store is defined - on
negotiating an outbound SSL connection the trust store will be used to
verify the remote server.

[source,xml,options="nowrap"]
----
<authentication>
  <truststore />
  <local />
  <jaas />
  <ldap />
  <properties />
  <users />
  <plug-in />
</authentication>
----

An authentication definition can have zero or one `<truststore />`, it
can also have zero or one `<local />` and it can also have one of
`<jaas />`, `<ldap />`, `<properties />`, `<users />`, and `<plug-in />`
i.e. the local mechanism and a truststore for certificate verification
can be independent switched on and off and a single username / password
store can be defined.

[[truststore]]
=== <truststore />

[source,xml,options="nowrap"]
----
<authentication>
  <truststore path="..." relative-to="..." keystore-password="..."/>
</authentication>
----

This element is used to define how to load a key store file that can be
used as the trust store within the SSLContext we create internally, the
store is then used to verify the certificates of the remote side of the
connection be that inbound or outbound.

* *path* (mandatory) - This is the path to the keystore, this can be an
absolute path or relative to the next attribute.
* *relative-to* (optional) - The name of a service representing a path
the keystore is relative to.
* *keystore-password* (mandatory) - The password required to open the
keystore.

[NOTE]

Although this is a definition of a trust store the attribute for the
password is `keystore-password`, this is because the underlying file
being opened is still a key store.

[[local]]
=== <local />

[source,xml,options="nowrap"]
----
<authentication>
  <local default-user="..." allowed-users="..." />
</authentication>
----

This element switches on the local authentication mechanism that allows
clients to the server to verify that they are local to the server, at
the protocol level it is optional for the remote client to send a user
name in the authentication response.

* *default-user* (optional) - If the client does not pass in a username
this is the assumed username, this value is also automatically added to
the list of allowed-users.
* *allowed-users* (optional) - This attribute is used to specify a comma
separated list of users allowed to authenticate using the local
mechanism, alternatively ' `*`' can be specified to allow any username
to be specified.

[[jaas]]
=== <jaas />

[source,xml,options="nowrap"]
----
<authentication>
  <jaas name="..." />
</authentication>
----

The jaas element is used to enable username and password based
authentication where the supplied username and password are verified by
making use of a configured jaas domain.

* *name* (mandatory) - The name of the jaas domain to use to verify the
supplied username and password.

[WARNING]

As JAAS authentication works by taking a username and password and
verifying these the use of this element means that at the transport
level authentication will be forced to send the password in plain text,
any interception of the messages exchanged between the client and server
without SSL enabled will reveal the users password.

[[ldap]]
=== <ldap />

[source,xml,options="nowrap"]
----
<authentication>
  <ldap connection="..." base-dn="..." recursive="..." user-dn="...">
    <username-filter attribute="..." />
    <advanced-filter filter="..." />
  </ldap>
</authentication>
----

The ldap element is used to define how LDAP searches will be used to
authenticate a user, this works by first connecting to LDAP and
performing a search using the supplied user name to identity the
distinguished name of the user and then a subsequent connection is made
to the server using the password supplied by the user - if this second
connection is a success then authentication succeeds.

[WARNING]

Due to the verification approach used this configuration causes the
authentication mechanisms selected for the protocol to cause the
password to be sent from the client in plain text, the following Jira
issue is to investigating proxying a Digest authentication with the LDAP
server so no plain text password is needed
https://issues.redhat.com/browse/ELY-296[ELY-296].

* *connection* (mandatory) - The name of the connection to use to
connect to LDAP.
* *base-dn* (mandatory) - The distinguished name of the context to use
to begin the search from.
* *recursive* (optional) - Should the filter be executed recursively?
Defaults to false.
* *user-dn* (optional) - After the user has been found specifies which
attribute to read for the users distinguished name, defaults to ' `dn`'.

Within the ldap element only one of `<username-filter />` or
`<advanced-filter />` can be specified.

[[username-filter]]
==== <username-filter />

This element is used for a simple filter to match the username specified
by the remote user against a single attribute, as an example with Active
Directory the match is most likely to be against the ' `sAMAccountName`'
attribute.

* *attribute* (mandatory) - The name of the field to match the users
supplied username against.

[[advanced-filter]]
==== <advanced-filter />

This element is used where a more advanced filter is required, one
example use of this filter is to exclude certain matches by specifying
some additional criteria for the filter.

* *filter* (mandatory) - The filter to execute to locate the user, this
filter should contain '\{ `0`}' as a place holder for the username
supplied by the user authenticating.

[[security-realms-properties]]
=== <properties />

[source,xml,options="nowrap"]
----
<authentication>
  <properties path="..." relative-to="..." plain-text="..." />
</authentication>
----

The properties element is used to reference a properties file to load to
read a users password or pre-prepared digest for the authentication
process.

* *path* (mandatory) - The path to the properties file, either absolute
or relative to the path referenced by the relative-to attribute.
* *relative-to* (optional) - The name of a path service that the defined
path will be relative to.
* *plain-text* (optional) - Setting to specify if the passwords are
stored as plain text within the properties file, defaults to false.

[NOTE]

By default the properties files are expected to store a pre-prepared
hash of the users password in the form HEX( MD5( username ':' realm ':'
password))

[[users]]
=== <users />

[source,xml,options="nowrap"]
----
<authentication>
  <users>
    <user username="...">
      <password>...</password>
    </user>
  </users>
</authentication>
----

This is a very simple store of a username and password that stores both
of these within the domain model, this is only really provided for the
provision of simple examples.

* *username* (mandatory) - A users username.

The `<password/>` element is then used to define the password for the
user.


== <authorization />

The authorization element is used to define how a users roles can be
loaded after the authentication process completes, these roles may then
be used for subsequent authorization decisions based on the service
being accessed. At the moment only a properties file approach or a
custom plug-in are supported - support for loading roles from LDAP or
from a database are planned for a subsequent release.

[source,xml,options="nowrap"]
----
<authorization>
  <properties />
  <plug-in />
</authorization>
----

=== <properties />

[source,xml,options="nowrap"]
----
<authorization>
  <properties path="..." relative-to="..." />
</authorization>
----

The format of the properties file is `username={ROLES`} where \{
`ROLES`} is a comma separated list of the users roles.

* *path* (mandatory) - The path to the properties file, either absolute
or relative to the path referenced by the relative-to attribute.
* *relative-to* (optional) - The name of a path service that the defined
path will be relative to.

[[outbound-connection]]
== <outbound-connection />

Strictly speaking these are not a part of the security realm definition,
however at the moment they are only used by security realms so the
definition of outbound connection is described here.

[source,xml,options="nowrap"]
----
<management>
  <security-realms />
  <outbound-connections>
    <ldap />
  </outbound-connections>
</management>
----

=== <ldap />

We only support outbound connections to ldap servers for the authentication process.

[source,xml,options="nowrap"]
----
<outbound-connections>
  <ldap name="..." url="..." search-dn="..." search-credential="..." security-realm="..." initial-context-factory="..."
        referrals="..." handles-referrals-for="..." always-send-client-cert="...">
    <properties>
      <property name="..." value="..." />
    </properties>
    <security-credential-reference store="..." alias="..." type="..."  clear-text="..." />
  </ldap>
</outbound-connections>
----

The outbound connections are defined in this section and then referenced
by name from the configuration that makes use of them.

* *name* (mandatory) - The unique name used to reference this
connection.
* *url* (mandatory) - The URL use to establish the LDAP connection.
* *search-dn* (mandatory) - The distinguished name of the user to
authenticate as to perform the searches.
* *search-credential* (optional) - The password required to connect to
LDAP as the search-dn.
* *initial-context-factory* (optional) - Allows overriding the initial
context factory, defaults to ' `com.sun.jndi.ldap.LdapCtxFactory`'
* *referrals* (optional) - The referral handling mode.
** *IGNORE* - Ignore any referrals received.
** *FOLLOW* - Automatically follow any referrals re-using the configuration for this connection.
** *THROW* - Throw an exception is a referral is encountered, this allows an alternative connection to be identified to handle the referral.
* *handles-referrals-for* (optional) - A space separated list of URIs this connection can be used for.
* *always-send-client-cert* (optional) - By default the server's client certificate is not sent whilst verifying the users credential, if this is set to `true` it will always be sent.

The optional `<properties/>` element can be used to specify additional properties to be passed in to the `DirContext` when it is created.

The optional `<security-credential-reference />` can be used to reference a credential stored in a credential store as an alternative to
the `search-credential` attribute.  This element supports the following attributes: -

* *store* (optional) - Reference to the credential store to obtain the search credential from.
* *alias* (optional) - The alias of the credential in the referenced store.
* *type* (optional) - The fully qualified class name of the credential type to obtain from the credential store.
* *clear-text* (optional) - Instead of referencing a credential store this attribute can be used to specify a clear text password.

