[id='property-security-realms_{context}']
= Property realms
Property realms use property files to define users and groups.

* `users.properties` contains {brandname} user credentials.
Passwords can be pre-digested with the `DIGEST-MD5` and `DIGEST` authentication mechanisms.
* `groups.properties` associates users with roles and permissions.

.users.properties
[source,options="nowrap",subs=attributes+]
----
include::properties/server_users.properties[]
----

.groups.properties
[source,options="nowrap",subs=attributes+]
----
include::properties/server_groups.properties[]
----

[discrete]
== Property realm configuration

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

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

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

== Property realm file structure

User properties files are structured as follows:

.users.properties structure
[source,options="nowrap",subs=attributes+]
----
include::properties/server_users_structure.properties[]
----

The first three lines are special comments that define the name of the realm (`$REALM_NAME`), whether the passwords are
stored in `clear` or `encrypted` format (`$ALGORITHM`) and the timestamp of the last update.

User credentials are stored in traditional key/value format: the key corresponds to the username and the value
corresponds to the password. Encrypted passwords are represented as semi-colon-separated algorithm/hash pairs, with the
hash encoded in Base64.

[WARN]
====
Credentials are encrypted using the realm name. Changing a realm's name requires re-encrypting all the passwords.
Use the {brandname} CLI to enter the correct security realm name to the file.
====
