[id='ldap-realm-principal-rewriting_{context}']
== LDAP realm principal rewriting

Principals obtained by SASL authentication mechanisms such as `GSSAPI`, `GS2-KRB5` and `Negotiate` usually include the domain name, for example `myuser@INFINISPAN.ORG`.
Before using these principals in LDAP queries, it is necessary to transform them to ensure their compatibility.
This process is called rewriting.

{brandname} includes the following transformers:

[horizontal]
case-principal-transformer:: rewrites the principal to either all uppercase or all lowercase. For example `MyUser` would be rewritten as `MYUSER` in uppercase mode and `myuser` in lowercase mode.
common-name-principal-transformer:: rewrites principals in the LDAP Distinguished Name format (as defined by https://www.ietf.org/rfc/rfc4514.txt[RFC 4514]). It extracts the first attribute of type `CN` (commonName). For example, `DN=CN=myuser,OU=myorg,DC=mydomain` would be rewritten as `myuser`.
regex-principal-transformer:: rewrites principals using a regular expression with capturing groups, allowing, for example, for extractions of any substring.

== LDAP principal rewriting configuration reference

[discrete]
== Case principal transformer

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

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

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

[discrete]
== Common name principal transformer

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

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

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

[discrete]
== Regex principal transformer

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

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

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