[id='aggregate-security-realms_{context}']
= Aggregate security realms

Aggregate realms combine multiple realms: the first one for the authentication steps and the others for loading the identity for the authorization steps.
For example, this can be used to authenticate users via a client certificate, and retrieve identity from a properties or LDAP realm.

[discrete]
== Aggregate realm configuration

.XML
[source,xml,options="nowrap",subs=attributes+,role="primary"]
----
include::xml/server_aggregate_realm.xml[]
----

.JSON
[source,json,options="nowrap",subs=attributes+,role="secondary"]
----
include::json/server_aggregate_realm.json[]
----

.YAML
[source,yaml,options="nowrap",subs=attributes+,role="secondary"]
----
include::yaml/server_aggregate_realm.yaml[]
----

== Name rewriters

Principal names may have different forms, depending on the security realm type:

* Properties and Token realms may return simple strings
* Trust and LDAP realms may return X.500-style distinguished names
* Kerberos realms may return `user@domain`-style names

Names must be normalized to a common form when using the aggregate realm using one of the following transformers.

=== Case Principal Transformer

The `case-principal-transformer` transforms a name to all uppercase or all lowercase letters.

.XML
[source,xml,options="nowrap",subs=attributes+,role="primary"]
----
include::xml/server_case_principal_transformer.xml[]
----

.JSON
[source,json,options="nowrap",subs=attributes+,role="secondary"]
----
include::json/server_case_principal_transformer.json[]
----

.YAML
[source,yaml,options="nowrap",subs=attributes+,role="secondary"]
----
include::yaml/server_case_principal_transformer.yaml[]
----

=== Common Name Principal Transformer

The `common-name-principal-transformer` extracts the first `CN` element from a `DN` used by LDAP or Certificates.
For example, given a principal in the form `CN=app1,CN=serviceA,OU=applications,DC=infinispan,DC=org`, the following
configuration will extract `app1` as the principal.

.XML
[source,xml,options="nowrap",subs=attributes+,role="primary"]
----
include::xml/server_common_name_principal_transformer.xml[]
----

.JSON
[source,json,options="nowrap",subs=attributes+,role="secondary"]
----
include::json/server_common_name_principal_transformer.json[]
----

.YAML
[source,yaml,options="nowrap",subs=attributes+,role="secondary"]
----
include::yaml/server_common_name_principal_transformer.yaml[]
----

=== Regex Principal Transformer

The `regex-principal-transformer` can perform find and replace using a regular expression.
The example shows how to extract the local-part from a `user@domain.com` identifier.

.XML
[source,xml,options="nowrap",subs=attributes+,role="primary"]
----
include::xml/server_regex_principal_transformer.xml[]
----

.JSON
[source,json,options="nowrap",subs=attributes+,role="secondary"]
----
include::json/server_regex_principal_transformer.json[]
----

.YAML
[source,yaml,options="nowrap",subs=attributes+,role="secondary"]
----
include::yaml/server_regex_principal_transformer.yaml[]
----

